@fabi-play/engine 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -71,6 +71,36 @@ export interface BackdropView {
 	/** Height, a fraction of the viewport's height. */
 	h: number;
 }
+/** A hand: the child's own left or right. */
+export type HandSide = "left" | "right";
+declare class AimHold {
+	readonly holdMs: number;
+	private readonly last;
+	constructor(holdMs?: number);
+	/** A number for a player's hand. */
+	static key(player: number, side: HandSide): number;
+	/** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+	at(key: number, p: Point | null, t: number): Point | null;
+	/** Forgets every hand. */
+	clear(): void;
+}
+/**
+ * The parts of the game's viewport a phone's notch, rounded corners or home bar may cover, in fractions of the
+ * viewport (top and bottom of its height, left and right of its width; each 0–0.25). The game's frame cannot read
+ * env(safe-area-inset-*), so the screen sends it (init.safeArea): keep buttons, scores and targets out of it, and
+ * still paint the background under it. Zeros where nothing is covered (a TV, a tablet, older hosts).
+ */
+export interface SafeArea {
+	top: number;
+	bottom: number;
+	left: number;
+	right: number;
+}
+/**
+ * A screen's orientation: 'landscape' when its width is at least its height, else 'portrait' (see orientationOf).
+ * GameManifest.orientations lists those a game supports; HostMessage init.orientation says the one it starts in.
+ */
+export type Orientation = "landscape" | "portrait";
 /**
  * Small pure helpers: 2D affine matrices, colours, easing. No DOM here, so they run in Node tests.
  */
@@ -1324,11 +1354,18 @@ export declare function wrists(body: Body): {
 }[];
 /** A player's colour (CSS), as the TV draws them: player 1 orange, 2 blue, 3 green, 4 lilac, then again. */
 export declare const playerColor: (player: number) => "#EE6A43" | "#6FA0E0" | "#8CC9A0" | "#C49BE0";
+/** handsOf's aim: the screen's orientation and, in portrait, what keeps hands through short losses (and its clock, ms). */
+export interface HandsAim {
+	orientation?: Orientation;
+	hold?: AimHold;
+	t?: number;
+}
 /**
- * Every player's hands in stage units: wrists of bodyOf(frame) (null: the frame's own body), through toScreen
- * (player space to screen fractions), times the stage size.
+ * Every player's hands in stage units, where they aim (the protocol's aimPoint), times the stage size; bodyOf(frame)
+ * is the body to read (null: the frame's own). Landscape (the default): its wrists through toScreen (player space to
+ * screen fractions). Portrait (aim.orientation): the wrists stretched to the whole screen, held by aim.hold if given.
  */
