@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/input/schema.ts

@@ -3,22 +3,36 @@
 // Was TS-types-only (`input-types.ts`) until T4.6 authored this Zod schema —
 // see docs/BACKBONE-TASKS.md T4.6. `InputManager.loadMap` (input-manager.ts)
 // is this schema's runtime reader: it parses via this schema, then copies
-// each action's `bindings` array straight into `this.actions`.
+// each action's `bindings` array (and its declared `valueType`, F1) straight
+// into `this.actions`/`this.actionValueTypes`.
 //
 // Every field has a `.describe()` (repo policy — powers
 // `scripts/generate-schema.ts` and the T4.1/T4.6 schema-walk coverage test).
 // No runtime dependency beyond `zod`, matching the `scene/schema/` and
 // `manifest/schema.ts` precedent.
 //
-// T4.1 inheritance: `input-manager.ts`'s `isPressed`/`isJustPressed`/
-// `isJustReleased` switch on `binding.type` and only ever handle `key`,
-// `mouse_button`, `gamepad_button`, and `gamepad_axis` — `mouse_move` and
-// `gamepad_axis_pair` are authored-but-unhandled binding kinds (mouse look is
-// read via a free-standing `mouseDelta`/`lookStick` accumulator that no
-// binding gates, and there is no code path that reads `xAxis`/`yAxis` as a
-// pair). Authoring either kind is a confirmed dead stub — REJECTED at parse,
-// mirroring the `scene/schema/ui.ts` dead-field mechanism (a `.superRefine`
-// that throws naming the field).
+// T4.1 history (now closed by F2): `mouse_move` and `gamepad_axis_pair` were
+// authored-but-unhandled binding kinds — REJECTED at parse via a `.superRefine`
+// that threw naming the field, mirroring the `scene/schema/ui.ts` dead-field
+// mechanism. F2 (spec §12 "Complete Device Backends") un-rejects both: real
+// `InputManager` readers now exist for them (`collectPointerDeltaContributions`/
+// `collectVector2Contributions` — `mouse_move` feeds pointerDelta/vector2 from
+// the existing mouseDelta accumulator; `gamepad_axis_pair` feeds vector2 from
+// the coupled `xAxis`/`yAxis` gamepad reading). F2 also adds two new LIVE
+// binding kinds, `touch_button`/`touch_stick` (the touch/virtual-control
+// backend — see `InputManager.setTouchButton`/`setTouchStick`).
+//
+// F1 (spec §12 "Define Typed Action Values") adds:
+//  - `InputAction.valueType` — an action now DECLARES its value shape
+//    (`digital`/`scalar`/`vector2`/`pointerDelta`/`pointerPosition`),
+//    defaulted to `digital` so every pre-F1 action stays valid unchanged.
+//  - four new, LIVE (not dead-rejected) binding kinds — `test_axis`,
+//    `test_vector2`, `test_pointer_delta`, `test_pointer_position` — the
+//    "injected test input" backend F2's acceptance criteria names as a
+//    peer of keyboard/mouse/gamepad/touch. They read back a caller-injected
+//    raw value (InputManager.injectAxis/injectVector2/injectPointerDelta/
+//    injectPointerPosition) through the SAME deadzone/normalize/combine path
+//    real device bindings use.
 
 import { z } from 'zod';
 import type { InputAction, InputBinding, InputMapFile } from './input-types';
