@vgai/engine 0.5.0 → 0.5.2

package/dist/scene/scene-diff-schema.js

@@ -1,92 +0,0 @@
-/**
- * Zod schema for a `SceneDiff` JSON patch (T4.5 — `vgai apply-diff`).
- *
- * Validates the SHAPE of a hand-authored or `diffScene`-computed patch before
- * `applyDiff` (./scene-apply.ts) touches it. Not wired into
- * `scripts/generate-schema.ts` — that script's output feeds the *scene file*
- * JSON Schema (autocomplete/reference for `.vscn.json`/`.prefab.json`/
- * `vgai.game.json`), a different artifact from a diff/patch file. Adding a
- * 5th line there would be mechanically trivial, but a generated
- * `scene-diff.schema.json` has no current consumer (no editor autocomplete
- * targets *.json patch files) — left undone; revisit if one appears.
- *
- * `SceneEntitySchema` is reused as-is for `add`/`update` payloads even though
- * both operations ignore any `children` the payload carries (children are
- * position-managed exclusively by their own `add`/`move` ops — see
- * `applyDiff`'s jsdoc). Rejecting `children` at the schema level would need
- * an `.omit()` off a plain object schema, but `SceneEntitySchema` is a
- * `z.lazy()`-wrapped discriminated union (recursive type), so this schema
- * takes the more permissive-but-documented path: allow it through and let
- * `applyDiff` silently drop it, rather than add a second near-duplicate
- * entity schema just to forbid one field.
- */
-import { z } from 'zod';
-import { SceneEntitySchema } from './schema/entity';
-import { SceneEnvironmentSchema } from './schema/environment';
-const ParentIdSchema = z
-    .string()
-    .nullable()
-    .describe('Parent entity id, or null for a top-level (root) entity');
-const TargetIndexSchema = z
-    .number()
-    .int()
-    .describe('Target position among the (new) parent’s children, counted in the FINAL tree ' +
-    '(after every op in this diff has been applied) — not the position at the moment this ' +
-    'one op runs. Negative values are rejected; out-of-range values are clamped to the end.');
-export const DiffOpSchema = z.discriminatedUnion('type', [
-    z
-        .object({
-        type: z.literal('add').describe('Insert a new entity into the scene tree'),
-        entity: SceneEntitySchema.describe('The entity to insert. Any `children` on this payload are ignored — insert descendants ' +
-            'via their own `add` ops with `parentId` set to this entity’s `id`.'),
-        parentId: ParentIdSchema,
-        index: TargetIndexSchema,
-    })
-        .describe('Add operation'),
-    z
-        .object({
-        type: z.literal('remove').describe('Delete an entity, and its whole subtree, from the scene'),
-        id: z.string().describe('Id of the entity to remove'),
-    })
-        .describe('Remove operation'),
-    z
-        .object({
-        type: z
-            .literal('update')
-            .describe('Replace an entity’s fields (every field except `id` and `children`) with new values — ' +
-            'a full replace, not a merge: fields present on the live entity but absent from this ' +
-            'payload are deleted'),
-        id: z.string().describe('Id of the entity to update'),
-        entity: SceneEntitySchema.describe('The new field values. `id` and any `children` on this payload are ignored — repositioning ' +
-            'is exclusively a `move` op’s job.'),
-    })
-        .describe('Update operation'),
-    z
-        .object({
-        type: z.literal('move').describe('Reparent and/or reorder an existing entity'),
-        id: z.string().describe('Id of the entity to move'),
-        parentId: ParentIdSchema,
-        index: TargetIndexSchema,
-    })
-        .describe('Move operation'),
-]);
-export const SceneDiffSchema = z
-    .object({
-    ops: z
-        .array(DiffOpSchema)
-        .describe('add/remove/update/move operations. Order in this array does not matter for correctness — ' +
-        'applyDiff derives its own safe application order (moves are detached before removes run, ' +
-        'so a child moved out of a removed parent survives; adds/moves are placed by a fully ' +
-        'pre-resolved id map, so a newly-added parent is always resolvable for its newly-added ' +
-        'children regardless of array position).'),
-    environmentChanged: z.boolean().describe('Whether the scene-level `environment` block changed'),
-    newEnvironment: SceneEnvironmentSchema.optional().describe('New `environment` block. Applied only when `environmentChanged` is true; ignored otherwise. ' +
-        'Absent (with `environmentChanged: true`) clears the scene’s environment block.'),
-    metaChanged: z.boolean().describe('Whether scene metadata (currently just `name`) changed'),
-    newName: z
-        .string()
-        .optional()
-        .describe('New scene `name`. Applied only when `metaChanged` is true and this is present; ignored otherwise.'),
-})
-    .describe('A scene-diff patch — the JSON format produced by `diffScene` (packages/editor/src/scene-diff.ts) ' +
-    'and consumed by `applyDiff` (./scene-apply.ts) / `vgai apply-diff`.');

