@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.3.0",
+  "version": "0.4.0-canary.20260715.0",
   "type": "module",
   "description": "The vgai game engine — core loop, GameComponent model, physics, scene loader, adapter seam.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -14,6 +14,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "vgai": {
+    "operations": [
+      "./src/humanoid/bake.operation.ts"
+    ]
+  },
   "exports": {
     ".": "./src/index.ts",
     "./package.json": "./package.json",
@@ -21,7 +26,8 @@
   },
   "files": [
     "src",
-    "dist"
+    "dist",
+    "schemas"
   ],
   "engines": {
     "node": ">=22.0.0"

package/schemas/engine-api.json

@@ -0,0 +1,124 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. Run 'npm run generate-engine-manifest'.",
+  "phases": [
+    {
+      "name": "input",
+      "description": "Sample input devices (keyboard, mouse, gamepad) at the top of the frame."
+    },
+    {
+      "name": "prePhysics",
+      "description": "Apply forces/intents to rigid bodies before the physics step."
+    },
+    {
+      "name": "physics",
+      "description": "Step the Rapier physics world (fixed timestep)."
+    },
+    {
+      "name": "postPhysics",
+      "description": "Read physics results back; sync transforms from bodies to Object3D."
+    },
+    {
+      "name": "gameLogic",
+      "description": "General gameplay behavior. Default phase for GameComponents."
+    },
+    {
+      "name": "animation",
+      "description": "Advance animation graphs / mixers."
+    },
+    {
+      "name": "preRender",
+      "description": "Final per-frame fixups (cameras, HUD state) before drawing."
+    },
+    {
+      "name": "render",
+      "description": "Draw the frame."
+    }
+  ],
+  "phaseOrder": [
+    "input",
+    "prePhysics",
+    "physics",
+    "postPhysics",
+    "gameLogic",
+    "animation",
+    "preRender",
+    "render"
+  ],
+  "phaseConstants": {
+    "INPUT": "input",
+    "PRE_PHYSICS": "prePhysics",
+    "PHYSICS": "physics",
+    "POST_PHYSICS": "postPhysics",
+    "GAME_LOGIC": "gameLogic",
+    "ANIMATION": "animation",
+    "PRE_RENDER": "preRender",
+    "RENDER": "render"
+  },
+  "gameComponent": {
+    "description": "Base class for game components attached to entities. The Three.js Object3D IS the entity — there is no separate entity id.",
+    "defaultPhase": "gameLogic",
+    "statics": [
+      {
+        "name": "phase",
+        "type": "SystemPhaseName",
+        "default": "gameLogic",
+        "description": "Which phase this component's update runs in. Override in subclasses."
+      },
+      {
+        "name": "schema",
+        "type": "z.ZodObject | undefined",
+        "default": null,
+        "description": "Optional Zod object schema for authored fields. When set, scene data is validated + defaulted through `schema.parse(data)` before assignment."
+      }
+    ],
+    "fields": [
+      {
+        "name": "object3D",
+        "type": "THREE.Object3D",
+        "description": "The Object3D this component is attached to. The Object3D IS the entity."
+      },
+      {
+        "name": "rigidBody",
+        "type": "RAPIER.RigidBody | null",
+        "description": "The entity's Rapier rigid body, if it has physics."
+      },
+      {
+        "name": "collider",
+        "type": "RAPIER.Collider | null",
+        "description": "The entity's Rapier collider, if it has physics."
+      }
+    ],
+    "hooks": [
+      {
+        "name": "init",
+        "optional": true,
+        "signature": "init?(ctx: GameContext): void | Promise<void>",
+        "description": "Called once after the entity is fully constructed (object3D, physics, etc.)."
+      },
+      {
+        "name": "update",
+        "optional": false,
+        "signature": "update(dt: number, ctx: GameContext): void",
+        "description": "Called every fixed timestep, in the component's phase. Required (abstract)."
+      },
+      {
+        "name": "dispose",
+        "optional": true,
+        "signature": "dispose?(ctx: GameContext): void",
+        "description": "Called when the entity is destroyed or the component is removed."
+      },
+      {
+        "name": "onTriggerEnter",
+        "optional": true,
+        "signature": "onTriggerEnter?(other: THREE.Object3D, ctx: GameContext): void",
+        "description": "Called when a sensor overlap with `other` begins."
+      },
+      {
+        "name": "onTriggerExit",
+        "optional": true,
+        "signature": "onTriggerExit?(other: THREE.Object3D, ctx: GameContext): void",
+        "description": "Called when a sensor overlap with `other` ends."
+      }
+    ]
+  }
+}

