@fabi-play/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,76 @@
+Fabi Play Kit License
+Version 1.0 (DRAFT, not yet reviewed by a lawyer)
+
+Copyright (c) 2026 Fabi Play. All rights reserved.
+
+This license applies to the Fabi Play Kit: the packages @fabi-play/protocol, @fabi-play/motion,
+@fabi-play/avatars, @fabi-play/sdk and @fabi-play/engine, in source and built form, as published on npm, served
+from https://cdn.fabiplay.app or found in this repository, including their code, type declarations, documentation,
+avatar artwork and other assets (together, the "Kit").
+
+1. Free of charge, for Fabi Play only
+
+   Fabi Play grants you a worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to
+   use, copy, and modify the Kit, and to distribute it as part of a Permitted Work, solely to make, test, run and
+   distribute Permitted Works.
+
+   A "Permitted Work" is a game, tool, or other software made to run on, be published on, or support the
+   development of games for the Fabi Play platform (https://fabiplay.app), including games submitted to Fabi Play
+   and tools used to build, test or preview them.
+
+2. What is not allowed
+
+   You may not, without Fabi Play's prior written permission:
+
+   a. use the Kit, or any part or modified version of it, in software that is not a Permitted Work, including in
+      any other game platform, product or service;
+   b. distribute the Kit, or a modified version of it, on its own or as a library, SDK, engine or framework for
+      others to build with, other than as part of a Permitted Work (installing it from npm or loading it from
+      https://cdn.fabiplay.app is not a distribution by you);
+   c. sell, rent or sublicense the Kit itself;
+   d. remove or alter this license, copyright notices, or the license banners in the built files;
+   e. use the avatars, the mascot "Fabi", or the name, logos or other trademarks of Fabi Play, except as the Kit
+      does when it runs inside a Permitted Work. This license grants no trademark rights;
+   f. use the Kit to circumvent, interfere with or misrepresent the Fabi Play platform, its safety, privacy or
+      parental controls, or its rules for games.
+
+3. Visible, not open source
+
+   The Kit's code is published so that developers can read it, debug with it and build Permitted Works. Being
+   visible does not make it open source; no rights are granted beyond those stated here.
+
+4. Your works
+
+   You keep all rights in your own code and content. This license does not give Fabi Play any rights in your
+   Permitted Works; publishing a game on Fabi Play is governed by Fabi Play's separate developer terms.
+
+5. Feedback
+
+   If you send Fabi Play suggestions or changes for the Kit, Fabi Play may use them without obligation to you.
+
+6. Termination
+
+   This license ends automatically if you break its terms. If you fix the breach within 30 days of becoming aware
+   of it, the license is reinstated, unless Fabi Play has already told you in writing that it is terminated. On
+   termination you must stop using and distributing the Kit. Permitted Works already distributed to end users in
+   compliance with this license may continue to be used by those end users.
+
+7. No warranty
+
+   THE KIT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FABI PLAY OR ITS CONTRIBUTORS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE KIT OR THE USE OR OTHER DEALINGS IN THE KIT.
+
+9. Changes to this license
+
+   Fabi Play may publish new versions of this license. Each version of the Kit is governed by the license version
+   it is distributed with, unless you choose to accept a later version.
+
+10. Contact
+
+   For permissions beyond this license: https://fabiplay.app

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @fabi-play/sdk
 
-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.
+What a [Fabi Play](https://fabiplay.app) game uses, from inside its sandboxed frame: the players and their bodies,
+movements by name (jump, squat, clap, shapes, lanes, freeze, hands as pointers), the avatars, the breaks, the scores
+and the end of the game.
+
+## npm
+
+```sh
+npm install @fabi-play/sdk
+```
+
+```ts
+import { connect } from '@fabi-play/sdk'
+
+const play = await connect()
+play.on('gesture', ({ player, gesture }) => console.log(player, gesture))
+play.ready()
+```
+
+ESM only, types included, no dependencies.
+
+## Script tag
+
+From the CDN, pinned to an exact version with its Subresource Integrity hash (listed in
+`https://cdn.fabiplay.app/sdk/<version>/integrity.json`, and in `dist/integrity.json` of this package):
+
+```html
+<script
+  src="https://cdn.fabiplay.app/sdk/0.1.0/fabi-play.umd.min.js"
+  integrity="sha384-…"
+  crossorigin="anonymous"
+  data-keys="jump:Space,left:ArrowLeft,right:ArrowRight"
+></script>
+<script>
+  FabiPlay.on('jump', ({ player }) => hop(player))
+</script>
+```
+
+| File | What |
+| --- | --- |
+| `fabi-play.umd.min.js` | UMD, minified: global `FabiPlay`, or the module under AMD / CommonJS |
+| `fabi-play.umd.js` | the same, readable |
+| `fabi-play.js` | the classic script (IIFE): sets `window.FabiPlay` |
+| `fabi-play.d.ts` | types for script-tag games (`FabiPlay.PlayerFrame`, …) |
+| `fabi-play.schema.json` | the JSON Schema of `fabi-play.json` |
+
+## Fabi explains your game (intro)
+
+Before calibration, Fabi (the mascot) can explain your game on the TV in a few steps: a speech bubble over an image
+of the game, or a move shown with the children's own avatars, which they can also try. You write only data, in
+`fabi-play.json`:
+
+```json
+"intro": { "steps": [
+  { "say": { "it": "Si corre nel bosco! Ognuno ha la sua pista e raccoglie le stelle.", "en": "Let's run in the woods! Everyone has a track and collects stars." }, "image": "intro/track.jpg" },
+  { "say": { "it": "Tronco? Salta! Provate adesso.", "en": "A log? Jump! Try it now." }, "move": "jump", "practice": true },
+  { "say": { "it": "Ramo basso? Giù!", "en": "Low branch? Down!" }, "move": "squat" }
+] }
+```
+
+- **1 to 4 steps.** Fabi Play adds its own last step ("Ready?") and goes on to calibration.
+- **`say`**: one sentence, in Italian and English, up to 90 characters each (an emoji counts as one), with no spaces
+  at either end and no control characters. Or one per age range, when the little
+  ones need simpler words: `{ "3-5": { "it": "…", "en": "…" }, "9-12": { "it": "…", "en": "…" } }` (at least one
+  range; a child of a range you left out gets the closest one you wrote, the younger if two are as close).
+- **Each step has an `image` or a `move`, not both.**
+  - `image`: a picture of the game, 16:9, at least 1280×720, `.jpg` or `.png` (no WebP: old TV browsers may not
+    decode it; use JPG, quality about 80, for screenshots and PNG only for flat art), a path
+    relative to the game's address like `entry`: no scheme (`https://`), no leading `/`, no `.` or `..` segments,
+    letters, digits, `_` and `-`, extension in lowercase (`intro/track.jpg`, not `intro/Track.JPG`).
+  - `move`: one of `jump`, `squat`, `clap`, `lane-left`, `lane-right`, `arms-up`, `arms-wide`, `arms-v`, `star`,
+    drawn with each child's avatar.
+  - `practice` (optional, only with a `move`): `true` and the children try it, each gets a tick, and the step moves
+    on when all did, or after 8 seconds. Default `false`: Fabi only shows it.
+- **The voice is Fabi Play's.** Fabi speaks each sentence with a clip Fabi Play generates from the text when the
+  game is published. Changing a text needs a new clip: until it is made, the TV shows that sentence in the bubble
+  only.
+- **No `intro`**: the game goes straight to calibration, as before.
+- **An invalid intro** is reported by the check (the Studio, `parseManifest`, the JSON Schema) and skipped by the
+  TV: it never blocks the game.
+
+Docs: https://docs.fabiplay.app.
+
+## License
+
+Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).

package/dist/avatars.d.ts

@@ -0,0 +1,256 @@
+// @fabi-play/sdk/avatars: the avatars' rig @fabi-play/engine draws with. Not a game API.
+// Generated by scripts/types.mjs from the sources: do not edit.
+
+type Body = number[];
+/**
+ * Age ranges: each has its own games. Only the range is kept, never a birth date: it is all the catalogue and the
+ * games need (simpler rules and no losing for the little ones, scores and challenges for the older ones).
+ */
+export type AgeRange = "3-5" | "6-8" | "9-12";
+/**
+ * A tiny shape list, the one source of truth for every avatar picture. The rig and the portrait build a list of
+ * shapes; two small backends draw it: on a 2D canvas (the TV, the games) and as an SVG string (the phones, the
+ * previews). Both read the same numbers, so the canvas and the SVG pictures match.
+ *
+ * Paths use a small subset of SVG path syntax, absolute commands only (M L Q C Z), so the canvas backend can trace
+ * them without Path2D (not available everywhere, e.g. React Native canvases or test mocks). The rig builds them as
+ * PathData, number arrays (no strings built and parsed again every frame); fixed paths may stay strings.
+ */
+/** How an avatar shape is painted (CSS colours). */
+export interface Paint {
+	/** Fill colour; none without it. */
+	fill?: string;
+	/** Outline colour; none without it. */
+	stroke?: string;
+	/** Stroke width, in the units of the shape (scaled by the groups around it). */
+	lw?: number;
+	/** 0–1, multiplied with the alpha around it. */
+	alpha?: number;
+}
+/** One shape of an avatar picture (the rig's output), in canvas units; k says which. */
+export type Shape = (Paint & {
+	k: "circle";
+	x: number;
+	y: number;
+	r: number;
+}) | (Paint & {
+	k: "ellipse";
+	x: number;
+	y: number;
+	rx: number;
+	ry: number;
+	rot?: number;
+})
+/** A rounded rectangle by its centre, rotated by rot radians around it. */
+ | (Paint & {
+	k: "rect";
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+	r: number;
+	rot?: number;
+}) | (Paint & {
+	k: "path";
+	d: string | PathData;
+})
+/** A polyline [x0, y0, x1, y1, …], stroked with round caps and joins. */
+ | (Paint & {
+	k: "line";
+	pts: number[];
+})
+/** Children drawn translated by (x, y), then rotated by rot radians, then scaled by s. */
+ | {
+	k: "group";
+	x: number;
+	y: number;
+	rot?: number;
+	s?: number;
+	alpha?: number;
+	items: Shape[];
+};
+/**
+ * A path as numbers: each command code (PATH.M, …) followed by its coordinates, absolute: M x y, L x y,
+ * Q cx cy x y, C c1x c1y c2x c2y x y, Z. Coordinates are rounded to 2 decimals, as the SVG prints them, so canvas and
+ * SVG pictures match.
+ */
+export type PathData = readonly number[];
+/** The part of CanvasRenderingContext2D the backend uses (so tests can pass a mock). */
+export type Ctx2D = Pick<CanvasRenderingContext2D, "save" | "restore" | "translate" | "rotate" | "scale" | "beginPath" | "closePath" | "moveTo" | "lineTo" | "quadraticCurveTo" | "bezierCurveTo" | "arc" | "ellipse" | "fill" | "stroke" | "rect" | "clip" | "globalAlpha" | "fillStyle" | "strokeStyle" | "lineWidth" | "lineCap" | "lineJoin">;
+export declare function drawShapes(ctx: Ctx2D, shapes: readonly Shape[]): void;
+export interface Pt {
+	x: number;
+	y: number;
+}
+/** An avatar's colours (CSS). */
+export interface Palette {
+	/** Head and torso. */
+	body: string;
+	/** Arms and legs. */
+	limbs: string;
+	/** Belly patch, muzzle, inner face. */
+	belly: string;
+	/** Details: inner ears, horns, beaks, tail tips, spikes. */
+	accent: string;
+	/** The outline around every part: dark, so the avatar reads on light and dark backgrounds. */
+	outline: string;
+	/** Hands; defaults to limbs. */
+	hands?: string;
+	/** Feet; defaults to limbs. */
+	feet?: string;
+	/** Solid ears of another colour (panda); by default ears are body-coloured with an accent inside. */
+	ears?: string;
+	/** The face and head when they differ from the torso (people, the lamb's face); defaults to body. */
+	skin?: string;
+	/** Hair (hair, curls, locks). */
+	hair?: string;
+}
+/** The head's outline. */
+export type HeadShape = "round" | "wide" | "tall" | "square" | "bulb" | "bucket";
+/** The ears (or what is in their place: horns, antennae, a fin). */
+export type EarKind = "none" | "pointy" | "round" | "big-round" | "long" | "side" | "tufts" | "antenna" | "antennae" | "horns" | "unicorn" | "floppy" | "droopy" | "fin" | "human";
+/** How the eyes are drawn. */
+export type EyeKind = "dot" | "big" | "mask" | "screen" | "almond" | "visor" | "calm" | "slit" | "goggle" | "bead";
+/** How the mouth (or beak) is drawn. */
+export type MouthKind = "none" | "smile" | "open" | "cat" | "beak" | "teeth" | "grill" | "tiny" | "smirk" | "bill" | "hook" | "jaws";
+/** The patch around the nose and mouth. */
+export type MuzzleKind = "none" | "oval" | "heart" | "monkey" | "disc" | "cheeks" | "band";
+/** The tail, behind the body. */
+export type TailKind = "none" | "fluffy" | "brush" | "pom" | "long" | "curl" | "tuft" | "striped" | "spiky" | "arrow" | "fish" | "plume";
+/** Things on the head. */
+export type HeadExtra = "mane" | "rainbow-mane" | "stripes" | "spikes" | "spots" | "curl" | "helmet" | "bolts" | "whiskers" | "tuft" | "brows" | "eggshell" | "wool" | "eye-spot" | "crest" | "forehead" | "gills" | "ruff" | "hair" | "curls" | "locks" | "ninja-hood" | "cap" | "safari-hat" | "wizard-hat" | "plume" | "stripe" | "bandana" | "eye-patch" | "dive-mask" | "domino";
+/** Things on the body. */
+export type BodyExtra = "wings" | "backpack" | "sheet" | "tentacles" | "panel" | "badge" | "joints" | "feathers" | "flippers" | "boots" | "scarf" | "spots" | "wool" | "robe" | "cape" | "fins" | "tank" | "straps" | "belt" | "stripes" | "pauldrons" | "emblem" | "pocket" | "racing-stripe" | "star";
+/** An avatar's face. */
+export interface FaceDef {
+	/** How the eyes are drawn. */
+	eyes: EyeKind;
+	/** Eye colour for big/screen/almond/visor eyes. */
+	eyeColor?: string;
+	/** Eyes higher than usual and bulging over the head (frog). */
+	eyesOnTop?: boolean;
+	/** Ring around the eyes (owl). */
+	eyeRing?: string;
+	/** How the mouth is drawn. */
+	mouth: MouthKind;
+	/** Nose colour; none when missing. */
+	nose?: string;
+	/** The patch around nose and mouth. */
+	muzzle: MuzzleKind;
+	/** Blush colour; none when missing. */
+	cheeks?: string;
+	/** 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). */
+export type AvatarBand = AgeRange | "all";
+/** An avatar, as data: one renderer draws any definition. */
+export interface AvatarDef {
+	/** Stable kebab-case id: stored on the phone and sent around, never renamed. */
+	id: string;
+	/** Its name, in English and Italian, for pickers. */
+	name: {
+		en: string;
+		it: string;
+	};
+	/**
+	 * The age band the avatar is for: its style and its body proportions (see BAND_BODY in rig.ts). 'all': in every
+	 * band's list, drawn with the 6–8 proportions.
+	 */
+	band: AvatarBand;
+	/** A special avatar (the mascot): first in every band's list; pickers may mark it. */
+	special?: boolean;
+	/** Its colours. */
+	palette: Palette;
+	/** The head's outline. */
+	head: HeadShape;
+	/** The ears, or what is in their place. */
+	ears: EarKind;
+	/** The face. */
+	face: FaceDef;
+	/** The tail. */
+	tail: TailKind;
+	/** Things on the head (manes, hats, masks). */
+	headExtras: readonly HeadExtra[];
+	/** Things on the body (wings, capes, belts). */
+	bodyExtras: readonly BodyExtra[];
+	/** Colours of the rainbow mane, of the stripes, of the spots: per-avatar extra colours. */
+	extraColors?: readonly string[];
+}
+/** Where player space (0–1) lands on the canvas. */
+export interface Box {
+	/** Left edge, canvas units. */
+	x: number;
+	/** Top edge, canvas units. */
+	y: number;
+	/** Width, canvas units. */
+	w: number;
+	/** Height, canvas units. */
+	h: number;
+}
+/**
+ * Body proportions by age band, in torso units U (head, limbs, torso) unless said otherwise. The joints are always
+ * the child's: limbs run through them and the head sits on the shoulders; only sizes change.
+ *
+ *   3–5: a big round head, chubby limbs, a round tummy that reaches low (the legs look short): toddlers.
+ *   6–8: the original proportions.
+ *   9–12: a smaller head, slimmer limbs and hips, a squarer torso: older kids.
+ */
+export interface BandBody {
+	/** Head radius. */
+	head: number;
+	/** How far the head centre sits above the shoulder line, in head radii. */
+	neck: number;
+	/** Limb thickness. */
+	arm: number;
+	leg: number;
+	/** Hand radius. */
+	hand: number;
+	/** Feet size, as a factor. */
+	foot: number;
+	/** The torso: at least this half width at the shoulders and the hips, and this much past the joints. */
+	shoulderMin: number;
+	shoulderPad: number;
+	hipMin: number;
+	hipPad: number;
+	/** How far the torso reaches below the hips. */
+	bottom: number;
+	/** The waist's bulge, as a share of the wider of shoulders and hips. */
+	bulge: number;
+	/** A raised arm is drawn over the head (a big head would hide it). */
+	armsOverHead: boolean;
+}
+export declare const BAND_BODY: Record<AgeRange, BandBody>;
+export interface RigOptions {
+	mirrored?: boolean;
+	/** Portraits leave the tail out: in a head-and-shoulders crop it would only peek in as a stray shape. */
+	portrait?: boolean;
+	/** Body proportions (see BAND_BODY); 6–8 by default. avatarShapes takes the avatar's own band. */
+	band?: AgeRange;
+}
+/** The torso frame: origin between the shoulders, r to the right, d down along the torso; lengths in pixels. */
+export interface Frame {
+	S: Pt;
+	r: Pt;
+	d: Pt;
+	U: number;
+	/** Shoulders to hips along d. */
+	L: number;
+	hipsOk: boolean;
+	head: Pt;
+	headR: number;
+	headRot: number;
+	angle: number;
+}
+/** The torso frame and head placement, or null when the shoulders are not seen. */
+export declare function frameOf(body: Body, box: Box, opts?: RigOptions): Frame | null;
+/** All the shapes of an avatar for this body, in canvas pixels. Empty when the shoulders are not seen. */
+export declare function avatarShapes(body: Body, def: AvatarDef, box: Box, opts?: RigOptions): Shape[];
+/** The avatar of a child who has not picked one yet: the fox (6–8's first). */
+export declare const DEFAULT_AVATAR: AvatarDef;
+/** The avatar with this id, or undefined. */
+export declare const avatarById: (id: string) => AvatarDef | undefined;
+/** The portrait: head and shoulders of the neutral pose, framed in a size × size square at (0, 0). */
+export declare function iconShapes(def: AvatarDef | string, size: number): Shape[];
+
+export {};

package/dist/avatars.js

@@ -0,0 +1,18 @@
+import {
+  BAND_BODY,
+  DEFAULT_AVATAR,
+  avatarById,
+  avatarShapes,
+  drawShapes,
+  frameOf,
+  iconShapes
+} from "./chunks/chunk-57WXWAXG.js";
+export {
+  BAND_BODY,
+  DEFAULT_AVATAR,
+  avatarById,
+  avatarShapes,
+  drawShapes,
+  frameOf,
+  iconShapes
+};