package/dist/scene/scene-diff-types.d.ts

@@ -1,40 +0,0 @@
-/**
- * Scene diff types — shared shape for `DiffOp`/`SceneDiff`.
- *
- * Lives in the engine (not next to the compute function in
- * `packages/editor/src/scene-diff.ts`) so that `packages/vgai-cli` — which
- * does not depend on `@vgai/editor` — can validate/apply a diff without
- * introducing a new cli→editor dependency edge. See the dependency-direction
- * note in `./scene-apply.ts` for the full rationale (T4.5).
- *
- * `packages/editor/src/scene-diff.ts` (the ONLY place that computes a
- * `SceneDiff`, via `diffScene`) re-exports these two names so existing
- * editor imports are unaffected.
- */
-import type { SceneEntity, SceneEnvironment } from './scene-types';
-export type DiffOp = {
-    type: 'add';
-    entity: SceneEntity;
-    parentId: string | null;
-    index: number;
-} | {
-    type: 'remove';
-    id: string;
-} | {
-    type: 'update';
-    id: string;
-    entity: SceneEntity;
-} | {
-    type: 'move';
-    id: string;
-    parentId: string | null;
-    index: number;
-};
-export interface SceneDiff {
-    ops: DiffOp[];
-    environmentChanged: boolean;
-    newEnvironment?: SceneEnvironment | undefined;
-    metaChanged: boolean;
-    newName?: string | undefined;
-}
-//# sourceMappingURL=scene-diff-types.d.ts.map

package/dist/scene/scene-diff-types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scene-diff-types.d.ts","sourceRoot":"","sources":["../../src/scene/scene-diff-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnE,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B"}

package/dist/scene/scene-diff-types.js

@@ -1,14 +0,0 @@
-/**
- * Scene diff types — shared shape for `DiffOp`/`SceneDiff`.
- *
- * Lives in the engine (not next to the compute function in
- * `packages/editor/src/scene-diff.ts`) so that `packages/vgai-cli` — which
- * does not depend on `@vgai/editor` — can validate/apply a diff without
- * introducing a new cli→editor dependency edge. See the dependency-direction
- * note in `./scene-apply.ts` for the full rationale (T4.5).
- *
- * `packages/editor/src/scene-diff.ts` (the ONLY place that computes a
- * `SceneDiff`, via `diffScene`) re-exports these two names so existing
- * editor imports are unaffected.
- */
-export {};

package/dist/scene/scene-loader.d.ts