package/schemas/engine-api.md

@@ -0,0 +1,53 @@
+<!-- AUTO-GENERATED by scripts/generate-engine-manifest.ts — do not edit manually. -->
+<!-- Run 'npm run generate-engine-manifest' to regenerate. -->
+
+# Engine API Manifest
+
+The schema-as-source-of-truth artifact for the engine's imperative surface — generated from the actual code so docs can never drift (see ROADMAP P0.3 / P2.9).
+
+## System Phases
+
+Each frame, systems run in this exact order (from `PHASE_ORDER` in `packages/engine/src/core/types.ts`):
+
+| # | Phase | Constant | Description |
+| - | ----- | -------- | ----------- |
+| 1 | `input` | `SystemPhase.INPUT` | Sample input devices (keyboard, mouse, gamepad) at the top of the frame. |
+| 2 | `prePhysics` | `SystemPhase.PRE_PHYSICS` | Apply forces/intents to rigid bodies before the physics step. |
+| 3 | `physics` | `SystemPhase.PHYSICS` | Step the Rapier physics world (fixed timestep). |
+| 4 | `postPhysics` | `SystemPhase.POST_PHYSICS` | Read physics results back; sync transforms from bodies to Object3D. |
+| 5 | `gameLogic` | `SystemPhase.GAME_LOGIC` | General gameplay behavior. Default phase for GameComponents. |
+| 6 | `animation` | `SystemPhase.ANIMATION` | Advance animation graphs / mixers. |
+| 7 | `preRender` | `SystemPhase.PRE_RENDER` | Final per-frame fixups (cameras, HUD state) before drawing. |
+| 8 | `render` | `SystemPhase.RENDER` | Draw the frame. |
+
+## GameComponent Contract (v2)
+
+Base class for game components attached to entities. The Three.js Object3D IS the entity — there is no separate entity id.
+
+Default phase: `gameLogic`
+
+### Static members
+
+| Member | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `phase` | `SystemPhaseName` | `"gameLogic"` | Which phase this component's update runs in. Override in subclasses. |
+| `schema` | `z.ZodObject | undefined` | `null` | Optional Zod object schema for authored fields. When set, scene data is validated + defaulted through `schema.parse(data)` before assignment. |
+
+### Instance fields (wired by ComponentManager)
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `object3D` | `THREE.Object3D` | The Object3D this component is attached to. The Object3D IS the entity. |
+| `rigidBody` | `RAPIER.RigidBody | null` | The entity's Rapier rigid body, if it has physics. |
+| `collider` | `RAPIER.Collider | null` | The entity's Rapier collider, if it has physics. |
+
+### Lifecycle / hooks
+
+| Hook | Required | Signature | Description |
+| ---- | -------- | --------- | ----------- |
+| `init` | no | `init?(ctx: GameContext): void | Promise<void>` | Called once after the entity is fully constructed (object3D, physics, etc.). |
+| `update` | yes | `update(dt: number, ctx: GameContext): void` | Called every fixed timestep, in the component's phase. Required (abstract). |
+| `dispose` | no | `dispose?(ctx: GameContext): void` | Called when the entity is destroyed or the component is removed. |
+| `onTriggerEnter` | no | `onTriggerEnter?(other: THREE.Object3D, ctx: GameContext): void` | Called when a sensor overlap with `other` begins. |
+| `onTriggerExit` | no | `onTriggerExit?(other: THREE.Object3D, ctx: GameContext): void` | Called when a sensor overlap with `other` ends. |
+

