@fabi-play/sdk 0.5.0 → 0.7.0

package/README.md

@@ -76,6 +76,31 @@ view), and offers only games that say they can be played in portrait:
   `'landscape'` (also what older hosts mean). Use it to choose a layout, but size everything from the real viewport
   (`innerWidth` × `innerHeight`).
 - On a phone the child is close and often seen from the head to the knees: don't rely on the feet being visible.
+- **Aim with `play.aim`, not with `toScreen(wrist)`.** On a phone the camera image (`play.view`) is drawn small at the
+  bottom of the screen, and raised hands even leave it, so a wrist through `toScreen` never reaches the top.
+  `play.aim(player, side)` (`side` `'left'` or `'right'`; a player id or a frame) is where a hand aims, in fractions
+  of the page: in portrait the arms' reach around the shoulders stretched to the whole screen (arms straight up near
+  the top, y ≈ 0.15; arms out to the sides near the edges; the wrist on the shoulder line at y ≈ 0.53; hands by the
+  hips near the bottom, y ≈ 0.87), held for 300 ms when the camera loses the wrist; in landscape exactly
+  `toScreen(wrist)` on the avatar's hand (or the real one over the video), as before. So one line works on every
+  screen: **use `aim` for what the hand touches, catches or presses; `toScreen(wrist)` only to draw on the body**.
+  The script tag has `FabiPlay.aim(player, side)` and the `hands` event's `aim: { left, right }`; with
+  `@fabi-play/engine`, `engine.hands()`, `engine.touched()` and `engine.handMarkers()` already aim, nothing to change.
+
+  ```js
+  const p = play.aim(1, 'right')
+  if (p && near(star, p.x * innerWidth, p.y * innerHeight)) pop(star)
+  ```
+
+- **Safe area.** A phone's notch, rounded corners and home bar cover parts of the page, and the game's frame can't
+  read `env(safe-area-inset-*)`. `play.safeArea` (`FabiPlay.safeArea`, the `start` event's `safeArea`) says how much,
+  in fractions of the page: `{ top, bottom, left, right }`, top and bottom of its height, left and right of its
+  width, each from 0 to 0.25; zeros on a TV, a tablet and from older hosts. Keep buttons, scores and targets out of
+  it, and still paint your background under it:
+
+  ```js
+  hud.style.top = `${play.safeArea.top * innerHeight}px`
+  ```
 
 ## Fabi explains your game (intro)
 
@@ -116,7 +141,8 @@ of the game, or a move shown with the children's own avatars, which they can als
 
 `play.view` is where the camera image lies on your page, so each child's avatar and hands are where the child stands.
 Draw anything that belongs to a child at `play.toScreen(point)` (a wrist, the head, the avatar's box), never at your
-own mapping of player space.
+own mapping of player space. For what a hand touches, use `play.aim(player, side)`: the same as `toScreen(wrist)` on
+a TV or a tablet, and on a phone held upright the hand stretched to the whole screen (see Portrait).
 
 The view is not fixed. By default the screen frames 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. It decides

package/dist/avatars.js

@@ -6,7 +6,7 @@ import {
   drawShapes,
   frameOf,
   iconShapes
-} from "./chunks/chunk-H3BKYVPL.js";
+} from "./chunks/chunk-WS2JRQ53.js";
 export {
   BAND_BODY,
   DEFAULT_AVATAR,

package/dist/chunks/{chunk-H3BKYVPL.js → chunk-WS2JRQ53.js}

@@ -70,6 +70,73 @@ function parseView(v) {
   return isNumber(x) && isNumber(y) && isNumber(w) && isNumber(h) && w > 0 && h > 0 ? { x, y, w, h } : void 0;
 }
 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 w = 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(w) < 0) return null;
+  const wx = body[w * 3];
+  const wy = body[w * 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 f2 = (n) => isNumber(n) ? Math.min(Math.max(n, 0), MAX_SAFE_INSET) : 0;
+  return { top: f2(v.top), bottom: f2(v.bottom), left: f2(v.left), right: f2(v.right) };
+}
 var DEVICE_TIERS = ["high", "medium", "low"];
 function parseDeviceHint(v) {
   if (!isObject(v)) return void 0;
@@ -106,6 +173,7 @@ function parseTurnOrder(v) {
 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;
@@ -2385,6 +2453,10 @@ export {
   wire,
   parseView,
   toScreen,
+  aimPoint,
+  AimHold,
+  NO_SAFE_AREA,
+  parseSafeArea,
   parseDeviceHint,
   parseGameStats,
   parseCursor,

package/dist/fabi-play.d.ts

@@ -178,6 +178,20 @@ declare namespace FabiPlay {
 		/** Height, a fraction of the viewport's height. */
 		h: number;
 	}
+	/** A hand: the child's own left or right. */
+	export type HandSide = "left" | "right";
+	/**
+	 * 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;
+	}
 	/** Quality tiers for drawing, best first: what @fabi-play/engine calls engine.tier.name. */
 	export type DeviceTier = "high" | "medium" | "low";
 	/**
@@ -235,6 +249,10 @@ declare namespace FabiPlay {
 	 * only a game whose manifest lists 'portrait' gets 'portrait'. Informational, to choose a layout: lay out from the
 	 * real viewport size all the same. Absent (older hosts) = 'landscape'.
 	 */
+	/**
+	 * safeArea: what a phone's notch, rounded corners and home bar cover, in fractions of the viewport (see SafeArea;
+	 * parseSafeArea clamps each side to 0–0.25). Absent (a TV, a tablet, older hosts) = nothing covered.
+	 */
 	{
 		type: "init";
 		v: number;
@@ -252,6 +270,7 @@ declare namespace FabiPlay {
 		pointer?: boolean;
 		pictures?: boolean;
 		orientation?: Orientation;
+		safeArea?: SafeArea;
 	}
 	/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
 	 | {
@@ -581,6 +600,8 @@ declare namespace FabiPlay {
 		mode: "tv" | "solo";
 		/** 'landscape' or 'portrait' (a phone held upright): the screen's orientation at the start, see Play.orientation. */
 		orientation: Orientation;
+		/** What a phone's notch and home bar cover, fractions of the viewport (zeros if nothing): see Play.safeArea. */
+		safeArea: Readonly<SafeArea>;
 		/** 'video': mirror mode, paint no opaque background; 'none': paint your own. See the backdrop event. */
 		backdrop: Backdrop;
 		/** Where the camera image is (with 'video', the video; with 'none', where the avatars stand), see toScreen; null if unknown. */
@@ -609,11 +630,20 @@ declare namespace FabiPlay {
 	} & {
 		/** The screen started the game (late listeners still get it). */
 		start: StartInfo;
-		/** Every frame, the hands of each player, as screen shares (0–1). */
+		/**
+		 * Every frame, the hands of each player, in fractions of the screen (0–1). aim: where each hand aims, for what it
+		 * touches (see Easy.aim: the hand on the body in landscape, stretched to the whole screen in portrait). left and
+		 * right: the hands as pointers, the arms' reach stretched to the whole screen in every orientation
+		 * (PlayerFrame.leftHand and rightHand). null: not seen.
+		 */
 		hands: {
 			player: number;
 			left: Point | null;
 			right: Point | null;
+			aim: {
+				left: Point | null;
+				right: Point | null;
+			};
 		};
 		/** When a player's shape changes (arms up, wide, …). */
 		shape: {
@@ -668,7 +698,7 @@ declare namespace FabiPlay {
 	 *
 	 * @example
 	 * FabiPlay.on('jump', ({ player }) => hop(player))
-	 * FabiPlay.on('hands', ({ player, right }) => right && aim(player, FabiPlay.toScreen(right)))
+	 * FabiPlay.on('hands', ({ player, aim }) => aim.right && touch(player, aim.right))
 	 * await FabiPlay.break('level')
 	 * FabiPlay.end(120)
 	 */
@@ -736,6 +766,10 @@ declare namespace FabiPlay {
 		}): Promise<PictureResult>;
 		/** The screen's sound is off (see StartInfo.muted); false before start. */
 		readonly muted: boolean;
+		/** The screen's orientation at the start (see Play.orientation); 'landscape' before start. */
+		readonly orientation: Orientation;
+		/** What a phone's notch and home bar cover, fractions of the viewport (see Play.safeArea); zeros before start. */
+		readonly safeArea: Readonly<SafeArea>;
 		/** Where the camera image is, with any backdrop; null if the host didn't say, and before start. */
 		readonly view: BackdropView | null;
 		/** What the screen knows about the device (see Play.device); null if it said nothing, and before start. */
@@ -747,6 +781,13 @@ declare namespace FabiPlay {
 		 * video or on their avatar. Draw hands and effects at toScreen(wrist), in every mode. Unchanged without a view.
 		 */
 		toScreen(p: Point): Point;
+		/**
+		 * Where a player's hand aims on the screen, in fractions (0–1), by player id or from a frame: use it for what the
+		 * hand touches; toScreen(wrist) only to draw on the body. On a TV or a tablet the hand on the body (the avatar's,
+		 * or the real one over the video); on a phone held upright the wrist stretched to the whole screen, so raised
+		 * hands reach the top. See Play.aim. null when not seen, and before start.
+		 */
+		aim(player: number | PlayerFrame, side: HandSide): Point | null;
 		/**
 		 * The avatar id a player picked on the phone, by player id or from a frame (players[i]); the slot's default
 		 * (fox, lion, dragon, unicorn: the 6–8 band's, as no age is known here) until the first frame says otherwise.
@@ -898,6 +939,13 @@ declare namespace FabiPlay {
 		 * the screen turns.
 		 */
 		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. The game's frame can't read env(safe-area-inset-*), so the
+		 * screen says it. Keep buttons, scores and targets out of it (e.g. a top bar from safeArea.top × innerHeight down);
+		 * still paint the background under it. Zeros (frozen) on a TV, a tablet, and from hosts that don't say.
+		 */
+		readonly safeArea: Readonly<SafeArea>;
 		/** The screen's sound is off: start the game muted. */
 		readonly muted: boolean;
 		/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
@@ -920,6 +968,20 @@ declare namespace FabiPlay {
 		 * mode. Unchanged without a view.
 		 */
 		toScreen(p: Point): Point;
+		/**
+		 * Where a player's hand aims on the game's viewport, in fractions (0–1), by player id (their newest frame) or from
+		 * a frame: use it for what the hand touches, catches, presses; toScreen(wrist) only to draw on the body. One rule
+		 * for every game, the protocol's aimPoint: in landscape (a TV, a tablet) the wrist through toScreen, on the
+		 * avatar's hand (its smoothed body) or, over the video, on the real one; in portrait (a phone held upright, where
+		 * the camera image is small at the bottom and raised hands leave it) the wrist stretched around the shoulders to
+		 * the whole screen (as PlayerFrame.leftHand), so arms straight up reach the top (y ≈ 0.15) and arms out the edges,
+		 * held 300 ms when the camera loses the wrist. null when the hand isn't seen.
+		 *
+		 * @example
+		 * const p = play.aim(1, 'right')
+		 * if (p && hit(star, p.x * innerWidth, p.y * innerHeight)) pop(star)
+		 */
+		aim(player: number | PlayerFrame, side: HandSide): Point | null;
 		/**
 		 * The avatar id a player picked on the phone (fox, lion, robot, …), by player id or from a frame. Each
 		 * frame carries it; before the first frame, from an older host, or for an id this SDK doesn't know: the slot's