@livlive/game 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @livlive/game
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The types of the livlive game contract: what a stage's rules may know of the engine — the shapes that cross the box, the functions the
+box calls (`Game<S>`), and `keeper.json`'s declaration (`GameManifest`).
+
+A game takes it with `import type` only (`import type { Game } from "@livlive/game";`). The package carries no code: a value import is
+refused when the rules are built.
+
+`index.d.ts` is generated from the engine's contract by livlive-backstage's `gen:engine` — never edit it here. The engine reference
+(`../reference/engine.json`) says when each function is called and what goes in and out.

package/index.d.ts

@@ -0,0 +1,252 @@
+// Generated by livlive-backstage gen:engine from app/src/contracts/game — do not edit.
+/** the contract's version: the engine opens a game only at a version it knows */
+export declare const GAME_PROTOCOL: 1;
+/** a setting's value — a number, a yes/no or words */
+export type SettingValue = number | boolean | string;
+/** ★a setting a game declares★ (spec §4 — owner 2026-11-03 「ステージのページで設定出来るようにしてほしいです。…固定の画面ではダメです。」
+    「デフォルト設定という形です。」): what the stage page asks (`words`, the game's own, ≤ 40 characters), its kind and bounds, and the value it
+    has until a stage sets one (`default`, within its own bounds). integer: min ≤ default ≤ max on `step` (1 if absent) from min; number: within
+    min…max; choice: one of its options' values (two or more); text: at most `max` characters (1–200) */
+export type SettingSpec = {
+    words: string;
+} & ({
+    type: "integer";
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+} | {
+    type: "number";
+    default: number;
+    min: number;
+    max: number;
+} | {
+    type: "boolean";
+    default: boolean;
+} | {
+    type: "choice";
+    default: string;
+    options: {
+        value: string;
+        words: string;
+    }[];
+} | {
+    type: "text";
+    default: string;
+    max: number;
+});
+/** the stage as a game sees it: its id, its seats and its things with their words, and its settings — every name the game declares with
+    the stage's value, the default where the stage set none */
+export type StageView = {
+    id: string;
+    seats: {
+        id: string;
+    }[];
+    objects: {
+        id: string;
+        name: string;
+        about: string;
+        can: string[];
+    }[];
+    settings: Readonly<Record<string, SettingValue>>;
+};
+/** the show's moment as a game is given it (ms) */
+export type GameTime = {
+    t: number;
+    tick: number;
+    dt: number;
+};
+/** an event the stage declares, asked for at its door this tick, and who asked */
+export type GameTrigger = {
+    event: string;
+    by?: string;
+};
+/** a hand of hers this tick: a done that says how the things she touched stand now (by thing id) */
+export type GameHand = {
+    t: number;
+    who: string;
+    changed: Record<string, Record<string, unknown>>;
+};
+/** an act of hers that finished well this tick — a game reads the ones it owns (its moves) */
+export type GamePlayed = {
+    t: number;
+    who: string;
+    type: string;
+    target: string | null;
+    mode: string | null;
+    direction: string | null;
+};
+/** what reached the stage since the game was last woken */
+export type GameInput = {
+    time: GameTime;
+    triggers: readonly GameTrigger[];
+    hands: readonly GameHand[];
+    acts: readonly GamePlayed[];
+    /** the players, in seat order — every performer, or the first `players.max` when keeper.json says how many play (below `players.min` the
+        game is not opened at all); `hands`, `acts` and `seats` are theirs alone */ cast: readonly string[];
+    /** where each player sits now — a seat id; null standing */ seats: Readonly<Record<string, string | null>>;
+};
+/** what a step came to — the engine's own keepers': what happened, how the room's things stand, its news, its events. A stage's own game answers
+    it empty: the box keeps its `state` and reads nothing else of the answer, so a game cannot move the room's things (GAME_CONTRACT's `step`) */
+export type GameOutcome = {
+    happenings: readonly unknown[];
+    things: Readonly<Record<string, unknown>>;
+    news: unknown;
+    events: unknown;
+};
+/** an act a character's menu offers, as `check` is asked about it */
+export type CheckAsk = {
+    type: string;
+    target: string | null;
+    mode?: string | null;
+    direction?: string | null;
+    who?: string;
+};
+/** ★a row a game offers her★ — what it asks, in her words, how long it takes (s); `at` the seats she must sit in for it (absent:
+    anywhere); `due` it is hers to do now — her menu then holds only the due rows */
+export type OfferRow = {
+    id: string;
+    act: {
+        type: string;
+        target?: string;
+        mode?: string;
+    };
+    words: string;
+    s: number;
+    at?: readonly string[];
+    due?: boolean;
+};
+/** a card a tile may show — its rank (1–5 characters) and suit, or a joker (suit null) */
+export type BoardCard = {
+    rank: string;
+    suit: "♠" | "♥" | "♦" | "♣" | null;
+};
+/** a board's tile: its words, marked, the card it shows, and the one just moved */
+export type BoardTile = {
+    text: string;
+    mark?: boolean;
+    card?: BoardCard;
+    fresh?: boolean;
+};
+/** a row's gauge and its number: `value` (finite, ≥ 0) of `of` (finite, > 0) — any game's own measure: a stack, a score, a life */
+export type BoardMeter = {
+    value: number;
+    of: number;
+};
+/** a short fact a row shows (a label and a value, ≤ 8 characters each — one code point a character) */
+export type BoardFact = {
+    label: string;
+    value: string;
+};
+/** the board's middle slot: a label, a big value (≤ 8 characters each) and a line under them (≤ 24) */
+export type BoardCenter = {
+    label: string;
+    value: string;
+    line?: string;
+};
+/** a row's last move, which the board plays once (its `key` new for each move, ≤ 32 characters): push (a bet, a raise), answer (a call, a
+    check), fold, draw (cards changed); its words (≤ 8 characters) and what it put (finite, ≥ 0) */
+export type BoardAct = {
+    key: string;
+    kind: "push" | "answer" | "fold" | "draw";
+    words: string;
+    amount?: number;
+};
+/** what just happened to the board as a whole, played once a show (its `key` new for each moment, ≤ 32 characters): the cards dealt, the hands
+    shown, a round won, the game over — `who` the row it is about (one of the view's rows, or the view is wrong and the game stops). A `win`
+    or an `end` with a `who` is a win: the camera goes to that player and back (when they are in the picture) and every character of the cast
+    is told of it, the winner as their own win (a winner who is none of the cast is told to nobody); an `end` with none is a draw — no camera,
+    no telling. `deal` and `reveal` never move the camera. `end` is the game over: keep it in every later view — a view without it brings the
+    table back */
+export type BoardMoment = {
+    key: string;
+    kind: "deal" | "reveal" | "win" | "end";
+    who?: string;
+};
+/** ★what the viewers see of a game★ (the board over the picture): rows of tiles, one row a player (`who`), the one to move marked, a note;
+    a row may say one short line under the player's name (`sub`, ≤ 24 characters — any game's own words: a score, a stack, a role), a gauge
+    (`meter`) and up to four short facts (`facts`); the view may say its middle slot (`center`) — every one of them optional. Three or four
+    rows are drawn as a table seen from above, each player's face in a circle at their side, while the game is on (its view does not
+    say `end`) and no win holds the camera: the table is then the whole picture — the room and the bodies are not shown. A win's hold, the
+    game's end and any other number of rows draw strips instead, over the room's picture with the bodies in it (livlive's standard look;
+    in app delivery — each character a small picture of its own — no board is drawn). The table draws the tiles, the
+    middle slot, the names, `sub` and `won` — not `meter`, `facts`, `act` or `danger`, nor a moment's effects (its sound still plays): keep
+    what viewers must read in the tiles, `center` or `sub`. `won` draws the row's WIN mark, on a strip and on the table; a row's `won` turning
+    true is a win, as a moment is (BoardMoment) — one win a view (the moment's, else the first such row), every won row still marked. The
+    table marks by `won` alone: a win told by a moment alone gets the camera and the telling, but no mark there */
+export type BoardView = {
+    title: string;
+    rows: {
+        who: string;
+        turn: boolean;
+        tiles: BoardTile[];
+        sub?: string;
+        meter?: BoardMeter;
+        facts?: BoardFact[];
+        act?: BoardAct;
+        danger?: boolean;
+        won?: boolean;
+    }[];
+    note: string;
+    center?: BoardCenter;
+    moment?: BoardMoment;
+};
+/** when a game asks to be woken by time: once at `at` (the show's ms), or every `every` ms */
+export type Alarm = {
+    at: number;
+} | {
+    every: number;
+};
+/** how an act a game owns is carried out — `reach`: she walks to the thing and reaches; `here`: where she is — for `ms`; `motion` the
+    basic motion it needs */
+export type ActSpec = {
+    controller: "reach" | "here";
+    ms: number;
+    motion: string;
+};
+/** ★how many of a show's performers play a game★ (plan 2026-11-05-four-players-1 Task 4): the fewest and the most, whole numbers,
+    1 ≤ min ≤ max ≤ the cast's cap (the engine reference states the number; keeper.json's check holds it) */
+export type GamePlayers = {
+    min: number;
+    max: number;
+};
+/** keeper.json — what a game declares beside its rules: its id (its questions are named `<id>.<name>`), its version, the acts it owns,
+    the questions its `ask` may name, the settings a stage may set and how many play */
+export type GameManifest = {
+    id: string;
+    version: string;
+    acts?: Record<string, ActSpec>;
+    questions?: Record<string, {
+        instructions: string;
+        threshold?: number;
+        default?: string;
+    }>;
+    settings?: Record<string, SettingSpec>;
+    /** the keeper protocol it was made for; 1 when absent (a stage made today keeps running — plan 2026-11-04-stage-kit-1 Task 4) */ protocol?: number;
+    /** how many play; absent: the game decides in code, and every performer is a player (today's behaviour) */ players?: GamePlayers;
+};
+/** ★the rules' functions, as the box calls them★ — see GAME_CONTRACT for when; `ask` answers a question's short name (keeper.json's) */
+export type Game<S> = {
+    reset(stage: StageView, time: GameTime, seed: string): S;
+    step(state: S, input: GameInput, stage: StageView): {
+        state: S;
+        out: GameOutcome;
+    };
+    check?(type: string, state: S, act: CheckAsk, stage: StageView): string | null;
+    alarm?(state: S): Alarm | null;
+    offers?(state: S, who: string, stage: StageView): OfferRow[];
+    ask?(state: S, who: string, stage: StageView): string | null;
+    still?(state: S, who: string, stage: StageView): boolean;
+    observe?(state: S, who: string, stage: StageView): string[];
+    view?(state: S, stage: StageView): BoardView | null;
+};
+/** ★the contract, in words★ — each function the box calls, when, what goes in and what comes out (the engine reference states it for a
+    person's agent; check:world-format holds it to the box's calls). `facts` and `may` are the engine's own keepers' (engineOnly) */
+export declare const GAME_CONTRACT: readonly {
+    name: string;
+    when: string;
+    in: string;
+    out: string;
+    optional: boolean;
+    engineOnly?: true;
+}[];

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@livlive/game",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The livlive game contract's types — import type only",
+  "license": "MIT",
+  "types": "index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts" } },
+  "files": ["index.d.ts", "README.md"]
+}