package/schemas/engine-capabilities.json

@@ -0,0 +1,124 @@
+{
+  "$comment": "Curated by human/agent review, NOT auto-generated (unlike engine-api.json beside it). Every claim was verified against code — see each entry's `evidence`. Staleness is machine-checked at two granularities: `schemaDirHash` (sha256 over packages/engine/src/scene/schema/) and per-entry `evidenceHashes` (sha256 of each cited evidence FILE — catches drift in files outside the schema dir, which is where most entries' evidence lives; T5.5/MASTER-ARCHITECTURE-REVIEW.md §7.2).",
+  "_readme": "Read this before authoring scene JSON or engine code, to avoid the negatives below. Refresh flow after a schema-dir OR evidence-file change: `npx tsx scripts/capabilities-hash.ts --check` (fails naming the stale entry) -> re-review affected entries against current code -> `--write` to record fresh hashes. The pre-commit hook runs --check automatically. Each entry's `evidenceHashes` maps the repo-relative file path parsed off the front of each `evidence[]` citation (before any `:line-range` suffix) to a sha256 of that file's current content.",
+  "schemaDirPath": "packages/engine/src/scene/schema/",
+  "schemaDirHash": "3530962568323eb7f0ea4aca8262c616d59fcc64c5fc5a171e4066f672bb77e1",
+  "reviewedAt": "2026-07-01",
+  "entries": [
+    {
+      "id": "physics-no-ccd",
+      "area": "physics",
+      "status": "unsupported",
+      "claim": "No Continuous Collision Detection (CCD). Fast/small dynamic bodies can tunnel through thin colliders in one step.",
+      "evidence": [
+        "packages/engine/src/scene/scene-loader.ts (the `bodyDesc` switch: fixed/kinematicPositionBased/dynamic only; file under concurrent edit elsewhere this wave, so no line numbers — grep 'RigidBodyDesc')",
+        "packages/engine/src/world2d/scene2d-loader.ts:144-154 (2D bodyDesc: same four stock constructors)"
+      ],
+      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches, 2D and 3D. No call ever sets a ccd flag. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders.",
+      "evidenceHashes": {
+        "packages/engine/src/scene/scene-loader.ts": "58ed692dc8bc71ab40839ff5ab48f392f90839734262da2a96bedddc81af09b5",
+        "packages/engine/src/world2d/scene2d-loader.ts": "125f51fd58d6a7912a22c9b8a78f280c59f1a9c035343faf1d266ee81efaa9a6"
+      }
+    },
+    {
+      "id": "physics-no-enforced-envelope",
+      "area": "physics",
+      "status": "unsupported",
+      "claim": "No enforced limit on entity or physics-body count; practical envelope is untested.",
+      "evidence": [
+        "packages/engine/src/setup/setup-physics.ts (RAPIER.World construction: no capacity/count config)",
+        "packages/engine/src/scene/scene-loader.ts (entity/body creation: no count guard)"
+      ],
+      "notes": "Grepped for maxBodies/MAX_ENTITIES/entity limit/body limit/entityCount: no matches. No invented numbers — nothing caps entity/body count and no perf test here establishes a safe ceiling. Treat large counts (hundreds+ dynamic bodies) as unvalidated, not 'supported at scale'.",
+      "evidenceHashes": {
+        "packages/engine/src/setup/setup-physics.ts": "0540c502f420018b24dac8b77c486f30f905f0a05b02ead7ed3899e5aa612ee5",
+        "packages/engine/src/scene/scene-loader.ts": "58ed692dc8bc71ab40839ff5ab48f392f90839734262da2a96bedddc81af09b5"
+      }
+    },
+    {
+      "id": "input-value-model",
+      "area": "input",
+      "status": "supported-with-caveats",
+      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
+      "evidence": [
+        "packages/engine/src/input/input-types.ts:2-40 (InputBinding union incl. mouse_move/gamepad_axis_pair/touch_button/touch_stick/test_*)",
+        "packages/engine/src/input/input-manager.ts:609-1905 (digital/gating/typed getters/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt)"
+      ],
+      "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
+      "evidenceHashes": {
+        "packages/engine/src/input/input-types.ts": "361c2618f5a55ecd8ec6b59689a9ab2a92590d86a694d33d21e825f250675ca0",
+        "packages/engine/src/input/input-manager.ts": "15dc63f60713a6f4087d4e761b5da178555984e939328bb40bf271d9ec76ee30"
+      }
+    },
+    {
+      "id": "animation-masked-layers",
+      "area": "animation",
+      "status": "supported",
+      "claim": "A native XState machine can drive multiple simultaneous named AnimationMixer layers through parallel regions. Layers support 0..1 weights, normal or additive Three.js blending, and include/exclude masks over named bone/Object3D subtrees.",
+      "evidence": [
+        "packages/engine/src/animation/xstate-animation-meta.ts (strict layer, weight, blendMode, and boneMask metadata schemas)",
+        "packages/engine/src/animation/xstate-animation-binding.ts (parallel-region reconciliation, subtree track filtering, and native additive composition)"
+      ],
+      "notes": "XState remains the only transition language. Parallel regions use distinct layer names. The binding filters native clip tracks, uses AnimationUtils.makeClipAdditive, can register with ctx.systems, and exposes live owner inspection data until disposal.",
+      "evidenceHashes": {
+        "packages/engine/src/animation/xstate-animation-meta.ts": "80376ac74819803616c4b396244a971cb9a6b2859c33409d032363bfeb3db44f",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "bfccffe15e265fa2d3843dfaad0d3f1b6a7227a23742efa1f0e11182c8efc33a"
+      }
+    },
+    {
+      "id": "component-fields-no-nested-objects",
+      "area": "scene-schema",
+      "status": "unsupported",
+      "claim": "Authored `components.<Name>` values in .vscn.json/.prefab.json must be a scalar or homogeneous scalar array — nested objects/arrays-of-objects are rejected before a component's own static schema sees them.",
+      "evidence": [
+        "packages/engine/src/scene/schema/entity.ts:46-54 (ComponentScalarSchema/ComponentValueSchema/ComponentDataSchema/ComponentsSchema)",
+        "packages/engine/src/scene/schema/entity.ts:89 (`components: ComponentsSchema.optional()` on SceneEntitySchema, validated at scene-parse time)",
+        "packages/engine/src/scene/component-registry.ts:21-37 (applyComponents' `Klass.schema.parse(data)` runs on data that already passed ComponentDataSchema)"
+      ],
+      "notes": "The ceiling: `z.union([number, string, boolean, number[], string[], boolean[]])`. A GameComponent's own static `schema` CAN declare z.object() fields, but the scene-file parse rejects a nested value first, so authored JSON never carries one that far. Workaround: flatten (`targetX`/`targetY`/`targetZ` instead of `target:{x,y,z}`).",
+      "evidenceHashes": {
+        "packages/engine/src/scene/schema/entity.ts": "2b73fec245362168b1824ee06b820c801e7590de95ab1f11176fadad54991f21",
+        "packages/engine/src/scene/component-registry.ts": "7ea93439c56fdcd1db915893ebb0f3cabfc08112dbf24c15c76df64a063713e4"
+      }
+    },
+    {
+      "id": "ingestion-pixi-tiers",
+      "area": "ingestion",
+      "status": "supported-with-tiers",
+      "claim": "Unmodified OSS PixiJS games run via the world2d seam: manifest 'iframe-reachable' + bundleUrl — in-realm capture, editor edits, overlay persistence. extraDeps must be registry-known (unknown throws); capture failure degrades loudly.",
+      "evidence": [
+        "docs/BACKBONE-TASKS.md:389-414"
+      ],
+      "notes": "Track P shipped 2026-07-03; proven: bubbo-bubbo/puzzling-potions/flappy-pixi. Tiers/limits: docs/CAPABILITY-TIERS.md, docs/PIXI-INGEST-LANDING-DESIGN.md.",
+      "evidenceHashes": {
+        "docs/BACKBONE-TASKS.md": "0a39f9539731af1de5440aa53ad92d463b809fd7458edb7e34df5dac71e911ac"
+      }
+    },
+    {
+      "id": "ingestion-react-dom",
+      "area": "ingestion",
+      "status": "supported-with-caveats",
+      "claim": "Unmodified native-React DOM games run via the manifest `ingest-react` identity: vendored byte-for-byte (vendor/react-games/, zero-diff CI), mounted through the react world stack under the host React 19 (deduped). Embed-only in v1 — hosted, sized, disposed; NO authoring (the editor never writes JSX back into an unmodified game, D-N4).",
+      "evidence": [
+        "docs/BACKBONE-TASKS.md:415-435 (Track N, N0-N4 all done)"
+      ],
+      "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate. Design: docs/REACT-INGEST-LANDING-DESIGN.md.",
+      "evidenceHashes": {
+        "docs/BACKBONE-TASKS.md": "0a39f9539731af1de5440aa53ad92d463b809fd7458edb7e34df5dac71e911ac"
+      }
+    },
+    {
+      "id": "engine-supports-summary",
+      "area": "summary",
+      "status": "supported",
+      "claim": "For contrast, the engine DOES support: discrete Rapier bodies (fixed/kinematic/dynamic) with triggers; phase-ordered GameComponents; Zod-validated scene/prefab JSON; masked layered animation state machines with blend trees; boolean+thresholded-analog input actions; direct (unwrapped) Colyseus multiplayer.",
+      "evidence": [
+        "packages/engine/schemas/engine-api.json (auto-generated positive/imperative-surface manifest beside this file)"
+      ],
+      "notes": "This file exists for negatives engine-api.json can't express (e.g. 'parses but does nothing'). For the full positive surface, read engine-api.json/.md — regenerated by `npm run generate-engine-manifest`, can't drift.",
+      "evidenceHashes": {
+        "packages/engine/schemas/engine-api.json": "9cdf401821aaa4065a32eb0c042c3962e27a9bb76b017ee6ab5a282ab4c7c004"
+      }
+    }
+  ]
+}

