@fabi-play/engine 0.4.0 → 0.7.0

package/README.md

@@ -50,6 +50,20 @@ Load the SDK first, then the engine, each pinned with its SRI hash
 
 Docs: https://docs.fabiplay.app/engine/overview/.
 
+## Hands, orientation, safe area
+
+`engine.hands()` (stage units), `engine.touched(node)` and the rings of `engine.handMarkers()` are where the hands
+**aim**, with the protocol's `aimPoint`: on a TV or a tablet (landscape) on the avatar's hand, or on the real one over
+the video, as before; on a phone held upright (`engine.orientation === 'portrait'`), where the camera image is small
+at the bottom, the arms' reach around the shoulders stretched to the whole stage, so arms straight up touch near the
+top (y ≈ 0.15 × 720) and arms out reach the sides, held for 300 ms when the camera loses a wrist. The avatars are still
+drawn through the view (`engine.view`), small at the bottom. Games need no change; to draw on the body itself, use the
+SDK's `toScreen(wrist)`.
+
+`engine.safeArea` is what a phone's notch and home bar cover, in fractions of the viewport (`{ top, bottom, left,
+right }`, each 0–0.25, zeros on a TV): keep the HUD and targets out of it, e.g. a score at
+`y = engine.safeArea.top * 720 + 24`.
+
 ## Filters
 
 Any node can go through filters: colour filters, blur and drop shadows draw the same on WebGL and Canvas 2D; custom

package/dist/fabi-play-engine.d.ts

@@ -86,6 +86,36 @@ declare namespace FabiEngine {
 		/** Height, a fraction of the viewport's height. */
 		h: number;
 	}
+	/** A hand: the child's own left or right. */
+	export type HandSide = "left" | "right";
+	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.
 	 */
@@ -1339,11 +1369,18 @@ declare namespace FabiEngine {
 	}[];
 	/** A player's colour (CSS), as the TV draws them: player 1 orange, 2 blue, 3 green, 4 lilac, then again. */
 	export 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 function handsOf(frames: readonly PlayerFrame[], toScreen: (p: Point) => Point, width: number, height: number, bodyOf?: (f: PlayerFrame) => Body | null): Hand[];
+	export 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. */
@@ -1520,6 +1557,10 @@ declare namespace FabiEngine {
 		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. */
@@ -1629,6 +1670,18 @@ declare namespace FabiEngine {
 		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. */
@@ -1715,9 +1768,16 @@ declare namespace FabiEngine {
 		 * 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;
@@ -1927,7 +1987,7 @@ declare namespace FabiEngine {
 		/** 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 {
@@ -1940,7 +2000,7 @@ declare namespace FabiEngine {
 		};
 		/**
 		 * 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;
 		/**
@@ -1949,7 +2009,7 @@ declare namespace FabiEngine {
 		 * (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;