GM dashboard

The optional top-level dashboard block declares metrics — labeled values aggregated from live player state — that the GM web renders on the Game tab. It’s how a GM watches a game’s progress at a glance: live standings, totals, or per-team rows that update each tick.

It’s fully data-driven and game-agnostic. The engine never interprets a metric; on createWorld it just mirrors the dashboard spec onto the world. The GM web reads each metric, aggregates over the current players, and renders the values. Metrics are pure data — a label, an aggregation, and a state key.

dashboard

interface Dashboard {
  metrics: DashboardMetric[];
}

interface DashboardMetric {
  label: string;                          // display label, e.g. "Treasure banked"
  agg: "sum" | "count" | "max" | "min" | "avg";
  key?: string;                           // player.state key to read; required for every agg except "count"
  where?: { key: string; value: unknown }; // only include players whose state[key] === value
  groupBy?: "team" | "none";              // "team" → one row per team; "none" (default) → single total
}

Fields

• label — the display name shown next to the value, e.g. "Treasure banked".
• agg — how the per-player numbers are combined:
  • sum, max, min, avg — reduce over Number(state[key]) across the included players.
  • count — ignores key and counts the players that pass where.
• key — the Player.state key to read. Required for every agg except count (which counts players rather than reading a value).
• where — an optional filter. Only players whose state[key] === value are included in the aggregation. Omit it to include every player.
• groupBy — how rows are emitted:
  • "team" — one value per team, aggregated over that team’s players, rendered as per-team rows with each team’s color.
  • "none" (the default) — a single value aggregated over all players.

Example

Pirate’s Booty ships the first dashboard: each crew’s banked loot is the sum of score across its pirates, grouped by team so the Game tab shows live standings.

dashboard:
  metrics:
    - { label: "Treasure banked", key: score, agg: sum, groupBy: team }

Source: apps/wage-engine/src/games/pirates_booty/game.yaml.

Behavior

• Aggregates over all player kinds. Human, bot, and demo players all feed the numbers, so a demo-only preview (no phones connected) still reads correctly.
• Shown whenever a game is loaded. The section renders on the GM web’s Game tab during setup, while running or paused, and after the game ends.
• No dashboard, no section. Rulesets that don’t declare a dashboard simply show nothing — the panel is hidden for them.

See also

• Top-level ruleset — where dashboard is indexed alongside the other ruleset blocks.
• Running a game as GM — the GM web’s Game tab in context.