@@ -37,8 +51,18 @@ const MouseMoveBindingSchema = z.object({
   type: z
     .literal('mouse_move')
     .describe(
-      'Binding kind: raw mouse movement. REJECTED at parse (T4.1/T4.6): declared but has no ' +
-        'runtime reader — authoring this binding throws. Do not author.',
+      '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: z
+    .number()
+    .optional()
+    .describe(
+      "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).',
     ),
 });
 
@@ -61,57 +85,187 @@ const GamepadAxisPairBindingSchema = z.object({
     .literal('gamepad_axis_pair')
     .describe(
       'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
-        '(look/aim). REJECTED at parse (T4.1/T4.6): declared but has no runtime reader — only ' +
-        '`gamepad_axis` (a single thresholded axis) is handled by isPressed/isJustPressed/' +
-        'isJustReleased. Authoring this binding throws. Do not author.',
+        '(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: z.number().describe('Standard Gamepad API axis index for the X component'),
   yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
   deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
 });
 
-/**
- * A single input binding. `mouse_move`/`gamepad_axis_pair` are dead-by-decision
- * (see the per-variant `.describe()` above) — the `.superRefine` below is the
- * actual enforcement, mirroring `scene/schema/ui.ts`'s dead-field mechanism.
- */
-export const InputBindingSchema: z.ZodType<InputBinding> = z
-  .discriminatedUnion('type', [
-    KeyBindingSchema,
-    MouseButtonBindingSchema,
-    MouseMoveBindingSchema,
-    GamepadButtonBindingSchema,
-    GamepadAxisBindingSchema,
-    GamepadAxisPairBindingSchema,
-  ])
-  .superRefine((binding, ctx) => {
-    if (binding.type === 'mouse_move') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message:
-          '`mouse_move` binding kind is authored but not implemented — InputManager.isPressed/' +
-          'isJustPressed/isJustReleased never handle it (mouse look is read via a free-standing ' +
-          'mouseDelta/lookStick accumulator, not gated by any action binding). See T4.1/T4.6.',
-        path: ['type'],
-      });
-    }
-    if (binding.type === 'gamepad_axis_pair') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message:
-          '`gamepad_axis_pair` binding kind is authored but not implemented — no reader consumes ' +
-          '`xAxis`/`yAxis` as a coupled pair (only `gamepad_axis`, a single thresholded axis, is ' +
-          'handled by isPressed/isJustPressed/isJustReleased). See T4.1/T4.6.',
-        path: ['type'],
-      });
-    }
-  }) as z.ZodType<InputBinding>;
+// ---------------------------------------------------------------------------
+// F1 (spec §12) — injected test input bindings. LIVE (real runtime readers in
+// InputManager's getScalar/getVector2/getPointerDelta/getPointerPosition),
+// unlike the two dead stubs above. Foreshadows F2's "injected test input"
+// backend: real device kinds F2 adds later feed the same typed-value
+// aggregation path these exercise today.
+// ---------------------------------------------------------------------------
+
+const TestAxisBindingSchema = z.object({
+  type: z
+    .literal('test_axis')
+    .describe(
+      "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: z
+    .string()
+    .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      '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.',
+    ),
+});
+
+const TestVector2BindingSchema = z.object({
+  type: z
+    .literal('test_vector2')
+    .describe(
+      "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: z
+    .string()
+    .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      '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).',
+    ),
+});
+
+const TestPointerDeltaBindingSchema = z.object({
+  type: z
+    .literal('test_pointer_delta')
+    .describe(
+      "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: z
+    .string()
+    .describe(
+      'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
+    ),
+});
+
+const TestPointerPositionBindingSchema = z.object({
+  type: z
+    .literal('test_pointer_position')
+    .describe(
+      "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: z
+    .string()
+    .describe(
+      'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
+    ),
+});
+
+// ---------------------------------------------------------------------------
+// F2 (spec §12 "Complete Device Backends") — touch/virtual-control bindings.
+// LIVE (real runtime readers in InputManager's isPressed/isJustPressed/
+// isJustReleased/getDigitalSource and getVector2), driven by
+// InputManager.setTouchButton/setTouchStick — the headless-testable
+// injectable entry points a real on-screen touch-control UI's own
+// touchstart/touchmove/touchend handlers would call (that DOM wiring is a
+// thin adapter at the edge, out of scope here — see input-manager.ts).
+// ---------------------------------------------------------------------------
+
+const TouchButtonBindingSchema = z.object({
+  type: z
+    .literal('touch_button')
+    .describe(
+      "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: z
+    .string()
+    .describe(
+      'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
+        'touch-UI-chosen id, not a real device index.',
+    ),
+});
+
+const TouchStickBindingSchema = z.object({
+  type: z
+    .literal('touch_stick')
+    .describe(
+      "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: z
+    .string()
+    .describe(
+      'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
+        'touch-UI-chosen id, not a real device index.',
+    ),
+  deadzone: z
+    .number()
+    .optional()
+    .describe(
+      'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
+        'deadzone).',
+    ),
+});
+
+/** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
+ *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
+export const InputBindingSchema: z.ZodType<InputBinding> = z.discriminatedUnion('type', [
+  KeyBindingSchema,
+  MouseButtonBindingSchema,
+  MouseMoveBindingSchema,
+  GamepadButtonBindingSchema,
+  GamepadAxisBindingSchema,
+  GamepadAxisPairBindingSchema,
+  TestAxisBindingSchema,
+  TestVector2BindingSchema,
+  TestPointerDeltaBindingSchema,
+  TestPointerPositionBindingSchema,
+  TouchButtonBindingSchema,
+  TouchStickBindingSchema,
+]) as z.ZodType<InputBinding>;
 
 /** An action has a name (the record key) and one or more bindings. */
 export const InputActionSchema: z.ZodType<InputAction> = z.object({
+  valueType: z
+    .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
+    .default('digital')
+    .describe(
+      "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.",
+    ),
   bindings: z
     .array(InputBindingSchema)
-    .describe('Bindings that all trigger this action (any one firing is enough)'),
+    .describe(
+      '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).',
+    ),
 });
 
 /**

package/src/manifest/index.ts

@@ -1,21 +1,21 @@
 // Game manifest (vgai.game.json) — schema + loader (T3.1 slice 1).
 // See docs/GAME-MANIFEST-DESIGN.md.
 
-export type { ResolvedAdapter, ResolvedGameManifest, ResolvedWorldEntry } from './load';
+export type { ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest } from './load';
 export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
 export type {
+  AdapterRoot,
   GameManifest,
   IngestStrategy,
+  RootAdapter,
   Tier,
-  WorldAdapter,
-  WorldEntry,
 } from './schema';
 export {
+  AdapterRootSchema,
   GameManifestSchema,
   IngestStrategySchema,
+  RootAdapterSchema,
   TierSchema,
-  WorldAdapterSchema,
-  WorldEntrySchema,
 } from './schema';
 
 // `loadGameManifestFile` (Node-only, reads `path` via `node:fs`) is