-export declare function handsOf(frames: readonly PlayerFrame[], toScreen: (p: Point) => Point, width: number, height: number, bodyOf?: (f: PlayerFrame) => Body | null): Hand[];
+export declare function handsOf(frames: readonly PlayerFrame[], toScreen: (p: Point) => Point, width: number, height: number, bodyOf?: (f: PlayerFrame) => Body | null, aim?: HandsAim): Hand[];
 /** What a node offers to hit tests: its world transform, size and anchor, or a radius. */
 export interface Hittable {
 	/** The node's transform to the stage. */
@@ -1505,6 +1542,10 @@ export interface PlayLike {
 	readonly backdrop?: Backdrop;
 	/** Where the camera image is on the screen, in fractions; null if unknown. */
 	readonly view?: BackdropView | null;
+	/** The screen's orientation at the start ('landscape' if unknown): in 'portrait' the hands aim (see Engine.hands). */
+	readonly orientation?: Orientation;
+	/** What a phone's notch and home bar cover, fractions of the viewport (see Engine.safeArea). */
+	readonly safeArea?: SafeArea;
 	/** The screen's sound is off. */
 	readonly muted?: boolean;
 	/** What the screen knows about the device (init.device): a starting tier and the display's rate. */
@@ -1614,6 +1655,18 @@ export interface Engine {
 	readonly backdrop: Backdrop;
 	/** Where the camera image is on the screen, in fractions; null if the host didn't say. */
 	readonly view: BackdropView | null;
+	/**
+	 * The screen's orientation when the game started: 'landscape' (a TV, a tablet; also before the host says) or
+	 * 'portrait' (a phone held upright). It decides where hands() are (see there).
+	 */
+	readonly orientation: Orientation;
+	/**
+	 * What a phone's notch, rounded corners and home bar cover, in fractions of the viewport (top and bottom of its
+	 * height, left and right of its width; each 0–0.25; zeros on a TV, a tablet, and from hosts that don't say). The
+	 * game's frame can't read env(safe-area-inset-*): keep buttons, scores and targets out of it (in stage units, top
+	 * × 720, left × stage.width), still paint the background under it.
+	 */
+	readonly safeArea: Readonly<SafeArea>;
 	/** Paused by the host (pause, break) or by pause(): game time, tweens, particles and sound are stopped. */
 	readonly paused: boolean;
 	/** Sounds and tones, quiet while paused or muted. */
@@ -1700,9 +1753,16 @@ export interface Engine {
 	 * bitmap fonts (.fnt, or a BMFont .json, + page images), sounds and fonts, by name.
 	 */
 	load(assets: Record<string, string>): Promise<void>;
-	/** This frame's hands (of one player, or everyone's), stage units: in the avatar's hands, or on the real ones. */
+	/**
+	 * This frame's hands (of one player, or everyone's), stage units, where they aim: what they touch, catch, press.
+	 * Landscape (a TV, a tablet): in the avatar's hands, or on the real ones over the video. Portrait (a phone held
+	 * upright, where the camera image is small at the bottom): the wrists stretched around the shoulders to the whole
+	 * stage (the protocol's aimPoint), so arms straight up reach the top (y ≈ 0.15 × 720) and arms out the sides, held
+	 * for 300 ms when the camera loses a wrist; the avatars are still drawn small in the view. To draw on the body
+	 * itself, use toScreen(wrist) of the SDK. touched() and handMarkers() use these hands.
+	 */
 	hands(player?: number): Hand[];
-	/** The first hand (of one player, or anyone's) touching the node, or null. padding: stage units. */
+	/** The first hand (of one player, or anyone's) touching the node, or null; the hands are hands()'s. padding: stage units. */
 	touched(node: Node, player?: number, opts?: {
 		padding?: number;
 	}): Hand | null;
@@ -1912,7 +1972,7 @@ export interface FaceDef {
 	/** Eyebrows of this colour (people): a little attitude. */
 	brows?: string;
 }
-/** The age band an avatar is for, or 'all': offered in every band (Fabi the fox, the app's mascot). */
+/** The age band an avatar is for, or 'all': of no band (Fabi the fox, the app's mascot: the host, in no picker). */
 export type AvatarBand = AgeRange | "all";
 /** An avatar, as data: one renderer draws any definition. */
 export interface AvatarDef {
@@ -1925,7 +1985,7 @@ export interface AvatarDef {
 	};
 	/**
 	 * The age band the avatar is for, its home: its style and its body proportions (see BAND_BODY in rig.ts). 'all': in
-	 * every band's list, drawn with the 6–8 proportions. See alsoIn for an avatar offered in other bands too.
+	 * no band's list (the mascot), drawn with the 6–8 proportions. See alsoIn for an avatar offered in other bands too.
 	 */
 	band: AvatarBand;
 	/**
@@ -1934,7 +1994,7 @@ export interface AvatarDef {
 	 * (outline), bandOf, and its proportions when the band shown is not known. Not for 'all' (the mascot).
 	 */
 	alsoIn?: readonly AgeRange[];
-	/** A special avatar (the mascot): first in every band's list; pickers may mark it. */
+	/** A special avatar (the mascot): the host, not a player; in no band's list (AVATAR_BANDS). */
 	special?: boolean;
 	/** Its colours. */
 	palette: Palette;

package/dist/index.development.js

@@ -28,6 +28,77 @@ var DEFAULT_AVATARS_BY_AGE = {
 };
 var DEFAULT_AVATARS = DEFAULT_AVATARS_BY_AGE["6-8"];
 var toScreen = (view, p) => view ? { x: view.x + p.x * view.w, y: view.y + p.y * view.h } : { x: p.x, y: p.y };
+var AIM_VISIBLE = 0.5;
+var HAND_SPACE = { left: 1.6, top: 1.6, w: 3.2, h: 3 };
+var TORSO_PER_SHOULDER_WIDTH = 1.2;
+function aimPoint(who, side, opts = {}) {
+  const body = Array.isArray(who) ? who : who.body;
+  if (!Array.isArray(body)) return null;
+  const w2 = side === "left" ? P.leftWrist : P.rightWrist;
+  const at = (i) => isNumber(body[i * 3]) && isNumber(body[i * 3 + 1]) && (body[i * 3 + 2] ?? 0) >= AIM_VISIBLE ? i : -1;
+  if (at(w2) < 0) return null;
+  const wx = body[w2 * 3];
+  const wy = body[w2 * 3 + 1];
+  if (opts.orientation !== "portrait") return toScreen(opts.view, { x: wx, y: wy });
+  if (at(P.leftShoulder) < 0 || at(P.rightShoulder) < 0) return null;
+  const ls = P.leftShoulder * 3;
+  const rs = P.rightShoulder * 3;
+  const sx = (body[ls] + body[rs]) / 2;
+  const sy = (body[ls + 1] + body[rs + 1]) / 2;
+  const lh = P.leftHip * 3;
+  const rh = P.rightHip * 3;
+  const hx = (body[lh] + body[rh]) / 2;
+  const hy = (body[lh + 1] + body[rh + 1]) / 2;
+  let torso = isNumber(hx) && isNumber(hy) ? Math.hypot(hx - sx, hy - sy) : 0;
+  if (at(P.leftHip) < 0 || at(P.rightHip) < 0) torso = Math.max(torso, TORSO_PER_SHOULDER_WIDTH * Math.hypot(body[ls] - body[rs], body[ls + 1] - body[rs + 1]));
+  torso = Math.max(torso, 0.01);
+  return {
+    x: clamp01((wx - sx + HAND_SPACE.left * torso) / (HAND_SPACE.w * torso)),
+    y: clamp01((wy - sy + HAND_SPACE.top * torso) / (HAND_SPACE.h * torso))
+  };
+}
+var AIM_HOLD_MS = 300;
+var AimHold = class {
+  constructor(holdMs = AIM_HOLD_MS) {
+    __publicField(this, "holdMs", holdMs);
+    __publicField(this, "last", /* @__PURE__ */ new Map());
+  }
+  /** A number for a player's hand. */
+  static key(player, side) {
+    return player * 2 + (side === "right" ? 1 : 0);
+  }
+  /** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+  at(key, p, t) {
+    const l = this.last.get(key);
+    if (p) {
+      if (l) {
+        l.x = p.x;
+        l.y = p.y;
+        l.t = t;
+      } else this.last.set(key, { x: p.x, y: p.y, t });
+      return p;
+    }
+    if (!l) return null;
+    if (t - l.t <= this.holdMs) return { x: l.x, y: l.y };
+    this.last.delete(key);
+    return null;
+  }
+  /** Forgets every hand. */
+  clear() {
+    this.last.clear();
+  }
+};
+var MAX_SAFE_INSET = 0.25;
+var NO_SAFE_AREA = Object.freeze({ top: 0, bottom: 0, left: 0, right: 0 });
+function parseSafeArea(v) {
+  if (!isObject(v)) return void 0;
+  const f = (n) => isNumber(n) ? Math.min(Math.max(n, 0), MAX_SAFE_INSET) : 0;
+  return { top: f(v.top), bottom: f(v.bottom), left: f(v.left), right: f(v.right) };
+}
+var COVER_ASPECT = 16 / 9;
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var clamp01 = (n) => Math.min(Math.max(n, 0), 1);
 var POSE_HEADER = 12;
 var POSE_BODY_BYTES = LANDMARKS * 4;
 var poseBytes = (bodies) => POSE_HEADER + bodies * POSE_BODY_BYTES;
@@ -4335,11 +4406,20 @@ function wrists(body) {
   return out;
 }
 var playerColor = (player) => PLAYER_COLORS[((player - 1) % PLAYER_COLORS.length + PLAYER_COLORS.length) % PLAYER_COLORS.length];
-function handsOf(frames, toScreen2, width, height, bodyOf = () => null) {
+var SIDES = ["left", "right"];
+function handsOf(frames, toScreen2, width, height, bodyOf = () => null, aim = {}) {
   const out = [];
   for (const f of frames) {
     const body = bodyOf(f) ?? f.body;
     if (!Array.isArray(body)) continue;
+    if (aim.orientation === "portrait") {
+      for (const side of SIDES) {
+        let p = aimPoint(body, side, { orientation: "portrait" });
+        if (aim.hold) p = aim.hold.at(AimHold.key(f.id, side), p, aim.t ?? 0);
+        if (p) out.push({ player: f.id, side, x: p.x * width, y: p.y * height, color: playerColor(f.id) });
+      }
+      continue;
+    }
     for (const w2 of wrists(body)) {
       const s = toScreen2(w2);
       out.push({ player: f.id, side: w2.side, x: s.x * width, y: s.y * height, color: playerColor(f.id) });
@@ -5001,6 +5081,10 @@ var HandMarkers = class extends Node {
   }
 };
 var now = () => performance.now();
+var frozenSafeArea = (v) => {
+  const sa = parseSafeArea(v);
+  return sa && Object.freeze(sa);
+};
 async function createEngine(opts = {}) {
   const play = opts.play ?? null;
   let canvas = opts.canvas ?? null;
@@ -5135,6 +5219,8 @@ async function createEngine(opts = {}) {
   ro?.observe(canvas);
   let backdrop = play?.backdrop === "video" ? "video" : "none";
   let view = play?.view ?? null;
+  let orientation = play?.orientation === "portrait" ? "portrait" : "landscape";
+  let safeArea = frozenSafeArea(play?.safeArea) ?? NO_SAFE_AREA;
   let livePlayers = [];
   let lastPlayersAt = -Infinity;
   let hostPaused = false;
@@ -5162,7 +5248,7 @@ async function createEngine(opts = {}) {
         lastPlayersAt = now();
       }
     };
-    const hold = (on) => {
+    const hold2 = (on) => {
       hostPaused = on;
       syncSound();
     };
@@ -5176,6 +5262,11 @@ async function createEngine(opts = {}) {
     };
     unlisten.push(
       play.on("start", (m) => lateHint(m?.device)),
+      play.on("start", (m) => {
+        if (m?.orientation === "portrait" || m?.orientation === "landscape") orientation = m.orientation;
+        const sa = frozenSafeArea(m?.safeArea);
+        if (sa) safeArea = sa;
+      }),
       // The simple API knows muted only from the start (its getter is false before): read it again then.
       play.on("start", (m) => {
         if (typeof m?.muted === "boolean") sound.muted = m.muted;
@@ -5184,11 +5275,11 @@ async function createEngine(opts = {}) {
       play.on("players", (m) => setPlayers(m?.players)),
       play.on("backdrop", (m) => setBackdrop(m?.backdrop, m?.view)),
       play.on("start", (m) => setBackdrop(m?.backdrop, m?.view ?? play.view)),
-      play.on("pause", () => hold(true)),
-      play.on("resume", () => hold(false)),
-      play.on("break-start", () => hold(true)),
-      play.on("break-done", () => hold(false)),
-      play.on("break-end", () => hold(false))
+      play.on("pause", () => hold2(true)),
+      play.on("resume", () => hold2(false)),
+      play.on("break-start", () => hold2(true)),
+      play.on("break-done", () => hold2(false)),
+      play.on("break-end", () => hold2(false))
     );
     sound.muted = play.muted === true;
   }
@@ -5199,11 +5290,13 @@ async function createEngine(opts = {}) {
   let tick = 0;
   const live = () => now() - lastPlayersAt < 1e3 ? livePlayers : [];
   const toScreen2 = (p) => play ? play.toScreen(p) : toScreen(view, p);
+  const hold = new AimHold();
   const allHands = () => {
     if (handsAt === tick) return handsCache;
     handsAt = tick;
-    const bodyOf = backdrop === "video" || !play?.smoothedBody ? () => null : (f) => play.smoothedBody(f);
-    handsCache = handsOf(live(), toScreen2, stageW, STAGE_HEIGHT, bodyOf);
+    const portrait = orientation === "portrait";
+    const bodyOf = backdrop === "video" && !portrait || !play?.smoothedBody ? () => null : (f) => play.smoothedBody(f);
+    handsCache = handsOf(live(), toScreen2, stageW, STAGE_HEIGHT, bodyOf, portrait ? { orientation, hold, t: now() } : void 0);
     return handsCache;
   };
   const box = { x: 0, y: 0, w: 1, h: 1 };
@@ -5366,6 +5459,12 @@ async function createEngine(opts = {}) {
     get view() {
       return view;
     },
+    get orientation() {
+      return orientation;
+    },
+    get safeArea() {
+      return safeArea;
+    },
     get paused() {
       return hostPaused || userPaused;
     },
@@ -6225,7 +6324,7 @@ ${msg}`);
 };
 
 // src/filters.ts
-var clamp01 = (v) => Math.min(Math.max(v, 0), 1);
+var clamp012 = (v) => Math.min(Math.max(v, 0), 1);
 var pos = (v) => Math.max(v, 0);
 var Base = class {
   constructor() {
@@ -6277,11 +6376,11 @@ var Contrast = class extends Amount {
 };
 var Invert = class extends Amount {
   toMatrix(m) {
-    const a = clamp01(this.amount);
+    const a = clamp012(this.amount);
     linear(m, 1 - 2 * a, a);
   }
   css() {
-    return `invert(${clamp01(this.amount)})`;
+    return `invert(${clamp012(this.amount)})`;
   }
 };
 var Saturate = class extends Amount {
@@ -6304,7 +6403,7 @@ var Saturate = class extends Amount {
 };
 var Grayscale = class extends Amount {
   toMatrix(m) {
-    const k = 1 - clamp01(this.amount);
+    const k = 1 - clamp012(this.amount);
     m9[0] = 0.2126 + 0.7874 * k;
     m9[1] = 0.7152 - 0.7152 * k;
     m9[2] = 0.0722 - 0.0722 * k;
@@ -6317,12 +6416,12 @@ var Grayscale = class extends Amount {
     rgb3(m, m9);
   }
   css() {
-    return `grayscale(${clamp01(this.amount)})`;
+    return `grayscale(${clamp012(this.amount)})`;
   }
 };
 var Sepia = class extends Amount {
   toMatrix(m) {
-    const k = 1 - clamp01(this.amount);
+    const k = 1 - clamp012(this.amount);
     m9[0] = 0.393 + 0.607 * k;
     m9[1] = 0.769 - 0.769 * k;
     m9[2] = 0.189 - 0.189 * k;
@@ -6335,7 +6434,7 @@ var Sepia = class extends Amount {
     rgb3(m, m9);
   }
   css() {
-    return `sepia(${clamp01(this.amount)})`;
+    return `sepia(${clamp012(this.amount)})`;
   }
 };
 var HueRotate = class extends Amount {
@@ -6384,7 +6483,7 @@ var Tint = class extends Amount {
     return i + 2;
   }
   toMatrix(m) {
-    const a = clamp01(this.amount);
+    const a = clamp012(this.amount);
     linear(m, 1 - a, 0);
     m[4] = (this.c >> 16 & 255) / 255 * a;
     m[9] = (this.c >> 8 & 255) / 255 * a;
@@ -6395,7 +6494,7 @@ var Tint = class extends Amount {
     return null;
   }
   paint2d(ctx, x, y, w2, h) {
-    const a = clamp01(this.amount);
+    const a = clamp012(this.amount);
     if (a <= 0) return;
     ctx.save();
     ctx.setTransform(1, 0, 0, 1, 0, 0);
@@ -6461,7 +6560,7 @@ var DropShadow = class extends Base {
     return this.a;
   }
   set opacity(v) {
-    this.a = clamp01(v);
+    this.a = clamp012(v);
   }
   get color() {
     return this.rgb;