@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/world2d/schema/sprite.ts

@@ -19,8 +19,16 @@ export const SpriteSchema = z
       ),
     frame: z
       .string()
+      .min(1)
       .optional()
       .describe('Spritesheet frame/sub-texture name when `texture` is a spritesheet atlas'),
+    animation: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        'Named spritesheet animation from `texture` (PIXI.Spritesheet.animations); mutually exclusive with `frame`',
+      ),
     anchor: Vec2Schema.optional().describe('Normalized anchor [x, y] (0..1). Default [0.5, 0.5]'),
     tint: z
       .string()
@@ -47,12 +55,32 @@ export const SpriteSchema = z
       .enum(['none', 'blur', 'desaturate'])
       .optional()
       .describe('Apply a PixiJS filter (BlurFilter / ColorMatrix desaturate). Default none'),
-    animationFrames: z
+    fps: z
       .number()
-      .int()
+      .positive()
       .optional()
-      .describe('If set, build an AnimatedSprite cycling N generated tinted frames'),
-    fps: z.number().optional().describe('AnimatedSprite playback speed in frames/sec. Default 8'),
+      .describe('AnimatedSprite playback speed in frames/sec. Default 8'),
+    loop: z
+      .boolean()
+      .optional()
+      .describe('Whether the named spritesheet animation loops. Default true'),
+  })
+  .strict()
+  .superRefine((sprite, ctx) => {
+    if (sprite.animation && !sprite.texture) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: '`animation` requires a spritesheet `texture`',
+        path: ['animation'],
+      });
+    }
+    if (sprite.animation && sprite.frame) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: '`animation` and `frame` are mutually exclusive',
+        path: ['animation'],
+      });
+    }
   })
   .describe('2D sprite appearance (world2d). Instantiated as a PIXI.Sprite or AnimatedSprite');
 

package/src/world2d/schema/tilemap.ts

