GamePreference

Methods

.define(tag, registry)

.set(value)

.toggle()

Events

game-preference-change GamePreferenceChangeEvent

A self-sufficient preference element. Owns its current value, persists to localStorage, and auto-wires hardwired audio keys. Works standalone anywhere inside a <game-shell>, or as a child of <game-preferences> for a full settings panel.

Boolean preferences have default="true" or default="false". Numeric preferences have a numeric default plus min/max. The type is inferred from the default attribute -- there is no type attribute.

Attributes

key

string -- The preference key, used for persistence, auto-wiring, and .get(key) on the parent panel.

label

string -- Display label shown next to the input when inside a <game-preferences> panel.

default

string -- Default value. "true" or "false" for boolean preferences, a numeric string for range preferences. Determines the value type and the initial value before any persisted value is loaded.

min

string -- Minimum value for numeric preferences. Default: "0".

max

string -- Maximum value for numeric preferences. Default: "100".

Properties

.value

get -- The current value. Returns boolean for boolean preferences, number for numeric, or string otherwise. Before connection, returns the parsed default.

.boolean

get -- true if the default attribute is "true" or "false", indicating a boolean preference.

Methods

.set(value)

Set the preference value. Persists to localStorage, applies auto-wiring (see below), and dispatches a game-preference-change event.

const pref = document.querySelector('game-preference[key="sound"]');
pref.set(false); // mute

.toggle()

For boolean preferences, flips the current value. Equivalent to pref.set(!pref.value). No-op for non-boolean preferences.

pref.toggle(); // true -> false, or false -> true

Auto-Wiring

The following preference keys are auto-wired to built-in components when the value changes or when the element connects:

Persistence

Preferences are stored as a JSON object in localStorage under the key {game-id}-preferences, where game-id comes from the nearest shell's game-id attribute (falling back to storage-key). On connection, the stored value is loaded and applied.

Events Dispatched

game-preference-change

Dispatched from the preference element whenever .set() or .toggle() is called. Carries .key and .value. Bubbles to the shell (composed: true).

Standalone Usage

A <game-preference> can be placed directly inside a <game-shell> without a <game-preferences> parent. This is useful for a mute toggle that lives outside the settings panel:

<game-shell id="game" game-id="my-game" sprite-sheet="/icons.svg">
  <game-preference key="sound" default="true"></game-preference>
  <button commandfor="game" command="--toggle-mute" aria-label="Toggle sound">
    <game-icon name="volume-2">
      <option when-some-muted value="volume-x"></option>
    </game-icon>
  </button>
  <!-- rest of game -->
</game-shell>

The shell's --toggle-mute command finds the <game-preference key="sound"> and calls .toggle().

Inside a Preferences Panel

When placed inside <game-preferences>, the parent renders a toggle switch or range slider based on .boolean and delegates value changes to the child element. See <game-preferences>.

CSS Custom Properties

When inside <game-preferences>, the panel uses --game-btn-bg, --game-btn-text, --game-text, and --game-accent for styling.