@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/scene/user-data.ts

@@ -28,11 +28,15 @@
  *                           `entity.components`.
  *
  * Runtime gameplay metadata (set by the scene loader):
+ * - `forward`             — `[x,y,z]` model-space visual forward exported as
+ *                           ordinary glTF extras for asset-facing validation.
  * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
  * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
  * - `splineCurve`         — resolved THREE curve built from the entity's spline.
  * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
  * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
+ *                           inspector facts, bounds, and deterministic disposal.
  *
  * Animation (load-bearing — ED5 disposal contract):
  * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
@@ -53,13 +57,6 @@
  * - `__shadeOrig`         — original material(s) stashed before a shading override.
  * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
  *
- * Custom-shader materials (see `material-registry.ts`):
- * - `__matDef`            — name of the registered custom-material definition.
- * - `__uniforms`          — authored uniform values passed to the def's update().
- *
- * Instancing (see `instance-registry.ts`):
- * - `__instancer`         — name of the registered instancer that built the mesh.
- *
  * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
  * - `__ingest`            — `true` on every Object3D minted by ingestion (vs the
  *                           first-party scene loader); routes edits to live
@@ -98,11 +95,27 @@ export type EditorHelperType =
   | 'cameras'
   | 'audio'
   | 'colliders'
+  // Joint anchor/axis/limit gizmos (W2a) — distinct from 'colliders' so the
+  // viewport's per-type visibility filter can toggle them independently.
+  | 'joints'
+  // LOD distance rings (W2b) — one ring per `mesh.lod` level, radius = the
+  // level's camera-distance threshold in world units.
+  | 'lod'
   | 'splines'
+  // 'particles' tags the LIVE three.quarks emitter Object3D itself (so the
+  // editor's helper machinery skips disposing it); 'particle-shape' tags the
+  // editor's emitter-shape WIREFRAME (W1b) — they must stay distinct: sweeping
+  // "particles"-tagged children would detach the running emitter, and quarks
+  // self-disposes any system whose emitter leaves the scene.
   | 'particles'
+  | 'particle-shape'
   | 'pivot'
   | 'navmesh'
-  | 'skeletons';
+  | 'skeletons'
+  // Per-component viewport gizmo contributions (W3a extension contract,
+  // critique O11): objects a project GameComponent's `static editorGizmo`
+  // hook draws for entities carrying that component.
+  | 'components';
 
 /**
  * Maps each canonical accessor name to its value type. This is the single
@@ -111,6 +124,7 @@ export type EditorHelperType =
 export interface UserDataSchema {
   entity: SceneEntity;
   entityId: string;
+  forward: [number, number, number];
   tags: string[];
   components: Record<string, unknown> | string[];
   navRole: 'walkable' | 'obstacle';
@@ -119,6 +133,7 @@ export interface UserDataSchema {
   splineControlPoint: number;
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
+  gaussianSplat: { src: string; numSplats: number };
   _animMixer: THREE.AnimationMixer;
   _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
@@ -126,9 +141,6 @@ export interface UserDataSchema {
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
-  __matDef: string;
-  __uniforms: Record<string, unknown>;
-  __instancer: string;
   __ingest: boolean;
   __ingestNextId: number;
   engineInternal: boolean;
@@ -140,6 +152,10 @@ export interface UserDataSchema {
   skeletonEnabled: boolean;
   envObject: boolean;
   vcDirIdx: number;
+  /** W1a navmesh path-probe preview polyline: the routed waypoints, mirrored
+   *  onto the preview line Object3D so e2e can read the path back from the
+   *  scene graph (`EditorViewport.setNavPathPreview`). */
+  navPathPoints: { x: number; y: number; z: number }[];
 }
 
 /** Any key in the typed registry. */
