A player's settings: which keys do what, whether the pointer steers, how loud things
are, how the world is drawn (display, and drawing: on the graphics card or not), and
the game's own options (Cauldron2D.Client.Game's
options/0, its defaults under whatever was saved), and which player each game
controller plays: pads, a map from a controller's name to a player number or :none
(Cauldron2D.Drafter.Client.Controllers). controllers lists the controllers
connected now, each %{name, player}; the client keeps it up to date for the game's
menus to show, and it is not saved.
Kept per kind of client — the terminal, a desktop, a browser, a phone: a kind is any
atom, :terminal the default — on disk under
$XDG_CONFIG_HOME/<game>/<player>.settings for the terminal and
<player>.<kind>.settings for another kind, <game> being the game's title in lower
case with runs of other characters as _ (or under ~/.config), and, when the
player has an account, in its props as well: settings for the terminal,
settings_<kind> for another kind. load/4 reads the file over any account props;
save/5 writes both.
settings = Cauldron2D.Drafter.Client.Settings.load(MyGame.Client, "alice", account_props)
settings.bindings[:launch]
Cauldron2D.Drafter.Client.Settings.load(MyGame.Client, "alice", account_props, kind: :desktop)Summary
Types
How the world is drawn: pixels where the terminal has them, else glyphs; braille; block characters of a glyph set; or glyphs.
Where a game that can be drawn by the graphics card is drawn: :auto on the card in the
pane when there is one, :software never on the card, :pane on the card in the pane,
:window on the card in a window of its own.
Frames per second, or :auto for the terminal's best.
One line of the settings screen: the preset, an action's binding, or a switch or level.
Functions
Add key to what action is bound to, after the keys it has; a key already there is not added twice.
Switch to preset of game, dropping individual rebindings.
The frame rate to draw at: the setting, or for :auto the terminal's best — 12 where
every frame is an inline image (iTerm2's own, sixel), 20 where every frame is a kitty
picture sent whole (a terminal without placements) or the session is served over ssh
(link :ssh), 30 elsewhere.
The frame rates the settings screen offers: the game's frame_rates/0, else :auto, 15, 30, 50 and 60.
The settings screen's items for game, top to bottom; :drawing is there when the
build has the graphics card renderer (cauldron_gpu).
The keys bound to action, as text for a screen.
Settings for player of game on a :kind of client (default :terminal): the file on disk over account_props over the defaults.
Settings for game with overrides applied over the game's first preset.
Move a 0.0–1.0 level by delta, clamped.
Where player's settings for game live, for a kind of client (default :terminal).
The presets in the order the settings screen offers them: the game's keymaps/0 order for a keyword list, by name for a map.
The account prop a kind's settings are kept under: :settings for the terminal, :settings_<kind> for another.
Bind action to key alone, in place of whatever it had.
Write the settings to disk, and to the account when accounts is given, for a :kind of client (default :terminal).
The next or previous display choice, in the order auto, braille, half, quad, sextant, octant, glyphs, wrapping.
The next or previous drawing choice, in the order auto, software, pane, window, wrapping.
The next or previous frame rate choice of game's frame_rates/1, wrapping.
The surface mode for the display setting: nil lets the terminal decide.
The map kept in account props and on disk.
Drop the last key action is bound to; an action with no keys is unchanged.
Types
@type display() :: :auto | :braille | :half | :quad | :sextant | :octant | :glyphs
How the world is drawn: pixels where the terminal has them, else glyphs; braille; block characters of a glyph set; or glyphs.
@type drawing() :: :auto | :software | :pane | :window
Where a game that can be drawn by the graphics card is drawn: :auto on the card in the
pane when there is one, :software never on the card, :pane on the card in the pane,
:window on the card in a window of its own.
@type fps() :: :auto | pos_integer()
Frames per second, or :auto for the terminal's best.
@type item() :: :preset | {:action, Cauldron2D.Input.action()} | :pointer | :sfx | :music | :display | :drawing | :fps
One line of the settings screen: the preset, an action's binding, or a switch or level.
@type t() :: %Cauldron2D.Drafter.Client.Settings{ bindings: Cauldron2D.Input.keymap(), controllers: [%{name: String.t(), player: pos_integer() | nil}], display: display(), drawing: drawing(), fps: fps(), music: float(), options: map(), pads: %{required(String.t()) => pos_integer() | :none}, pointer: boolean(), preset: atom(), sfx: float() }
Functions
@spec bind(t(), Cauldron2D.Input.action(), Cauldron2D.Input.key_spec()) :: t()
Add key to what action is bound to, after the keys it has; a key already there is not added twice.
Switch to preset of game, dropping individual rebindings.
@spec frame_rate(t(), atom() | nil | :unprobed, boolean(), :local | :ssh) :: pos_integer()
The frame rate to draw at: the setting, or for :auto the terminal's best — 12 where
every frame is an inline image (iTerm2's own, sixel), 20 where every frame is a kitty
picture sent whole (a terminal without placements) or the session is served over ssh
(link :ssh), 30 elsewhere.
The frame rates the settings screen offers: the game's frame_rates/0, else :auto, 15, 30, 50 and 60.
The settings screen's items for game, top to bottom; :drawing is there when the
build has the graphics card renderer (cauldron_gpu).
@spec keys_text(t(), Cauldron2D.Input.action()) :: String.t()
The keys bound to action, as text for a screen.
Settings for player of game on a :kind of client (default :terminal): the file on disk over account_props over the defaults.
Settings for game with overrides applied over the game's first preset.
An override naming a preset the game no longer has starts from the first preset, and its bindings are dropped with it.
Move a 0.0–1.0 level by delta, clamped.
Where player's settings for game live, for a kind of client (default :terminal).
The presets in the order the settings screen offers them: the game's keymaps/0 order for a keyword list, by name for a map.
The account prop a kind's settings are kept under: :settings for the terminal, :settings_<kind> for another.
@spec rebind(t(), Cauldron2D.Input.action(), Cauldron2D.Input.key_spec()) :: t()
Bind action to key alone, in place of whatever it had.
@spec save(t(), module(), String.t(), GenServer.server() | nil, keyword()) :: :ok
Write the settings to disk, and to the account when accounts is given, for a :kind of client (default :terminal).
The next or previous display choice, in the order auto, braille, half, quad, sextant, octant, glyphs, wrapping.
The next or previous drawing choice, in the order auto, software, pane, window, wrapping.
The next or previous frame rate choice of game's frame_rates/1, wrapping.
@spec surface_mode(t()) :: nil | :braille | :half | :quad | :sextant | :octant | :text
The surface mode for the display setting: nil lets the terminal decide.
The map kept in account props and on disk.
@spec unbind_last(t(), Cauldron2D.Input.action()) :: t()
Drop the last key action is bound to; an action with no keys is unchanged.