@@ -2,20 +2,37 @@ import { z } from 'zod';
 
 /**
  * `tilemap` authored section — engine-owned 2D tilemap data (NOT a CompositeTilemap),
- * instantiated to a `@pixi/tilemap` CompositeTilemap by the 2D spawn path. Asset-light:
- * a `palette` of hex colors generates one tile texture each, and `tiles` is a row-major
- * grid of palette indices. A real tileset texture/Tiled `.tmj` import is the natural
- * extension (per the spec's optional Tiled note).
+ * instantiated to a `@pixi/tilemap` CompositeTilemap by the 2D spawn path. `texture`
+ * points at a native Pixi spritesheet JSON asset; `frames` gives its ordered tile
+ * palette and `tiles` stores indices into that palette.
  */
 export const TilemapSchema = z
   .object({
-    tileSize: z.number().describe('Tile width/height in pixels'),
-    palette: z
-      .array(z.string())
-      .describe('Hex colors; one generated tile texture per entry (index → color)'),
+    frames: z
+      .array(z.string().min(1))
+      .min(1)
+      .describe('Ordered Pixi spritesheet frame names used as tile indices'),
+    texture: z.string().min(1).describe('URL or project path to a Pixi spritesheet JSON asset'),
+    tileSize: z.number().positive().describe('Positive square tile width/height in pixels'),
     tiles: z
       .array(z.array(z.number().int()))
-      .describe('Row-major grid of palette indices (each row is an array of tile indices)'),
+      .describe(
+        'Row-major grid of frame indices; -1 is an empty cell (each row is an array of tile indices)',
+      ),
+  })
+  .strict()
+  .superRefine((tilemap, ctx) => {
+    for (let row = 0; row < tilemap.tiles.length; row++) {
+      for (let column = 0; column < tilemap.tiles[row]!.length; column++) {
+        const index = tilemap.tiles[row]![column]!;
+        if (index >= -1 && index < tilemap.frames.length) continue;
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Tile index must be -1 (empty) or a frame index from 0 to ${tilemap.frames.length - 1}`,
+          path: ['tiles', row, column],
+        });
+      }
+    }
   })
   .describe('2D tilemap (world2d). Instantiated as a @pixi/tilemap CompositeTilemap');
 

package/src/world2d/transform-writer-2d.ts

@@ -1,24 +1,42 @@
+import type { Container } from 'pixi.js';
 import type { Physics2DRegistry } from './physics2d-registry';
+import { relativeTransform2D } from './physics2d-transform';
+
+function normalizeAngle(angle: number): number {
+  return Math.atan2(Math.sin(angle), Math.cos(angle));
+}
 
 /**
  * Build the single postPhysics transform writer for world2d — the ~5-line 2D
  * analog of `createTransformWriter`.
  *
- * Rapier 2D reports `translation()` as `{x, y}` and `rotation()` as a SCALAR angle
- * (radians), so the writeback is simply `display.position.set(x, y)` +
- * `display.rotation = angle`. Scale is left untouched (Rapier carries no scale).
- *
- * Bodies are simulated in world2d pixel space directly (the surface uses a
- * y-down, pixel-unit world), so no unit conversion is needed; parented entities
- * are kept flat under the world container by the loader, mirroring the 3D writer's
- * scene-root fast path.
+ * Rapier reports world-space poses. A display nested below the scene root needs
+ * that pose converted through its parent's inverse transform before assignment;
+ * writing the world pose as local coordinates makes parented visuals drift away
+ * from their colliders. Scale is left untouched (Rapier carries no scale).
  */
-export function createTransformWriter2D(physics: Physics2DRegistry) {
+export function createTransformWriter2D(physics: Physics2DRegistry, sceneRoot: Container) {
   return function writeTransforms2D(): void {
     for (const [display, { body }] of physics.entries()) {
       const t = body.translation();
-      display.position.set(t.x, t.y);
-      display.rotation = body.rotation();
+      const rotation = body.rotation();
+      const parent = display.parent;
+      const ownReflection = display.scale.x < 0 ? Math.PI : 0;
+      if (parent && parent !== sceneRoot) {
+        const parentMatrix = relativeTransform2D(parent, sceneRoot);
+        const localOrigin = parentMatrix.applyInverse({ x: t.x, y: t.y });
+        const localXAxis = parentMatrix.applyInverse({
+          x: t.x + Math.cos(rotation),
+          y: t.y + Math.sin(rotation),
+        });
+        display.position.set(localOrigin.x, localOrigin.y);
+        display.rotation = normalizeAngle(
+          Math.atan2(localXAxis.y - localOrigin.y, localXAxis.x - localOrigin.x) - ownReflection,
+        );
+      } else {
+        display.position.set(t.x, t.y);
+        display.rotation = normalizeAngle(rotation - ownReflection);
+      }
     }
   };
 }

package/src/world2d/types.ts

@@ -1,11 +1,13 @@
 import type RAPIER from '@dimforge/rapier2d-compat';
 import type { Application, Container } from 'pixi.js';
-import type { z } from 'zod';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { SeededRandom } from '../core/seeded-random';
 import type { createSystemRunner } from '../core/system-runner';
-import type { SystemPhaseName } from '../core/types';
 import type { ComponentManager } from '../ecs/component-manager';
-import type { GameComponent } from '../ecs/game-component';
-import type { Game } from '../runtime/game';
+import type { GameComponentClass } from '../ecs/game-component';
+import type { InputManager } from '../input/input-manager';
+import type { Game, WorldInstance } from '../runtime/game';
+import type { DebugCtxSurface } from '../runtime/types';
 import type { Collision2DSystem } from './collision-2d';
 import type { Physics2DRegistry } from './physics2d-registry';
 
@@ -39,6 +41,18 @@ export interface World2DContext {
   components: ComponentManager;
   /** The phase-ordered system runner (shared with the 3D path). */
   systems: ReturnType<typeof createSystemRunner>;
+  /** The game-owned input manager. Pixi components use the same action maps,
+   *  rebinding, gamepad, tracing, and virtual-input path as Three components. */
+  input: InputManager;
+  /** The shared debug/synthetic-player surface, scoped to this Pixi root. */
+  debug?: DebugCtxSurface;
+  /** The game-scoped seeded random surface shared by every first-party root. */
+  random: SeededRandom;
+  /** Register a game-owned editor-facing system adapter on this root. */
+  registerSystemAdapter?<K extends keyof SystemAdapters>(
+    kind: K,
+    adapter: NonNullable<SystemAdapters[K]>,
+  ): void;
   /**
    * The shared Game root when this world is mounted by a first-party host.
    * This is the cross-world data path: a Pixi component can query gameplay
@@ -46,16 +60,15 @@ export interface World2DContext {
    * bespoke synchronization bridge.
    */
   game?: Game | undefined;
+  /** Live alias of `game.roots`, when mounted by the universal host. */
+  roots?: ReadonlyArray<WorldInstance> | undefined;
 }
 
 /** Constructor type for `GameComponent<'pixijs'>` subclasses used in a world2d
  *  registry (carries static phase/schema) — the 2D-registry analog of
  *  `GameComponentClass` (`ecs/game-component.ts`), narrowed to the pixijs kind
  *  so `new Cls()` returns a properly-typed `GameComponent<'pixijs'>` without a cast. */
-export type Pixi2DComponentClass = (new () => GameComponent<'pixijs'>) & {
-  phase?: SystemPhaseName;
-  schema?: z.ZodObject<z.ZodRawShape>;
-};
+export type Pixi2DComponentClass = GameComponentClass<'pixijs'>;
 
 /** Component registry for world2d — a plain name→class map (the 2D analog). */
 export type Component2DRegistry = Record<string, Pixi2DComponentClass>;

package/src/world3d-react/behavior.tsx

@@ -0,0 +1,138 @@
+/**
+ * `<Behavior type="…" {...config}>` — the rapier-`<RigidBody>`-shaped wrapper
+ * that attaches a registry GameComponent to its child's Object3D under ENGINE
+ * phases (the manager provided by `EngineBridge`, ticked by the host loop via
+ * ./r3f-adapter.tsx — pause freezes it), detaches on unmount, and re-applies
+ * schema-parsed config on prop change.
+ *
+ * Upstreamed VERBATIM in semantics from `examples/r3f-first-party/src/
+ * behavior.tsx` (R4, docs/R3F-FOLLOW-THROUGH-SPEC.md): the Zod-parse +
+ * live-instance re-config behavior and the group-wrapper single-stamp shape
+ * are live-proven and deliberately unchanged. The one structural difference:
+ * the class lookup is REGISTRY-DRIVEN through the bridge (`EngineBridgeValue.
+ * registry`, handed to `createR3FAdapter({ components })` by the project)
+ * instead of a project-module import — an engine module cannot import
+ * project code.
+ *
+ * WRAPPER SHAPE (the documented W3 decision): a `<group>` wrapper, NOT
+ * `cloneElement` ref-injection. Reasons:
+ *  - Write-back: the child element keeps its OWN JSX stamp untouched (its
+ *    `userData-oid` prop pierces onto the child's Object3D exactly as it
+ *    does un-wrapped), so the child's prop/gizmo write-back path is
+ *    byte-identical to an un-wrapped mesh. `cloneElement` would have to
+ *    merge a ref without clobbering an authored one — fragile across
+ *    forwardRef/ref-as-prop shapes — and adds nothing the group doesn't.
+ *  - The wrapper is also the Behavior's OWN presence in the scene graph: it
+ *    carries the `<Behavior>` call site's `userData-oid` stamp (fiber
+ *    pierces the forwarded dashed prop onto the group's userData), which is
+ *    what makes the Behavior node itself selectable/source-addressable in
+ *    the editor hierarchy, with its schema-declared config editable like any
+ *    other JSX prop.
+ *  - Transform semantics: the group stays at identity, so the child's
+ *    authored `position`/`rotation`/`scale` are unchanged by wrapping.
+ *
+ * The component attaches to the FIRST CHILD's Object3D (`group.children[0]`)
+ * — the wrapper contract from the spec — not to the group, so `this.object3D`
+ * inside the GameComponent is the mesh the author wrapped.
+ */
+
+// NOTE: the fiber types import below is type-only; at runtime this module
+// depends only on `react`. It is still R3F-COUPLED by contract: only a
+// project that already mounts through fiber (createR3FAdapter) can render it
+// meaningfully, and the editor's OID stamping marks R3F-dialect files by
+// their fiber import — project entry files importing this module keep their
+// own `@react-three/fiber` import for the scene itself.
+import type { ThreeElements } from '@react-three/fiber';
+import { createElement, useContext, useEffect, useRef } from 'react';
+import type { Group } from 'three';
+import type { GameComponent } from '../ecs/game-component';
+import { type BehaviorRegistry, EngineBridge, resolveBehaviorClass } from './engine-bridge';
+
+export interface BehaviorProps<Reg extends BehaviorRegistry = BehaviorRegistry>
+  extends Pick<ThreeElements['group'], 'children'> {
+  /** Project-registry key of the GameComponent class to attach. */
+  type: Extract<keyof Reg, string>;
+  /** Authored config fields, validated through the class's static Zod schema
+   *  — plus the editor's `userData-oid` stamp, forwarded to the group. */
+  [field: string]: unknown;
+}
+
+export function Behavior<Reg extends BehaviorRegistry = BehaviorRegistry>(
+  props: BehaviorProps<Reg>,
+) {
+  const { type, children, 'userData-oid': oid, ...config } = props;
+  const bridge = useContext(EngineBridge);
+  const groupRef = useRef<Group>(null);
+
+  // Latest config, readable from the attach effect without re-running it.
+  const configRef = useRef(config);
+  configRef.current = config;
+  // The live instance the config-reapply effect targets (never re-attach).
+  const liveRef = useRef<GameComponent | null>(null);
+
+  useEffect(() => {
+    if (!bridge?.registry) {
+      // Loud degrade, never a crash: a mount without the adapter's bridge
+      // (e.g. a foreign harness rendering this tree directly) — or a bridge
+      // whose adapter was built without a `components` registry — renders
+      // the children plain; behavior simply doesn't attach.
+      console.warn(
+        `<Behavior type="${type}">: no EngineBridge ${
+          bridge ? 'registry' : 'provider'
+        } — component not attached.`,
+      );
+      return;
+    }
+    const target = groupRef.current?.children[0];
+    if (!target) {
+      console.warn(`<Behavior type="${type}">: no child Object3D to attach to.`);
+      return;
+    }
+    const registry = bridge.registry;
+    const Cls = resolveBehaviorClass(registry, type);
+    const instance = new Cls();
+    const parsed = Cls.schema ? Cls.schema.parse(configRef.current) : configRef.current;
+    Object.assign(instance, parsed);
+    // `attach`'s registry info carries the raw authored props so engine-side
+    // HMR (`hotSwap`) can re-validate them against a future class version.
+    bridge.components.attach(target, instance, {
+      key: type,
+      props: { ...configRef.current },
+    });
+    liveRef.current = instance;
+    return () => {
+      // `detach(node)` removes every component on the node (the manager's
+      // public teardown op). This wrapper attaches exactly one component per
+      // child, so this is exact here.
+      bridge.components.detach(target);
+      liveRef.current = null;
+    };
+  }, [bridge, type]);
+
+  // Re-apply config on prop change, onto the LIVE instance (no re-attach).
+  const configJson = JSON.stringify(config);
+  useEffect(() => {
+    const instance = liveRef.current;
+    if (!instance || !bridge?.registry) return;
+    const Cls = resolveBehaviorClass(bridge.registry, type);
+    const parsed: Record<string, unknown> = JSON.parse(configJson);
+    Object.assign(instance, Cls.schema ? Cls.schema.parse(parsed) : parsed);
+  }, [configJson, type, bridge]);
+
+  // Built with createElement, NOT a JSX literal, deliberately: the editor's
+  // OID stamper rewrites JSX syntax only, so a JSX `<group>` here would get
+  // behavior.tsx's OWN stamp AND the forwarded call-site oid (a duplicate
+  // `userData-oid` attribute). The wrapper group must carry exactly ONE
+  // identity — the `<Behavior>` CALL SITE's oid — so the editor's hierarchy
+  // selects/edits the Behavior element the author actually wrote.
+  return createElement(
+    'group',
+    {
+      ref: groupRef,
+      name: `Behavior:${type}`,
+      'userData-oid': oid,
+      'userData-behaviorType': type,
+    },
+    children,
+  );
+}

package/src/world3d-react/engine-bridge.ts

@@ -0,0 +1,48 @@
+/**
+ * `@engine/world3d-react` — the React context that carries the engine
+ * component runtime into an R3F tree, so `<Behavior>` (./behavior.tsx) can
+ * reach the REAL `ComponentManager.attach` path from inside fiber JSX.
+ *
+ * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4,
+ * docs/R3F-FOLLOW-THROUGH-SPEC.md — the opt-in module
+ * R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names). The bridge value is built by
+ * `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
+ * `createSystemRunner` + `createComponentManager` pair whose phases the
+ * adapter's `update(dt)` runs under the HOST loop — so attached
+ * GameComponents tick in engine phase order, pause included (no update while
+ * the world is frozen), exactly like scene-authored components.
+ *
+ * `registry` is the project's own behavior registry (`<Behavior type="…">`
+ * resolves against it) — REGISTRY-DRIVEN by design: the engine module never
+ * imports project code; the project hands its registry to
+ * `createR3FAdapter({ components })`, which places it here.
+ */
+
+import { createContext } from 'react';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameComponentClass } from '../ecs/game-component';
+
+/** A project's behavior registry: `<Behavior type>` keys → component classes. */
+export type BehaviorRegistry = Readonly<Record<string, GameComponentClass>>;
+
+export interface EngineBridgeValue {
+  /** The engine's real component manager for this R3F world. */
+  readonly components: ComponentManager;
+  /** The project's behavior registry (absent ⇒ `<Behavior>` degrades loudly). */
+  readonly registry?: BehaviorRegistry | undefined;
+}
+
+export const EngineBridge = createContext<EngineBridgeValue | null>(null);
+
+/** Resolve a `<Behavior type>` key against the bridge's registry, throwing a
+ *  teaching error naming the registered keys (the same loud failure shape the
+ *  example's project-owned `getComponent` had). */
+export function resolveBehaviorClass(registry: BehaviorRegistry, type: string): GameComponentClass {
+  const cls = registry[type];
+  if (!cls) {
+    throw new Error(
+      `Unknown behavior type "${type}" — registered: ${Object.keys(registry).join(', ')}`,
+    );
+  }
+  return cls;
+}

package/src/world3d-react/index.ts

@@ -0,0 +1,44 @@
+/**
+ * world3d-react — the react-three-fiber bridge for vgai's threejs surface
+ * (`@engine/world3d-react`).
+ *
+ * The OPT-IN module R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names, upstreamed
+ * from the live-proven `examples/r3f-first-party` project copies (R4,
+ * docs/R3F-FOLLOW-THROUGH-SPEC.md; decision D24 — R3F TSX is the blessed
+ * three.js authoring path). Mirrors how `world2d/` is pixi's opt-in home: a
+ * peer surface module the engine CORE never imports (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is
+ * an allowed react-importing entry alongside `react/`, and core files may
+ * not import it).
+ *
+ * Peer contract: an importing PROJECT already depends on `react`,
+ * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
+ * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
+ * in the project's Vite config; see `createR3FAdapter`'s header). The engine
+ * package deliberately declares no hard dependency on fiber: only projects
+ * that already mount through fiber ever import this module.
+ *
+ * Surface:
+ *  - `createR3FAdapter({ id, content, components })` — mount an R3F tree as
+ *    a first-party `kind: "threejs"` world under the host's gated loop.
+ *  - `<Behavior type="…" {...config}>` — attach a registry GameComponent to
+ *    the wrapped child's Object3D under engine phases (registry-driven via
+ *    `EngineBridge`; generic over the project's registry for typed keys).
+ *  - `EngineBridge` / `EngineBridgeValue` / `BehaviorRegistry` — the context
+ *    contract, exported for advanced adopters building their own bridge.
+ */
+
+export { Behavior, type BehaviorProps } from './behavior';
+export {
+  type BehaviorRegistry,
+  EngineBridge,
+  type EngineBridgeValue,
+  resolveBehaviorClass,
+} from './engine-bridge';
+export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
+export {
+  createR3FWorldContext,
+  DEFAULT_INPUT_MAP_PATH,
+  type R3FWorldContextOptions,
+  type R3FWorldRuntime,
+} from './world-context';