@fabi-play/protocol 0.2.0 → 0.3.0

package/README.md

@@ -74,3 +74,21 @@ from this package.
 ## License
 
 Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).
+
+## The TV remote
+
+A manifest's optional `inputs` (`GameInput[]`, from `GAME_INPUTS`: `body`, `remote`; absent `["body"]`, see
+`gameInputs`) says whether the game can be played with the TV remote when there is no phone; `parseManifest`
+requires `body` in it, no repeats and no unknown values. The screen tells the game how a session is played in
+`init.input` (absent `'body'`) and, with `'remote'`, whether the remote points (`init.pointer`, LG's Magic Remote:
+plain pointer and mouse events in the game's page). The screen turns keys into gestures (↑ or OK `jump`, ↓ held
+`squat`/`stand`, ← → lanes, OK twice `clap`, Back the platform's pause) and plays one child at a time: init's
+`players` is the child playing now (one id). Several children take turns only with games whose manifest says `"turns": true`
+(valid only with `remote` in `inputs`; it means the game follows the turn contract; without it, one child only): `init.turns`
+lists every child in turn order (`parseTurnOrder`; absent: `players`). The game plays a round per child; when a
+child's round ends (a crash too) and turns remain, it asks `break('turn')`, and the screen always answers
+`break-start` (its turn screen), `{ type: 'turn', players: [2] }` (exactly one id, the next in the order;
+`parseTurnPlayers` checks its shape) and `break-done`, the next child's puppet recentred in the middle lane. After
+the last round the game ends with every child's scores. `level` and `gameover` breaks never swap players; hosts
+before turns answer `turn` as an unknown reason, at once. Games keep scores by player id. See "Playing with the TV remote" in the
+[`@fabi-play/sdk` README](https://www.npmjs.com/package/@fabi-play/sdk).

package/dist/index.d.ts

@@ -307,10 +307,15 @@ export declare const wire: <T extends object>(m: T) => Wire<T>;
 /**
  * Why the game stops, when it asks for a break:
  * - level: a level is over (the best moment);
- * - gameover: the game is over and a new one may start.
- * Never at the game's own pause menu: a child who stops for a moment must not get an ad for it.
- */
-export type BreakReason = "level" | "gameover";
+ * - gameover: the game is over and a new one may start;
+ * - turn: with input 'remote' and turns remaining, the child playing now finished their round (whatever happened in
+ *   it: a crash or a fall ends a round too). The screen always answers with break-start (its turn screen is the
+ *   break, and may host an ad), then turn (the next child), then break-done. Hosts before turns answer it as an
+ *   unknown reason (break-done at once), but they never send turns either.
+ * Only 'turn' ever swaps players; 'level' and 'gameover' never do. Never at the game's own pause menu: a child who
+ * stops for a moment must not get an ad for it.
+ */
+export type BreakReason = "level" | "gameover" | "turn";
 export declare const BREAK_REASONS: BreakReason[];
 /**
  * The movements the host recognises, per player:
@@ -366,7 +371,9 @@ export type Backdrop = "video" | "none";
  * image is cropped to fill the screen), with any backdrop, so avatars and hands are where the children stand (a
  * "virtual mirror"). The screen decides it: with 'video', where the video is drawn (cover or contain); with 'none',
  * the whole image contained at 92% of the viewport's height, bottom-aligned. Games don't compute it: they just use
- * it. Body points are in player space (0–1 of the camera image, already mirrored like the video), so a point p is on
+ * it. It is not fixed: with automatic framing (the default, see GameManifest.framing) the screen zooms in on children
+ * standing far away, up to 1.8×, so the image may reach past every edge; it changes only at calibration and in breaks
+ * (pause, level, turn), never during play, and arrives in a backdrop message. Body points are in player space (0–1 of the camera image, already mirrored like the video), so a point p is on
  * screen at (x + p.x·w, y + p.y·h): see toScreen.
  */
 export interface BackdropView {
@@ -418,6 +425,22 @@ export type HostMessage =
 /** view: where the camera image is, with any backdrop (see BackdropView); absent if the screen doesn't know. */
 /** stats: a debug host (the simulator) asks the game to say how often it draws (stats messages); absent on the TV. */
 /** device: what the screen knows about the device (a starting tier, the display's rate); absent if it knows nothing. */
+/**
+ * input: how this session is played (see GameInput); absent = 'body'. Only games whose manifest lists 'remote' ever
+ * get 'remote'. With 'remote', players is exactly one id: the child playing now (see turn).
+ */
+/**
+ * turns: only with input 'remote', and only to games whose manifest says "turns": true: every child who
+ * will play this game, one id each, in turn order, players[0] first (see parseTurnOrder); absent = players (one
+ * child, no turns). A round per child: at the end of each child's round, while turns remain, the game calls
+ * break('turn'); the screen answers break-start, turn (the next child), break-done. After the last child's round
+ * the game calls end() with every child's scores. An order that is not valid, or doesn't start with players[0],
+ * makes the session one child only.
+ */
+/**
+ * pointer: only with input 'remote', true when the TV's remote also points (LG's Magic Remote): it reaches the game
+ * as ordinary pointer and mouse events (hover, click with OK). Absent = false.
+ */
 {
 	type: "init";
 	v: number;
@@ -430,8 +453,11 @@ export type HostMessage =
 	view?: BackdropView;
 	stats?: boolean;
 	device?: DeviceHint;
+	input?: GameInput;
+	turns?: number[];
+	pointer?: boolean;
 }
-/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit changed). */
+/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
 	type: "backdrop";
 	backdrop: Backdrop;
@@ -470,7 +496,24 @@ export type HostMessage =
  | {
 	type: "break-done";
 	shown: boolean;
+}
+/**
+ * Turns (input 'remote' only): from now on this child plays, in place of the one before. One remote is one child,
+ * so with several children the screen plays one at a time: the same game goes on with the next child in init's
+ * turns (players [2] after [1], …), exactly one id. Sent only inside the break of a break('turn') the game asked
+ * for (after break-start, before break-done); never at other breaks, so a round never changes hands midway. The
+ * new child's puppet starts recentred, in the middle lane (lane 0), with no lane gesture. Ids keep their meaning
+ * (slots, avatars): keep each player's score by id across turns, and end with the scores of every child who
+ * played. Never sent with input 'body', where init's players stay for the whole game.
+ */
+ | {
+	type: "turn";
+	players: number[];
 };
+/** The players of a turn message, or undefined if they are not valid: exactly one integer id from 1 to MAX_PLAYERS. A copy. */
+export declare function parseTurnPlayers(v: unknown): number[] | undefined;
+/** init's turns, or undefined if they are not valid: 1 to MAX_PLAYERS distinct integer ids from 1 to MAX_PLAYERS, in order. A copy. */
+export declare function parseTurnOrder(v: unknown): number[] | undefined;
 /** Why a game is paused (see HostMessage pause). */
 export type PauseReason = "user" | "distance";
 export declare const PAUSE_REASONS: PauseReason[];
@@ -566,7 +609,45 @@ export interface GameManifest {
 	backdrop?: GameBackdrop[];
 	/** Optional: Fabi explains the game on the TV before calibration (see GameIntro). Absent: straight to calibration. */
 	intro?: GameIntro;
+	/** Optional: how it can be played; absent = ['body']. Must include 'body' (Fabi Play is a movement platform); add 'remote' to be offered without a phone. */
+	inputs?: GameInput[];
+	/**
+	 * Optional, only with 'remote' in inputs: true when the game follows the turns contract, so the screen may let
+	 * several children play with the remote, a round each (init.turns): play a round with the child in players; when
+	 * it ends (a crash too) and turns remain, ask break('turn') (the screen answers break-start, turn, break-done);
+	 * after the last round, end with every child's scores. Absent or false: remote mode is one child only.
+	 */
+	turns?: boolean;
+	/**
+	 * Optional: 'auto' (the default) lets the screen frame the children: when they stand far from the camera it zooms
+	 * in on them (up to 1.8×), so every child's avatar is about the same size and reaches the same things, near or
+	 * far; the view changes only at calibration and in breaks. 'fixed' keeps the whole camera image, as before (for
+	 * a game drawn on exact spots of the live video).
+	 */
+	framing?: GameFraming;
 }
+/** How the screen frames the camera image for a game: see GameManifest.framing. */
+export type GameFraming = "auto" | "fixed";
+export declare const GAME_FRAMINGS: GameFraming[];
+/** The framing of a manifest, with the default. */
+export declare function gameFraming(m: Pick<GameManifest, "framing">): GameFraming;
+/**
+ * How a game can be played: with the body (camera on the phone), or with the TV remote (keys become gestures).
+ *
+ * 'remote' is for TV apps without a phone (Samsung, LG, Android TV, Fire TV): one remote is one child, and with
+ * several children the screen runs turns, only for games whose manifest says "turns": true (see GameManifest.turns,
+ * BreakReason turn, HostMessage turn). The screen turns keys into the gestures the body makes (↑ or OK jump;
+ * ↓ held squat, stand on release; ← → lanes; OK twice quickly clap; Back is the platform's pause, never the game's)
+ * and animates a puppet body in the frames, so with one child most games need no code. On LG the Magic
+ * Remote also points: it reaches the game as ordinary pointer and mouse events (init.pointer says when). A game that
+ * lists 'remote' must play with those keys alone and, where it has things to pick (bubbles, answers, buttons), let a
+ * pointer click them too (pointer events, large hit areas, a hover highlight). Games aimed with the hands should not
+ * list it unless they offer a selection the keys can drive.
+ */
+export type GameInput = "body" | "remote";
+export declare const GAME_INPUTS: GameInput[];
+/** The inputs of a manifest, with the default. */
+export declare function gameInputs(m: Pick<GameManifest, "inputs">): GameInput[];
 /** The backdrops a game may declare in its manifest (its own background is always supported). */
 export type GameBackdrop = Exclude<Backdrop, "none">;
 export declare const GAME_BACKDROPS: GameBackdrop[];

package/dist/index.js

@@ -204,7 +204,7 @@ var TOO_CLOSE_KEY = "fabi-play.too-close-pause";
 var PHASES = ["setup", "intro", "calibrate", "play", "pause", "break", "end"];
 var NS = "fabi-play";
 var wire = (m) => ({ ns: NS, ...m });
-var BREAK_REASONS = ["level", "gameover"];
+var BREAK_REASONS = ["level", "gameover", "turn"];
 function parseView(v) {
   if (!isObject(v)) return void 0;
   const { x, y, w, h } = v;
@@ -227,7 +227,23 @@ function parseGameStats(v) {
   if (DEVICE_TIERS.includes(v.tier)) out.tier = v.tier;
   return out;
 }
+var isPlayerId = (id) => Number.isInteger(id) && id >= 1 && id <= MAX_PLAYERS;
+function parseTurnPlayers(v) {
+  return Array.isArray(v) && v.length === 1 && isPlayerId(v[0]) ? [v[0]] : void 0;
+}
+function parseTurnOrder(v) {
+  if (!Array.isArray(v) || v.length < 1 || v.length > MAX_PLAYERS || !v.every(isPlayerId) || new Set(v).size !== v.length) return void 0;
+  return [...v];
+}
 var PAUSE_REASONS = ["user", "distance"];
+var GAME_FRAMINGS = ["auto", "fixed"];
+function gameFraming(m) {
+  return m.framing ?? "auto";
+}
+var GAME_INPUTS = ["body", "remote"];
+function gameInputs(m) {
+  return m.inputs?.length ? m.inputs : ["body"];
+}
 var GAME_BACKDROPS = ["video"];
 var MOVEMENTS = ["hands", "jump", "squat", "clap", "freeze", "lanes", "shapes"];
 function parseManifest(data) {
@@ -248,6 +264,11 @@ function parseManifest(data) {
   if (m.sdk !== PROTOCOL_VERSION) errors.push(`sdk: this version of Fabi Play uses protocol ${PROTOCOL_VERSION}`);
   if (m.backdrop !== void 0 && !(Array.isArray(m.backdrop) && m.backdrop.every((b) => GAME_BACKDROPS.includes(b)) && new Set(m.backdrop).size === m.backdrop.length))
     errors.push(`backdrop: optional, from ${GAME_BACKDROPS.join(", ")}, without repeats`);
+  if (m.inputs !== void 0 && !(Array.isArray(m.inputs) && m.inputs.includes("body") && m.inputs.every((i) => GAME_INPUTS.includes(i)) && new Set(m.inputs).size === m.inputs.length))
+    errors.push(`inputs: optional, from ${GAME_INPUTS.join(", ")}, without repeats, always with body`);
+  if (m.turns !== void 0 && !(typeof m.turns === "boolean" && (!m.turns || Array.isArray(m.inputs) && m.inputs.includes("remote"))))
+    errors.push('turns: optional, true or false; true only with "remote" in inputs');
+  if (m.framing !== void 0 && !GAME_FRAMINGS.includes(m.framing)) errors.push(`framing: optional, ${GAME_FRAMINGS.join(" or ")}`);
   if (m.intro !== void 0) errors.push(...introErrors(m.intro));
   return errors.length ? { errors } : { manifest: m };
 }
@@ -545,6 +566,8 @@ export {
   DEVICE_TIERS,
   FABI_VOICE,
   GAME_BACKDROPS,
+  GAME_FRAMINGS,
+  GAME_INPUTS,
   INTRO_MAX_CHARS,
   INTRO_MAX_STEPS,
   INTRO_MOVES,
@@ -571,6 +594,8 @@ export {
   decodePose,
   defaultAvatarFor,
   encodePose,
+  gameFraming,
+  gameInputs,
   gamesFor,
   introText,
   isAgeRange,
@@ -589,6 +614,8 @@ export {
   parseIntro,
   parseManifest,
   parseScreenMessage,
+  parseTurnOrder,
+  parseTurnPlayers,
   parseView,
   parseZone,
   poseBytes,

package/fabi-play.schema.json

@@ -5,6 +5,10 @@
   "type": "object",
   "required": ["id", "version", "title", "description", "ageRanges", "movements", "players", "minutes", "entry", "sdk"],
   "additionalProperties": false,
+  "anyOf": [
+    { "not": { "required": ["turns"], "properties": { "turns": { "const": true } } } },
+    { "required": ["inputs"], "properties": { "inputs": { "contains": { "const": "remote" } } } }
+  ],
   "properties": {
     "$schema": {
       "type": "string",
@@ -78,6 +82,23 @@
       "uniqueItems": true,
       "items": { "enum": ["video"] }
     },
+    "inputs": {
+      "type": "array",
+      "description": "Optional: how the game can be played; absent = [\"body\"]. Must include \"body\" (Fabi Play is a movement platform). Add \"remote\" to be offered on TVs without a phone: the TV remote's keys become gestures (up or OK jump, down held squat, left and right lanes, OK twice clap), one child at a time; on LG the Magic Remote also points, so let what the game has to pick be clicked too.",
+      "minItems": 1,
+      "uniqueItems": true,
+      "contains": { "const": "body" },
+      "items": { "enum": ["body", "remote"] },
+      "examples": [["body", "remote"]]
+    },
+    "turns": {
+      "type": "boolean",
+      "description": "Optional, true only with \"remote\" in inputs: the game follows the turns contract, so several children may play with the remote, a round each. When a child's round ends (a crash too) and turns remain, the game asks break('turn') (the screen answers break-start, turn, break-done); after the last round it ends with every child's scores. Absent or false: remote mode is one child only."
+    },
+    "framing": {
+      "enum": ["auto", "fixed"],
+      "description": "Optional, \"auto\" by default: the screen zooms in on children standing far away (up to 1.8×), so every child's avatar is about the same size near or far; the view changes only at calibration and in breaks, never during play. \"fixed\": always the whole camera image (for a game drawn on exact spots of the live video)."
+    },
     "intro": {
       "type": "object",
       "description": "Optional: Fabi explains the game on the TV before calibration, in 1 to 4 steps. Each step: one sentence (Italian and English, up to 90 characters; or one per age range) over an image of the game or a move shown with the children's avatars. The voice is generated by Fabi Play at publication from the text. Without intro the game goes straight to calibration; an invalid one is skipped by the TV.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/protocol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Messages between the phone, the screen and the games, with their checks.",
   "keywords": [
     "fabi-play",