@@ -153,6 +169,7 @@ export type UserDataKey = keyof UserDataSchema;
 export const UserDataKeys = {
   entity: 'entity',
   entityId: 'entityId',
+  forward: 'forward',
   tags: 'tags',
   components: 'components',
   navRole: 'navRole',
@@ -161,6 +178,7 @@ export const UserDataKeys = {
   splineControlPoint: 'splineControlPoint',
   _camera: '_camera',
   _particleSystem: '_particleSystem',
+  gaussianSplat: 'gaussianSplat',
   _animMixer: '_animMixer',
   _animClips: '_animClips',
   _availableClips: '_availableClips',
@@ -168,9 +186,6 @@ export const UserDataKeys = {
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',
-  __matDef: '__matDef',
-  __uniforms: '__uniforms',
-  __instancer: '__instancer',
   __ingest: '__ingest',
   __ingestNextId: '__ingestNextId',
   engineInternal: 'engineInternal',
@@ -182,6 +197,7 @@ export const UserDataKeys = {
   skeletonEnabled: 'skeletonEnabled',
   envObject: 'envObject',
   vcDirIdx: 'vcDirIdx',
+  navPathPoints: 'navPathPoints',
 } as const satisfies Record<UserDataKey, string>;
 
 /**

package/src/setup/setup-renderer.ts

@@ -28,8 +28,13 @@ import {
   TiltShiftEffect,
   VignetteEffect,
 } from 'postprocessing';
-import { MotionBlurEffect, SSGIEffect, SSREffect, VelocityDepthNormalPass } from 'realism-effects';
 import * as THREE from 'three';
+import {
+  MotionBlurEffect,
+  SSGIEffect,
+  SSREffect,
+  VelocityDepthNormalPass,
+} from '../../vendor/realism-effects/dist/index.js';
 import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
 import { DEFAULTS } from '../scene/defaults';
 import type { SceneEnvironment } from '../scene/scene-types';

package/src/world2d/asset-paths2d.ts

@@ -0,0 +1,44 @@
+import type { Entity2D, Entity2DAsset, Scene2DFile } from './schema/entity2d';
+
+function visit(entities: Entity2D[], apply: (entity: Entity2D) => void): void {
+  for (const entity of entities) {
+    apply(entity);
+    if (entity.children) visit(entity.children, apply);
+  }
+}
+
+export function collectEntity2DAssetPaths(entities: Entity2D[]): Set<string> {
+  const paths = new Set<string>();
+  visit(entities, (entity) => {
+    if (entity.sprite?.texture) paths.add(entity.sprite.texture);
+    if (entity.tilemap?.texture) paths.add(entity.tilemap.texture);
+  });
+  return paths;
+}
+
+function rename(entities: Entity2D[], oldPath: string, newPath: string): void {
+  visit(entities, (entity) => {
+    if (entity.sprite?.texture === oldPath) entity.sprite.texture = newPath;
+    if (entity.tilemap?.texture === oldPath) entity.tilemap.texture = newPath;
+  });
+}
+
+export function applyScene2DAssetRename(
+  document: Scene2DFile,
+  oldPath: string,
+  newPath: string,
+): Scene2DFile {
+  const cloned = structuredClone(document);
+  rename(cloned.entities, oldPath, newPath);
+  return cloned;
+}
+
+export function applyEntity2DAssetRename(
+  asset: Entity2DAsset,
+  oldPath: string,
+  newPath: string,
+): Entity2DAsset {
+  const cloned = structuredClone(asset);
+  rename([cloned.root], oldPath, newPath);
+  return cloned;
+}

package/src/world2d/collision-2d.ts

@@ -1,7 +1,7 @@
 import type RAPIER from '@dimforge/rapier2d-compat';
 import type { NodeOf } from '../ecs/game-component';
-import type { GameContext } from '../runtime/types';
 import type { Physics2DRegistry } from './physics2d-registry';
+import type { World2DContext } from './types';
 
 export type Collision2DHandler = (handleA: number, handleB: number, started: boolean) => void;
 
@@ -52,8 +52,8 @@ export type Collision2DSystem = ReturnType<typeof createCollision2DSystem>;
  */
 export interface TriggerDispatchComponents {
   getComponents(node: NodeOf<'pixijs'>): ReadonlyArray<{
-    onTriggerEnter?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
-    onTriggerExit?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
+    onTriggerEnter?(other: NodeOf<'pixijs'>, ctx: World2DContext): void;
+    onTriggerExit?(other: NodeOf<'pixijs'>, ctx: World2DContext): void;
   }>;
 }
 
@@ -62,21 +62,14 @@ export interface TriggerDispatchComponents {
  * the GameComponents of the two involved display objects — the 2D analog of
  * `createTriggerDispatch`. Only sensor-involved collisions dispatch triggers.
  *
- * `ctx` is typed `GameContext` (the unified manager's typing) — production
- * (`pixi-game-adapter.ts`) casts its real `World2DContext` to `GameContext`
- * before passing it here; individual `GameComponent<'pixijs'>` subclasses
- * that need real 2D fields off `ctx` widen their own lifecycle-method
- * signature to `GameContext | World2DContext` and narrow back down (see
- * `Camera2DFollow.update` in `./components-2d.ts` — the worked example of
- * the pattern since the world2d-demo silo and its `first-party-scene.ts`
- * were deleted, T6.1 slice 4). This function only ever forwards `ctx` — it
- * never reads a field off it itself.
+ * The callback receives the native `World2DContext`; Pixi components do not
+ * widen or cast their lifecycle context to reach their own first-party APIs.
  */
 export function createTriggerDispatch2D(
   physics: Physics2DRegistry,
   components: TriggerDispatchComponents,
   rapierWorld: RAPIER.World,
-  ctx: GameContext,
+  ctx: World2DContext,
 ): Collision2DHandler {
   return (handleA, handleB, started) => {
     const colA = rapierWorld.getCollider(handleA);
@@ -97,7 +90,7 @@ function notify(
   self: NodeOf<'pixijs'>,
   other: NodeOf<'pixijs'>,
   started: boolean,
-  ctx: GameContext,
+  ctx: World2DContext,
 ): void {
   for (const inst of components.getComponents(self)) {
     if (started) inst.onTriggerEnter?.(other, ctx);

package/src/world2d/entity2d-asset.ts

@@ -0,0 +1,22 @@
+import { SceneParseError } from '../scene/parse';
+import { type Entity2D, type Entity2DAsset, Entity2DAssetSchema } from './schema/entity2d';
+
+/** Parse fetched reusable 2D entity bytes through the same named-error
+ * convention as every other authored project asset. */
+export function parseEntity2DAsset(value: unknown, sourceName?: string): Entity2DAsset {
+  const result = Entity2DAssetSchema.safeParse(value);
+  if (!result.success) throw new SceneParseError(result.error.issues, sourceName);
+  return result.data;
+}
+
+/** Copy a reusable subtree into a scene. Every copy receives fresh authored
+ * identities so repeated drops cannot alias hierarchy/history targets. */
+export function instantiateEntity2DAsset(asset: Entity2DAsset): Entity2D {
+  const root = structuredClone(asset.root);
+  const assignFreshIds = (entity: Entity2D): void => {
+    entity.id = crypto.randomUUID();
+    for (const child of entity.children ?? []) assignFreshIds(child);
+  };
+  assignFreshIds(root);
+  return root;
+}

package/src/world2d/index.ts

@@ -13,6 +13,11 @@
  * See docs/PIXI-WORLD2D-MAXIMAL-SPEC.json (FROZEN).
  */
 
+export {
+  applyEntity2DAssetRename,
+  applyScene2DAssetRename,
+  collectEntity2DAssetPaths,
+} from './asset-paths2d';
 export {
   AuthoringAdapter2D,
   type EditorNode2D,
@@ -27,7 +32,7 @@ export {
   createCollision2DSystem,
   createTriggerDispatch2D,
 } from './collision-2d';
-export { Camera2DFollow, Clickable2D } from './components-2d';
+export { instantiateEntity2DAsset, parseEntity2DAsset } from './entity2d-asset';
 export {
   type EmbedMount2D,
   type IframeReachableMount2D,
@@ -40,6 +45,19 @@ export {
   type Physics2DRefs,
   type Physics2DRegistry,
 } from './physics2d-registry';
+export {
+  assertMovingPhysicsParent2D,
+  computePhysicsPose2D,
+  type PhysicsPose2D,
+  relativeTransform2D,
+  type ScaledCollider2D,
+  scaleCollider2D,
+} from './physics2d-transform';
+export {
+  DEFAULT_WORLD2D_GRAVITY_METERS_PER_SECOND_SQUARED,
+  DEFAULT_WORLD2D_PIXELS_PER_METER,
+  defaultWorld2DGravityY,
+} from './physics2d-units';
 export {
   createWorld2DRuntime,
   type MountedGame2D,
@@ -55,7 +73,14 @@ export {
   installSceneCapture2D,
   type SceneCapture2DHandle,
 } from './scene-capture-2d';
-export { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
+export { materializeScene2DEntityIds, resolveScene2DEntityIds } from './scene2d-identity';
+export {
+  applySceneEntityTransform2D,
+  captureSceneSpriteBaseScale2D,
+  getSceneTilemapTextures2D,
+  loadScene2DFromData,
+  type Scene2DInstance,
+} from './scene2d-loader';
 export * from './schema/entity2d';
 export * from './schema/physics2d';
 export * from './schema/sprite';

package/src/world2d/physics2d-transform.ts

@@ -0,0 +1,173 @@
+import { type Container, Matrix } from 'pixi.js';
+import type { Entity2D } from './schema/entity2d';
+import type { SceneCollider2D } from './schema/physics2d';
+
+const EPSILON = 1e-6;
+
+export interface PhysicsPose2D {
+  matrix: Matrix;
+  position: [number, number];
+  rotation: number;
+  scale: [number, number];
+}
+
+export type ScaledCollider2D =
+  | { shape: 'cuboid'; halfExtents: [number, number] }
+  | { shape: 'ball'; radius: number }
+  | { shape: 'capsule'; halfHeight: number; radius: number };
+
+function isFiniteMatrix(matrix: Matrix): boolean {
+  return [matrix.a, matrix.b, matrix.c, matrix.d, matrix.tx, matrix.ty].every(Number.isFinite);
+}
+
+function linearMetrics(matrix: Matrix): {
+  determinant: number;
+  orthogonality: number;
+  scaleX: number;
+  scaleY: number;
+} {
+  return {
+    determinant: matrix.a * matrix.d - matrix.b * matrix.c,
+    orthogonality: Math.abs(matrix.a * matrix.c + matrix.b * matrix.d),
+    scaleX: Math.hypot(matrix.a, matrix.b),
+    scaleY: Math.hypot(matrix.c, matrix.d),
+  };
+}
+
+function assertRigidRepresentable(matrix: Matrix, label: string): [number, number] {
+  if (!isFiniteMatrix(matrix)) {
+    throw new Error(`world2d physics entity "${label}" has a non-finite composed transform`);
+  }
+  const { determinant, orthogonality, scaleX, scaleY } = linearMetrics(matrix);
+  if (scaleX <= EPSILON || scaleY <= EPSILON || Math.abs(determinant) <= EPSILON) {
+    throw new Error(`world2d physics entity "${label}" has a singular composed transform`);
+  }
+  if (orthogonality > EPSILON * scaleX * scaleY) {
+    throw new Error(
+      `world2d physics entity "${label}" has a sheared composed transform; ` +
+        'Rapier rigid bodies cannot represent shear',
+    );
+  }
+  return [scaleX, scaleY];
+}
+
+/** Matrix from `container` local coordinates into `root` coordinates. The
+ * root's own camera/pan transform is deliberately cancelled: Rapier lives in
+ * the world2d root's logical pixel space, not application/screen space. */
+export function relativeTransform2D(container: Container, root: Container): Matrix {
+  let ancestor: Container | null = container;
+  while (ancestor && ancestor !== root) ancestor = ancestor.parent;
+  if (ancestor !== root) {
+    throw new Error('world2d physics object is not a descendant of the scene root');
+  }
+
+  const rootGlobal = root.getGlobalTransform();
+  const global = container.getGlobalTransform();
+  const origin = rootGlobal.applyInverse(global.apply({ x: 0, y: 0 }));
+  const unitX = rootGlobal.applyInverse(global.apply({ x: 1, y: 0 }));
+  const unitY = rootGlobal.applyInverse(global.apply({ x: 0, y: 1 }));
+  return new Matrix(
+    unitX.x - origin.x,
+    unitX.y - origin.y,
+    unitY.x - origin.x,
+    unitY.y - origin.y,
+    origin.x,
+    origin.y,
+  );
+}
+
+/** Moving Rapier bodies may rotate after spawn. Their Pixi parent chain must
+ * therefore be conformal (uniform scale plus rotation/reflection); otherwise a
+ * later rigid-body rotation would become shear when converted back to the
+ * parent-local display transform. Fixed bodies can retain a non-uniform parent
+ * because their authored relative rotation does not change. */
+export function assertMovingPhysicsParent2D(
+  display: Container,
+  root: Container,
+  label: string,
+): void {
+  const parent = display.parent;
+  if (!parent) throw new Error(`world2d physics entity "${label}" is not mounted`);
+  if (parent === root) return;
+  const parentMatrix = relativeTransform2D(parent, root);
+  const [scaleX, scaleY] = assertRigidRepresentable(parentMatrix, label);
+  if (Math.abs(scaleX - scaleY) > EPSILON * Math.max(scaleX, scaleY)) {
+    throw new Error(
+      `world2d moving physics entity "${label}" has a non-conformal parent transform ` +
+        `(composed scale [${scaleX}, ${scaleY}]); rotating a Rapier body beneath ` +
+        'non-uniform parent scale would shear the Pixi visual',
+    );
+  }
+}
+
+/** Compose the transform Rapier actually owns for one authored entity.
+ *
+ * The parent uses its real Pixi transform so nested visuals and physics agree.
+ * The entity's own linear transform comes from `transform2d`, not from the
+ * display object's `scale`: Sprite width/height are implemented internally by
+ * Pixi as scale, but collider dimensions are already authored in pixels and
+ * must not be multiplied by that implementation detail. The body origin is
+ * the entity position (the world position of Pixi's pivot), matching the
+ * existing world2d physics contract. */
+export function computePhysicsPose2D(
+  entity: Entity2D,
+  display: Container,
+  root: Container,
+  label = entity.name,
+): PhysicsPose2D {
+  const parent = display.parent;
+  if (!parent) throw new Error(`world2d physics entity "${label}" is not mounted`);
+  const parentMatrix = parent === root ? new Matrix() : relativeTransform2D(parent, root);
+  const transform = entity.transform2d;
+  const position = transform?.position ?? [0, 0];
+  const scale = transform?.scale ?? [1, 1];
+  const local = new Matrix().setTransform(
+    position[0],
+    position[1],
+    0,
+    0,
+    scale[0],
+    scale[1],
+    transform?.rotation ?? 0,
+    0,
+    0,
+  );
+  const matrix = new Matrix().appendFrom(local, parentMatrix);
+  const [scaleX, scaleY] = assertRigidRepresentable(matrix, label);
+
+  return {
+    matrix,
+    position: [matrix.tx, matrix.ty],
+    rotation: Math.atan2(matrix.b, matrix.a),
+    scale: [scaleX, scaleY],
+  };
+}
+
+/** Bake the composed visual scale into the native Rapier collider dimensions.
+ * Round shapes require uniform scale because Rapier has no ellipse collider. */
+export function scaleCollider2D(
+  collider: SceneCollider2D,
+  scale: readonly [number, number],
+  label: string,
+): ScaledCollider2D {
+  const [scaleX, scaleY] = scale;
+  if (collider.shape === 'cuboid') {
+    return {
+      shape: 'cuboid',
+      halfExtents: [collider.halfExtents[0] * scaleX, collider.halfExtents[1] * scaleY],
+    };
+  }
+  if (Math.abs(scaleX - scaleY) > EPSILON * Math.max(scaleX, scaleY)) {
+    throw new Error(
+      `world2d physics entity "${label}" uses non-uniform composed scale ` +
+        `[${scaleX}, ${scaleY}] with a ${collider.shape} collider; Rapier cannot represent ` +
+        'an elliptical round collider',
+    );
+  }
+  if (collider.shape === 'ball') return { shape: 'ball', radius: collider.radius * scaleX };
+  return {
+    shape: 'capsule',
+    halfHeight: collider.halfHeight * scaleY,
+    radius: collider.radius * scaleX,
+  };
+}

package/src/world2d/physics2d-units.ts

@@ -0,0 +1,10 @@
+/** Canonical Pixi-world scale: 100 authored pixels represent one physics meter. */
+export const DEFAULT_WORLD2D_PIXELS_PER_METER = 100;
+
+/** Earth-like downward acceleration used when a 2D scene omits gravity. */
+export const DEFAULT_WORLD2D_GRAVITY_METERS_PER_SECOND_SQUARED = 9.8;
+
+/** Derive the pixel-space default while preserving friendly decimal values. */
+export function defaultWorld2DGravityY(pixelsPerMeter: number): number {
+  return (DEFAULT_WORLD2D_GRAVITY_METERS_PER_SECOND_SQUARED * 10 * pixelsPerMeter) / 10;
+}