package/schemas/inputmap.schema.json

@@ -0,0 +1,314 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "number",
+      "description": "Input map file format version (RESERVED — no range check yet)"
+    },
+    "actions": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "valueType": {
+            "default": "digital",
+            "description": "This action's declared value shape (F1, spec §12). 'digital' (boolean, with pressed/justPressed/justReleased edges) is the default when omitted, matching every action authored before F1. 'scalar' is a single deadzone-rescaled float axis. 'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an absolute {x,y}, last-write-wins across sources. InputManager enforces this at read time: reading an action through the wrong typed getter (e.g. getScalar on a 'digital' action) throws.",
+            "type": "string",
+            "enum": [
+              "digital",
+              "scalar",
+              "vector2",
+              "pointerDelta",
+              "pointerPosition"
+            ]
+          },
+          "bindings": {
+            "type": "array",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "key",
+                      "description": "Binding kind: a keyboard key (KeyboardEvent.code)"
+                    },
+                    "code": {
+                      "type": "string",
+                      "description": "KeyboardEvent.code value, e.g. \"KeyW\", \"Space\", \"ArrowUp\""
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "code"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "mouse_button",
+                      "description": "Binding kind: a mouse button"
+                    },
+                    "button": {
+                      "type": "number",
+                      "description": "MouseEvent.button index (0 = left, 1 = middle, 2 = right)"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "button"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "mouse_move",
+                      "description": "Binding kind: raw mouse movement (F2, spec §12 \"Complete Device Backends\"). Feeds a 'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-circle-clamped via `deadzone`)."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never deadzoned).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_button",
+                      "description": "Binding kind: a gamepad face/shoulder button"
+                    },
+                    "button": {
+                      "type": "number",
+                      "description": "Standard Gamepad API button index"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "button"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_axis",
+                      "description": "Binding kind: a single thresholded gamepad axis"
+                    },
+                    "axis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index"
+                    },
+                    "direction": {
+                      "type": "string",
+                      "enum": [
+                        "positive",
+                        "negative"
+                      ],
+                      "description": "Which side of the deadzone counts as \"pressed\""
+                    },
+                    "deadzone": {
+                      "description": "Deadzone magnitude (default 0.15 if omitted)",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "axis",
+                    "direction"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_axis_pair",
+                      "description": "Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector (look/aim/movement) (F2, spec §12 \"Complete Device Backends\"). Feeds a 'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-circle-clamped the same way a real analog stick is."
+                    },
+                    "xAxis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index for the X component"
+                    },
+                    "yAxis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index for the Y component"
+                    },
+                    "deadzone": {
+                      "description": "Deadzone magnitude (default 0.15 if omitted)",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "xAxis",
+                    "yAxis"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_axis",
+                      "description": "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action (InputManager.injectAxis/getScalar) — the \"injected test input\" backend named in F2, built in F1 as the typed scalar value model's testable source."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectAxis)."
+                    },
+                    "deadzone": {
+                      "description": "1D deadzone magnitude applied to the injected raw value before combine (default 0 — no deadzone). Values below it read as 0; values at/above it rescale from 0 (at the deadzone edge) to ±1 (at |raw| = 1), sign preserved.",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_vector2",
+                      "description": "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action (InputManager.injectVector2/getVector2) — the \"injected test input\" backend named in F2, built in F1 as the typed Vector2 value model's testable source."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectVector2)."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 — no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, direction is preserved and magnitude rescales the same way the scalar deadzone does, then the result is clamped to the unit circle (magnitude <= 1).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_pointer_delta",
+                      "description": "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-valueType action (InputManager.injectPointerDelta/getPointerDelta) — the \"injected test input\" backend named in F2. No deadzone (deltas are not deadzoned)."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectPointerDelta)."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_pointer_position",
+                      "description": "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-valueType action (InputManager.injectPointerPosition/getPointerPosition) — the \"injected test input\" backend named in F2."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectPointerPosition)."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "touch_button",
+                      "description": "Binding kind: a virtual on-screen button for a 'digital' action (InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) the same way a real mouse/keyboard button is."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the virtual control zone this binding reads (InputManager.setTouchButton) — a touch-UI-chosen id, not a real device index."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "touch_stick",
+                      "description": "Binding kind: a virtual on-screen analog stick for a 'vector2' action (InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the same way a real gamepad stick is."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the virtual control zone this binding reads (InputManager.setTouchStick) — a touch-UI-chosen id, not a real device index."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no deadzone).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "description": "Bindings that all trigger/feed this action. Digital actions combine via OR (any one binding satisfied is enough). Scalar actions combine via max-magnitude across contributing bindings (ties keep the first-listed binding). Vector2 actions combine by summing contributing {x,y} values then clamping to the unit circle. PointerDelta actions sum contributing deltas. PointerPosition actions use the most-recently-written contributing source (last-write-wins)."
+          }
+        },
+        "required": [
+          "valueType",
+          "bindings"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Named actions, each with a list of bindings (InputManager.loadMap)"
+    }
+  },
+  "required": [
+    "version",
+    "actions"
+  ],
+  "additionalProperties": false
+}