GamePreferences

Methods

.get(key)

.define(tag, registry)

.subscribe(context, callback)

A declarative preferences panel for common game settings. Uses the native popover API for overlay behavior and command/commandfor to open — zero JavaScript needed for the open/close flow. Add the popover attribute so it works as a native popover, and give it an id so buttons can target it with commandfor.

Methods

.get(key)

Get the current value of a preference by key.

const prefs = document.querySelector("game-preferences");
const soundEnabled = prefs.get("sound"); // true or false
const volume = prefs.get("volume"); // 0-100

Events Dispatched

game-preference-change

Dispatched whenever a preference value changes. Carries .key and .value. Bubbles to the shell.

shell.addEventListener("game-preference-change", (e) => {
  if (e.key === "dark-mode") {
    document.body.classList.toggle("dark", e.value);
  }
});

Auto-Wiring

The following preference keys are auto-wired to built-in components:

All other keys (e.g. dark-mode) dispatch game-preference-change events for your game code to handle.

Persistence

Preferences are stored as a JSON object in localStorage under the key {game-id}-preferences, where game-id comes from the shell's game-id attribute. If game-id is absent, falls back to storage-key. Loaded on connection.

Context Subscriptions

None — preferences are independent of game state.

Usage

<game-shell id="game" game-id="my-game">
  <div when-some-scene="intro" data-overlay>
    <h1>My Game</h1>
    <button commandfor="prefs" command="show-popover">Settings</button>
    <button commandfor="game" command="--start">Play</button>
  </div>

  <game-preferences id="prefs" popover>
    <game-preference type="toggle" key="sound" label="Sound" default="true">
    </game-preference>
    <game-preference
      type="toggle"
      key="vibration"
      label="Vibration"
      default="true"
    >
    </game-preference>
    <game-preference
      type="range"
      key="volume"
      label="Volume"
      min="0"
      max="100"
      default="80"
    >
    </game-preference>
    <game-preference
      type="toggle"
      key="dark-mode"
      label="Dark Mode"
      default="false"
    >
    </game-preference>
  </game-preferences>

  <!-- rest of game -->
</game-shell>

The settings button opens the preferences panel using the native show-popover command — no JavaScript required.