@@ -1,167 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import * as THREE from 'three';
-import type { BatchedRenderer } from 'three.quarks';
-import { NavMeshManager } from '../ai/navigation';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { PhysicsRegistry } from '../physics/physics-registry';
-import { type RenderScope } from '../render/render-settings';
-import { type ComponentRegistry } from './component-registry';
-import './geometries';
-import './instancers';
-import './materials';
-import { type InstancesFile, type MaterialFile, type PrefabFile, type SceneEntity, type SceneEnvironment, type SceneFile } from './scene-types';
-/**
- * Clear module-level asset caches (textures, GLTF scenes, IBL env maps). Call
- * on full runtime teardown to release cached GPU resources and avoid leaking
- * across editor Play sessions. Delegates the GLTF/texture caches to
- * {@link clearSharedAssetCaches} and additionally frees the local
- * IBL env-map cache + PMREM generator.
- *
- * Lifetime / P1.8: these caches are intentionally module-level and persist
- * ACROSS hot-reloads / scene switches (they are NOT cleared on every
- * loadSceneFromData). This is deliberate: (1) it makes repeated Play→Stop→Play
- * cheap, and (2) it underpins the `__sharedGeometry` contract from P0.2 —
- * GLTF clones share the cached source geometry, so clearing mid-session would
- * orphan live clones. The caches are keyed by URL, so loading the SAME scene N
- * times is bounded (one entry per distinct asset URL, not per load). They are
- * only released here, on full runtime teardown (`fullCleanup`).
- */
-export declare function clearAssetCaches(): void;
-/**
- * F7 — per-frame LOD tick. THREE.LOD only swaps its active level when
- * `.update(camera)` runs, so every `THREE.LOD` in the scene graph (built by
- * the `mesh.lod` spawn branch above) needs this called once a frame. Mirrors
- * `tickCustomMaterials`'s traverse-and-tick shape; wired into the runtime's
- * `preRender` system in `vgai-scene-game-adapter.ts`.
- */
-export declare function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void;
-/**
- * Test-only: current sizes of the module-level asset caches. Used by the P1.8
- * headless test to assert caches stay bounded (one entry per distinct asset URL)
- * across repeated loads of the same scene, rather than growing per load.
- */
-export declare function __assetCacheSizesForTest(): {
-    textures: number;
-    gltf: number;
-    env: number;
-};
-export interface SceneLoadContext {
-    scene: THREE.Scene;
-    rapierWorld: RAPIER.World;
-    rapier: typeof RAPIER;
-    /** Object3D ↔ Rapier body/collider registry (keys physics by the Object3D). */
-    physics: PhysicsRegistry;
-    prefabs?: Map<string, (ctx: SceneLoadContext, entity: SceneEntity) => THREE.Object3D>;
-    componentRegistry?: ComponentRegistry;
-    /** Cache for loaded .prefab.json files. Populated on first reference, cleared per scene load. */
-    prefabFileCache?: Map<string, PrefabFile>;
-    /** Cache for loaded .mat.json files. Populated on first reference. */
-    materialFileCache?: Map<string, MaterialFile>;
-    /** Cache for loaded .instances.json files. Populated on first reference (F3). */
-    instancesFileCache?: Map<string, InstancesFile>;
-    /** Supply an AudioListener (attached to camera) to enable audio entity spawning. */
-    audioListener?: THREE.AudioListener;
-    /** ComponentManager for instantiating GameComponent classes from scene data. */
-    componentManager?: ComponentManager;
-    /** three.quarks BatchedRenderer. If provided, particle systems declared on
-     *  entities are registered here so they render (mirrors the editor). */
-    particleRenderer?: BatchedRenderer;
-    /** WebGLRenderer. Required for skybox/IBL (PMREM). Absent in headless tests,
-     *  where the skybox load is skipped rather than substituting a placeholder. */
-    renderer?: THREE.WebGLRenderer;
-    /** Scene-level render-feature overrides (`environment.rendering`), populated by
-     *  `instantiateScene` once `data.environment` is known. Read by the F7 mesh.lod
-     *  master-gate check (`resolveRenderSettings(ctx.sceneRendering, def.render)`). */
-    sceneRendering?: RenderScope;
-}
-/** Handle returned from loadScene — call update() each frame to tick animations. */
-export interface SceneInstance {
-    update(dt: number): void;
-    dispose(): void;
-    /** Pre-baked navmesh loaded from sibling .navmesh file, if present. */
-    navMesh?: NavMeshManager | undefined;
-    /** Cameras defined in the scene file. First entry is typically the "main" camera. */
-    cameras: THREE.Camera[];
-    /** Parsed scene environment, if any — lets the runtime apply post-processing
-     *  (which needs the composer/camera the loader doesn't have). */
-    environment?: SceneEnvironment | undefined;
-    /**
-     * Authored entity id -> spawned Object3D (design/24-scene-ui.md D5). The
-     * SAME map `spawnEntity`/`createSceneJoints` build internally (id-less
-     * entities are auto-UUID'd before insertion, so every spawned entity has an
-     * entry) -- exposed so the scene adapter's default `worldProjector` can
-     * resolve a `trackEntity` id to a live Object3D without a second id
-     * registry. Both `loadScene` and `loadSceneFromData` funnel through the one
-     * `instantiateScene` return site, so this is populated identically for both.
-     */
-    entities: ReadonlyMap<string, THREE.Object3D>;
-}
-/**
- * Loads a .vscn.json file and instantiates all entities.
- *
- * Creates Three.js objects and Rapier bodies. The Object3D IS the entity —
- * there is no separate ECS id. Uses raw Three.js/Rapier calls — no abstraction.
- *
- * Returns a SceneInstance that must be ticked each frame (for GLTF animations).
- */
-export declare function loadScene(url: string, ctx: SceneLoadContext): Promise<SceneInstance>;
-/**
- * Instantiate a scene from an already-parsed SceneFile.
- *
- * Same as loadScene but skips the fetch — useful when the scene data is
- * already in memory (e.g. serialized from the editor for play-mode preview).
- */
-export declare function loadSceneFromData(data: SceneFile, ctx: SceneLoadContext): Promise<SceneInstance>;
-/**
- * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — resolve `EntityRefSchema`
- * component fields from the authored string id to the live `Object3D`.
- *
- * Modeled directly on `createSceneJoints` above (same walk, same `idMap`,
- * same "missing target" shape) — the difference is WHAT gets resolved
- * (a component field, discovered via the component's own static schema)
- * and HOW a miss is handled: a joint with a missing target logs a warning
- * and skips it; a missing entity-ref id is a loud load error (throw) per
- * the design doc's AC, because a component that expects a live `Object3D`
- * at `init()` cannot safely run with a dangling string in that field.
- *
- * Must run AFTER every entity is spawned (idMap is complete — components are
- * attached during spawn too, so by this point every instance's ref field
- * still holds its raw authored string id) and BEFORE
- * `componentManager.initAll()`, so `init()` observes the resolved
- * `Object3D`, not the string. Resolves through the SAME `idMap`
- * `createSceneJoints` uses — no new registry (G3).
- */
-export declare function resolveEntityRefs(entities: SceneEntity[], idMap: Map<string, THREE.Object3D>, manager: ComponentManager): void;
-/** Handle returned from spawnPrefab — call update() each frame to tick animations. */
-export interface SpawnedPrefab {
-    /** The Object3D of the spawned prefab root (added to the scene). */
-    object3D: THREE.Object3D;
-    /**
-     * Tick standalone `animation.autoplay` clips for this prefab. A GameComponent
-     * that attaches its own XState-driven animation binding (E5 — see
-     * `xstate-animation-binding.ts`) ticks that binding itself, so this is a
-     * no-op for those. Call once per frame, mirroring SceneInstance.update.
-     */
-    update(dt: number): void;
-    /** Stop any mixers this prefab created. */
-    dispose(): void;
-}
-/**
- * Spawn a prefab instance at runtime from gameplay code.
- *
- * Returns a {@link SpawnedPrefab}. The previous version passed throwaway
- * tickFns/mixers arrays, so a runtime-spawned prefab's `animation.autoplay`
- * never advanced. Now the tick functions are captured and exposed via
- * `update()`, consistent with how loadScene's SceneInstance.update drives
- * animations.
- *
- * Usage:
- *   const crate = await spawnPrefab('/data/prefabs/crate.prefab.json', ctx, {
- *     transform: { position: [x, y, z] },
- *     components: { Health: { current: 50 } },
- *   });
- *   // each frame (only needed for autoplay clips):
- *   crate.update(dt);
- */
-export declare function spawnPrefab(prefabUrl: string, ctx: SceneLoadContext, overrides?: Partial<SceneEntity>): Promise<SpawnedPrefab>;
-//# sourceMappingURL=scene-loader.d.ts.map

package/dist/scene/scene-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scene-loader.d.ts","sourceRoot":"","sources":["../../src/scene/scene-loader.ts"],"names":[],"mappings":"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"}