Cauldron2D.Drafter.Launcher (Cauldron2D.Drafter v0.3.0)

Copy Markdown View Source

A setup page shown before a game starts. The player picks where the game's data is, how it is drawn, and anything else the game asks. Play saves the choices, and later runs start straight away with them.

fields = [
  %{key: :dir, label: "Quake folder", kind: {:path, &MyGame.check_dir/1}, discover: &MyGame.find_dir/0},
  %{key: :skill, label: "Skill", kind: {:choice, [{0, "easy"}, {1, "normal"}, {2, "hard"}]}, default: 1},
  Cauldron2D.Drafter.Launcher.drawing_field()
]

case Cauldron2D.Drafter.Launcher.choose(MyGame.Client, fields, overrides: %{skill: 2}, player: "ranger") do
  {:ok, values} -> start_the_game(values)
  :quit -> :ok
end

A field is a map:

  • :key — the atom its value is kept under
  • :label — the text shown beside it
  • :kind — {:path, check}, a path the player types, where check takes it and answers :ok or {:error, text}; {:choice, [{value, text}]}, one of a list the player steps through; or :text, any text
  • :default — the value when nothing else gives one (optional)
  • :discover — a function answering a value or nil, tried when nothing is saved (optional; for finding a game's data in the usual places)
  • :hint — a line shown under the field (optional)

choose/3 works out each value from the run's overrides (from command-line flags), then what was saved, then :discover, then :default. It shows the page when nothing has been saved yet, when a path does not pass its check, or when the option launcher: true asks for it. Play saves the values under $XDG_CONFIG_HOME/<game>/launcher.config (or ~/.config), <game> named as Cauldron2D.Drafter.Client.Settings names it. Overrides that skip the page are not saved.

A field with key :drawing (drawing_field/0) is also written into the player's settings (Cauldron2D.Drafter.Client.Settings's drawing) when :player is given, so the page and the game's own options change the same setting.

On the page, ↑ and ↓ move, ← and → change a choice, Enter edits a path or text or presses Play or Quit, and Escape quits.

Summary

Types

field()

Functions

choose(game, fields, opts \\ [])

The values for game's fields, showing the page when it is needed. Options: :overrides (a map of values for this run), :launcher (true shows the page whatever was saved), :player (the player whose settings get the :drawing field), :title (the page's heading, default the game's title).

drawing_field()

The field for how the game is drawn: automatically, in software, or on the graphics card in the terminal or a window.

keybindings()
load(game)

The values saved for game, or an empty map.

on_ready(state)

Callback implementation for Drafter.App.on_ready/1.

on_timer(timer_id, state)

Callback implementation for Drafter.App.on_timer/2.

path(game)

Where game's launcher choices are kept.

save(game, values)

Saves values for game.

show(title, fields, values)

Shows the page with values filled in; answers the values on Play, or :quit.

steam_folders(name)

The folders where Steam keeps the game folder name on this machine, the ones that exist: Steam's own libraries on macOS, Linux (including Flatpak) and Windows, and Steam in CrossOver bottles on macOS. For a field's :discover.

unmount(state)

Callback implementation for Drafter.App.unmount/1.

Types

field()

@type field() :: %{
  :key => atom(),
  :label => String.t(),
  :kind =>
    {:path, (String.t() -> :ok | {:error, String.t()})}
    | {:choice, [{term(), String.t()}]}
    | :text,
  optional(:default) => term(),
  optional(:discover) => (-> term() | nil),
  optional(:hint) => String.t()
}

Functions

choose(game, fields, opts \\ [])

@spec choose(module(), [field()], keyword()) :: {:ok, map()} | :quit

The values for game's fields, showing the page when it is needed. Options: :overrides (a map of values for this run), :launcher (true shows the page whatever was saved), :player (the player whose settings get the :drawing field), :title (the page's heading, default the game's title).

drawing_field()

@spec drawing_field() :: field()

The field for how the game is drawn: automatically, in software, or on the graphics card in the terminal or a window.

keybindings()

load(game)

@spec load(module()) :: map()

The values saved for game, or an empty map.

on_ready(state)

Callback implementation for Drafter.App.on_ready/1.

on_timer(timer_id, state)

Callback implementation for Drafter.App.on_timer/2.

path(game)

@spec path(module()) :: Path.t()

Where game's launcher choices are kept.

save(game, values)

@spec save(module(), map()) :: :ok

Saves values for game.

show(title, fields, values)

@spec show(String.t(), [field()], map()) :: {:ok, map()} | :quit

Shows the page with values filled in; answers the values on Play, or :quit.

steam_folders(name)

@spec steam_folders(String.t()) :: [Path.t()]

The folders where Steam keeps the game folder name on this machine, the ones that exist: Steam's own libraries on macOS, Linux (including Flatpak) and Windows, and Steam in CrossOver bottles on macOS. For a field's :discover.

Cauldron2D.Drafter.Launcher.steam_folders("Half-Life")

unmount(state)

Callback implementation for Drafter.App.unmount/1.