@vgai/engine 0.5.0 → 0.5.2

package/dist/scene/asset-ref-check.d.ts

@@ -1,88 +0,0 @@
-/**
- * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
- *
- * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
- * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
- * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
- * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
- * WITHOUT the SDK importing from the CLI — that would invert the intended
- * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
- * is the correct shared home: both the CLI and the SDK already depend
- * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
- * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
- * scene-layer machinery neither caller re-implements.
- *
- * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
- * schema only checks that e.g. `materialRef` is a STRING — never that the
- * string points at anything real. A diff introducing
- * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
- * malformed) passes ordinary scene/patch validation and would be written;
- * the failure would otherwise only surface later, at runtime asset fetch.
- * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
- * reference the diff INTRODUCED (present in `result`, absent from
- * `inputScene` — deliberately not pre-existing refs, so a scene with
- * unrelated prior breakage can still receive an unrelated repair;
- * `validate-scenes` remains the whole-project content gate) against disk,
- * refusing the write if anything is missing or fails its own schema.
- *
- * Reference kinds and their treatment (unchanged from the original CLI-only
- * implementation):
- *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
- *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
- *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
- *     deep — the referenced prefab file itself must exist and parse; assets
- *     IT references are that file's own concern. (`animation.animGraph` ->
- *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
- *   - Existence-checked only (binary formats with no Zod schema to parse
- *     them through): gltf `mesh.src`, every material texture-map path
- *     (including the nested clearcoat/transmission/sheen/iridescence groups),
- *     `particles.material.map`, `audio.src`, `environment.skybox`.
- *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
- *     `.prefab.json` field references an input map.
- */
-import type { SceneFile } from './scene-types';
-/** One asset reference found in a scene document: where it is + what it points at. */
-export interface AssetRef {
-    /** The authored path string (web-root-relative, optionally /-prefixed). */
-    path: string;
-    /** Human-readable field location for error messages, e.g. `entity "crate" field materialRef`. */
-    field: string;
-    kind: 'material' | 'prefab' | 'binary';
-}
-/**
- * One asset reference that failed to dereference. `reason` is a one-line-or-
- * more human-readable explanation (schema-validation failures may be
- * multi-line); `field`/`path` mirror `AssetRef` and `diskPath` is the
- * resolved absolute path that was checked, so every caller (CLI text report,
- * SDK structured error data) can build its own presentation from the same
- * facts without re-deriving them.
- */
-export interface AssetRefError {
-    field: string;
-    path: string;
-    diskPath: string;
-    reason: string;
-}
-/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
-export declare function collectAssetRefs(doc: SceneFile): AssetRef[];
-/**
- * Resolve the asset root the scene's references are relative to. Asset paths
- * are web-root-relative (the runtime fetches them from the served `public/`
- * directory), and scene files conventionally live INSIDE `public/`
- * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
- * named `public` is the root. Fallback for scenes not under a `public/`
- * ancestor: the scene's own directory.
- */
-export declare function findAssetRoot(scenePath: string): string;
-/**
- * Dereference every asset reference `result` introduces relative to
- * `inputScene` (present in the result, absent from the input) against disk,
- * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
- * structured errors (empty = every new reference resolved and validated) —
- * never throws; callers decide how to present/escalate a non-empty result
- * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
- * a declared `ASSET_REF_INVALID` `OperationError`).
- */
-export declare function dereferenceNewAssetRefs(inputScene: SceneFile, result: SceneFile, scenePath: string): AssetRefError[];
-//# sourceMappingURL=asset-ref-check.d.ts.map

package/dist/scene/asset-ref-check.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-ref-check.d.ts","sourceRoot":"","sources":["../../src/scene/asset-ref-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AA4BD,iIAAiI;AACjI,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,QAAQ,EAAE,CA0D3D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CASvD;AAOD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,EACrB,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,GAChB,aAAa,EAAE,CAkDjB"}

package/dist/scene/asset-ref-check.js

@@ -1,214 +0,0 @@
-/**
- * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
- *
- * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
- * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
- * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
- * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
- * WITHOUT the SDK importing from the CLI — that would invert the intended
- * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
- * is the correct shared home: both the CLI and the SDK already depend
- * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
- * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
- * scene-layer machinery neither caller re-implements.
- *
- * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
- * schema only checks that e.g. `materialRef` is a STRING — never that the
- * string points at anything real. A diff introducing
- * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
- * malformed) passes ordinary scene/patch validation and would be written;
- * the failure would otherwise only surface later, at runtime asset fetch.
- * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
- * reference the diff INTRODUCED (present in `result`, absent from
- * `inputScene` — deliberately not pre-existing refs, so a scene with
- * unrelated prior breakage can still receive an unrelated repair;
- * `validate-scenes` remains the whole-project content gate) against disk,
- * refusing the write if anything is missing or fails its own schema.
- *
- * Reference kinds and their treatment (unchanged from the original CLI-only
- * implementation):
- *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
- *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
- *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
- *     deep — the referenced prefab file itself must exist and parse; assets
- *     IT references are that file's own concern. (`animation.animGraph` ->
- *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
- *   - Existence-checked only (binary formats with no Zod schema to parse
- *     them through): gltf `mesh.src`, every material texture-map path
- *     (including the nested clearcoat/transmission/sheen/iridescence groups),
- *     `particles.material.map`, `audio.src`, `environment.skybox`.
- *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
- *     `.prefab.json` field references an input map.
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
-import { parseMaterialFile, parsePrefabFile, SceneParseError } from './parse';
-/** Material texture-map fields that hold image paths — top-level and nested feature groups. */
-const MATERIAL_MAP_KEYS = [
-    'map',
-    'normalMap',
-    'emissiveMap',
-    'aoMap',
-    'roughnessMap',
-    'metalnessMap',
-    'displacementMap',
-];
-const MATERIAL_GROUP_MAP_KEYS = {
-    clearcoat: ['clearcoatMap', 'clearcoatRoughnessMap'],
-    transmission: ['transmissionMap'],
-    sheen: ['sheenColorMap', 'sheenRoughnessMap'],
-    iridescence: ['iridescenceMap', 'iridescenceThicknessMap'],
-};
-/** Same file-path-vs-registry-id heuristic as `asset-paths.ts`. */
-function isFilePrefab(value) {
-    return value.includes('/');
-}
-function entityLabel(e) {
-    return e.id ? `entity "${e.name}" (id ${e.id})` : `entity "${e.name}"`;
-}
-/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
-export function collectAssetRefs(doc) {
-    const refs = [];
-    function walk(entities) {
-        for (const e of entities) {
-            const label = entityLabel(e);
-            if (e.mesh?.type === 'gltf' && e.mesh.src) {
-                refs.push({ path: e.mesh.src, field: `${label} field mesh.src`, kind: 'binary' });
-            }
-            if (e.material) {
-                const mat = e.material;
-                for (const key of MATERIAL_MAP_KEYS) {
-                    const val = mat[key];
-                    if (typeof val === 'string') {
-                        refs.push({ path: val, field: `${label} field material.${key}`, kind: 'binary' });
-                    }
-                }
-                for (const [group, keys] of Object.entries(MATERIAL_GROUP_MAP_KEYS)) {
-                    const groupVal = mat[group];
-                    if (groupVal && typeof groupVal === 'object') {
-                        for (const key of keys) {
-                            const val = groupVal[key];
-                            if (typeof val === 'string') {
-                                refs.push({
-                                    path: val,
-                                    field: `${label} field material.${group}.${key}`,
-                                    kind: 'binary',
-                                });
-                            }
-                        }
-                    }
-                }
-            }
-            if (e.materialRef) {
-                refs.push({ path: e.materialRef, field: `${label} field materialRef`, kind: 'material' });
-            }
-            if (e.particles?.material?.map) {
-                refs.push({
-                    path: e.particles.material.map,
-                    field: `${label} field particles.material.map`,
-                    kind: 'binary',
-                });
-            }
-            if (e.audio?.src) {
-                refs.push({ path: e.audio.src, field: `${label} field audio.src`, kind: 'binary' });
-            }
-            if (e.prefab && isFilePrefab(e.prefab)) {
-                refs.push({ path: e.prefab, field: `${label} field prefab`, kind: 'prefab' });
-            }
-            if (e.children)
-                walk(e.children);
-        }
-    }
-    walk(doc.entities);
-    if (doc.environment?.skybox) {
-        refs.push({ path: doc.environment.skybox, field: 'environment.skybox', kind: 'binary' });
-    }
-    return refs;
-}
-/**
- * Resolve the asset root the scene's references are relative to. Asset paths
- * are web-root-relative (the runtime fetches them from the served `public/`
- * directory), and scene files conventionally live INSIDE `public/`
- * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
- * named `public` is the root. Fallback for scenes not under a `public/`
- * ancestor: the scene's own directory.
- */
-export function findAssetRoot(scenePath) {
-    const dir = resolve(dirname(scenePath));
-    let cursor = dir;
-    for (;;) {
-        if (basename(cursor) === 'public')
-            return cursor;
-        const parent = dirname(cursor);
-        if (parent === cursor)
-            return dir;
-        cursor = parent;
-    }
-}
-/** Format Zod/scene-parse issues as `path: message`, one per line. */
-function formatIssues(issues) {
-    return issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
-}
-/**
- * Dereference every asset reference `result` introduces relative to
- * `inputScene` (present in the result, absent from the input) against disk,
- * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
- * structured errors (empty = every new reference resolved and validated) —
- * never throws; callers decide how to present/escalate a non-empty result
- * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
- * a declared `ASSET_REF_INVALID` `OperationError`).
- */
-export function dereferenceNewAssetRefs(inputScene, result, scenePath) {
-    const preexisting = new Set(collectAssetRefs(inputScene).map((r) => r.path));
-    const newRefs = collectAssetRefs(result).filter((r) => !preexisting.has(r.path));
-    if (newRefs.length === 0)
-        return [];
-    const assetRoot = findAssetRoot(scenePath);
-    const errors = [];
-    for (const ref of newRefs) {
-        const diskPath = join(assetRoot, ref.path.replace(/^\//, ''));
-        if (!existsSync(diskPath)) {
-            errors.push({
-                field: ref.field,
-                path: ref.path,
-                diskPath,
-                reason: `file not found at ${diskPath} (resolved against ${assetRoot})`,
-            });
-            continue;
-        }
-        if (ref.kind === 'binary')
-            continue; // existence-only (see the exclusion note above)
-        let json;
-        try {
-            json = JSON.parse(readFileSync(diskPath, 'utf-8'));
-        }
-        catch (err) {
-            errors.push({
-                field: ref.field,
-                path: ref.path,
-                diskPath,
-                reason: `${diskPath} is not valid JSON: ${err instanceof Error ? err.message : err}`,
-            });
-            continue;
-        }
-        try {
-            if (ref.kind === 'material') {
-                parseMaterialFile(json, diskPath);
-            }
-            else {
-                parsePrefabFile(json, diskPath);
-            }
-        }
-        catch (err) {
-            const detail = err instanceof SceneParseError ? `\n${formatIssues(err.issues)}` : ` ${err}`;
-            errors.push({
-                field: ref.field,
-                path: ref.path,
-                diskPath,
-                reason: `${diskPath} fails schema validation:${detail}`,
-            });
-        }
-    }
-    return errors;
-}

package/dist/scene/asset-registry.d.ts

@@ -1,38 +0,0 @@
-/**
- * Central asset registry — stores per-asset metadata (import corrections, etc.).
- *
- * Loaded once via fetch(), cached in memory. Both the runtime scene loader
- * and editor entity factory import from this module.
- */
-import * as THREE from 'three';
-export interface ImportCorrection {
-    /** Uniform scale factor applied to the GLTF clone before entity transform. */
-    scale?: number;
-    /** Euler rotation in degrees [x, y, z] applied to the GLTF clone before entity transform. */
-    rotation?: [number, number, number];
-}
-export interface AssetMeta {
-    importCorrection?: ImportCorrection;
-}
-/**
- * Apply an asset's visual-only import correction to the loaded GLTF content.
- * Call this on the model child, before placing it under the entity wrapper, so
- * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
- * -Z-forward coordinate contract.
- */
-export declare function applyImportCorrection(content: THREE.Object3D, correction: ImportCorrection | undefined): void;
-type AssetRegistry = Record<string, AssetMeta>;
-/**
- * Fetch and cache the asset registry. Safe to call multiple times —
- * returns the cached result after the first successful load.
- */
-export declare function loadRegistry(): Promise<AssetRegistry>;
-/** Get metadata for an asset path, or undefined if not in the registry. */
-export declare function getAssetMeta(path: string): AssetMeta | undefined;
-/**
- * Update the in-memory cache directly (used by the editor after saving
- * import settings, to avoid a re-fetch).
- */
-export declare function setRegistryCache(data: AssetRegistry): void;
-export {};
-//# sourceMappingURL=asset-registry.d.ts.map

package/dist/scene/asset-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-registry.d.ts","sourceRoot":"","sources":["../../src/scene/asset-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,KAAK,CAAC,QAAQ,EACvB,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,IAAI,CAUN;AAED,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAU/C;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAgBrD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAIhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAG1D"}

package/dist/scene/asset-registry.js

@@ -1,66 +0,0 @@
-/**
- * Central asset registry — stores per-asset metadata (import corrections, etc.).
- *
- * Loaded once via fetch(), cached in memory. Both the runtime scene loader
- * and editor entity factory import from this module.
- */
-import * as THREE from 'three';
-import { resolveUrl } from '../loader';
-/**
- * Apply an asset's visual-only import correction to the loaded GLTF content.
- * Call this on the model child, before placing it under the entity wrapper, so
- * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
- * -Z-forward coordinate contract.
- */
-export function applyImportCorrection(content, correction) {
-    if (!correction)
-        return;
-    if (correction.scale !== undefined)
-        content.scale.multiplyScalar(correction.scale);
-    if (correction.rotation) {
-        content.rotation.set(THREE.MathUtils.degToRad(correction.rotation[0]), THREE.MathUtils.degToRad(correction.rotation[1]), THREE.MathUtils.degToRad(correction.rotation[2]));
-    }
-}
-let registryCache = null;
-let registryPromise = null;
-/** Normalize asset path for registry lookup (strip leading slash). */
-function normalize(path) {
-    return path.startsWith('/') ? path.slice(1) : path;
-}
-/**
- * Fetch and cache the asset registry. Safe to call multiple times —
- * returns the cached result after the first successful load.
- */
-export function loadRegistry() {
-    if (registryCache)
-        return Promise.resolve(registryCache);
-    if (registryPromise)
-        return registryPromise;
-    registryPromise = fetch(resolveUrl('asset-registry.json'))
-        .then((res) => {
-        if (!res.ok)
-            return {};
-        return res.json();
-    })
-        .catch(() => ({}))
-        .then((data) => {
-        registryCache = data;
-        return data;
-    });
-    return registryPromise;
-}
-/** Get metadata for an asset path, or undefined if not in the registry. */
-export function getAssetMeta(path) {
-    if (!registryCache)
-        return undefined;
-    // Try exact match first, then normalized
-    return registryCache[path] ?? registryCache[normalize(path)];
-}
-/**
- * Update the in-memory cache directly (used by the editor after saving
- * import settings, to avoid a re-fetch).
- */
-export function setRegistryCache(data) {
-    registryCache = data;
-    registryPromise = null;
-}

package/dist/scene/collider-dimensions.d.ts

@@ -1,63 +0,0 @@
-/**
- * Shared world-scale collider dimension math (T1.2).
- *
- * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
- * shape is defined in absolute world units at creation time. Three.js meshes,
- * by contrast, scale visually for free via the normal Object3D hierarchy. To
- * keep the physical collider matching what's on screen, the LOADER must bake
- * the entity's composed WORLD scale (self × every transformed ancestor — see
- * T1.1's world-transform composition) into the collider's dimensions at
- * creation time.
- *
- * This is the ONE place that does that math, so both the runtime loader
- * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
- * (gizmo-registry.ts) agree on exactly the same numbers — previously the
- * editor gizmo only rendered the entity's own live Object3D scale (via normal
- * Three.js parenting) while the Rapier body ignored scale entirely, so the
- * two silently agreed by coincidence for uniform scale and disagreed for
- * everything else.
- *
- * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
- * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
- * round collider's round axes throws a loud error naming the entity, rather
- * than silently simulating (or rendering) the wrong shape.
- */
-import type { SceneCollider } from './scene-types';
-export interface ColliderWorldDimensions {
-    /** cuboid only: per-axis half-extents, world scale applied. */
-    halfExtents?: [number, number, number];
-    /** ball/capsule only: radius, world scale applied (uniform axes required). */
-    radius?: number;
-    /** capsule only: half-height along the capsule's axis, world scale applied. */
-    halfHeight?: number;
-}
-/**
- * Compute a collider's WORLD-space dimensions given the entity's composed
- * world scale (self × ancestors, per-axis, in the entity's own local frame —
- * X/Y/Z order matches `SceneEntity.transform.scale`).
- *
- * @param collider - the entity's authored (unscaled) collider definition.
- * @param worldScale - composed world scale `[x, y, z]`.
- * @param entityLabel - human-readable entity identifier, used only in thrown
- *   error messages (loud-failure naming, never silently wrong).
- * @throws if a ball/capsule collider's round cross-section axes have a
- *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
- */
-export declare function computeColliderWorldDimensions(collider: SceneCollider, worldScale: readonly [number, number, number], entityLabel: string): ColliderWorldDimensions;
-/**
- * Compute a collider's WORLD-scaled translation offset (sibling to
- * {@link computeColliderWorldDimensions}, same input contract).
- *
- * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
- * notion of a parent Object3D's scale — like dimensions, an authored `offset`
- * (in the entity's own local units) must be scaled per-axis by the entity's
- * composed world scale before being handed to Rapier, or the collider's center
- * silently drifts away from its visual anchor point under any non-1 scale.
- * Applies to every collider type (including trimesh, which is otherwise not
- * handled by {@link computeColliderWorldDimensions}).
- *
- * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
- * guard call sites already use.
- */
-export declare function computeColliderWorldOffset(offset: readonly [number, number, number] | undefined, worldScale: readonly [number, number, number]): [number, number, number] | undefined;
-//# sourceMappingURL=collider-dimensions.d.ts.map

package/dist/scene/collider-dimensions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"collider-dimensions.d.ts","sourceRoot":"","sources":["../../src/scene/collider-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAKnD,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,uBAAuB,CA4CzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACrD,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAItC"}

package/dist/scene/collider-dimensions.js

@@ -1,98 +0,0 @@
-/**
- * Shared world-scale collider dimension math (T1.2).
- *
- * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
- * shape is defined in absolute world units at creation time. Three.js meshes,
- * by contrast, scale visually for free via the normal Object3D hierarchy. To
- * keep the physical collider matching what's on screen, the LOADER must bake
- * the entity's composed WORLD scale (self × every transformed ancestor — see
- * T1.1's world-transform composition) into the collider's dimensions at
- * creation time.
- *
- * This is the ONE place that does that math, so both the runtime loader
- * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
- * (gizmo-registry.ts) agree on exactly the same numbers — previously the
- * editor gizmo only rendered the entity's own live Object3D scale (via normal
- * Three.js parenting) while the Rapier body ignored scale entirely, so the
- * two silently agreed by coincidence for uniform scale and disagreed for
- * everything else.
- *
- * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
- * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
- * round collider's round axes throws a loud error naming the entity, rather
- * than silently simulating (or rendering) the wrong shape.
- */
-import { DEFAULTS } from './defaults';
-/** Axes are considered "uniform enough" within this tolerance (float error only). */
-const UNIFORM_SCALE_EPSILON = 1e-4;
-/**
- * Compute a collider's WORLD-space dimensions given the entity's composed
- * world scale (self × ancestors, per-axis, in the entity's own local frame —
- * X/Y/Z order matches `SceneEntity.transform.scale`).
- *
- * @param collider - the entity's authored (unscaled) collider definition.
- * @param worldScale - composed world scale `[x, y, z]`.
- * @param entityLabel - human-readable entity identifier, used only in thrown
- *   error messages (loud-failure naming, never silently wrong).
- * @throws if a ball/capsule collider's round cross-section axes have a
- *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
- */
-export function computeColliderWorldDimensions(collider, worldScale, entityLabel) {
-    const [sx, sy, sz] = worldScale;
-    switch (collider.type) {
-        case 'cuboid': {
-            const he = collider.halfExtents ?? DEFAULTS.collider.cuboid.halfExtents;
-            return { halfExtents: [he[0] * sx, he[1] * sy, he[2] * sz] };
-        }
-        case 'ball': {
-            if (Math.abs(sx - sy) > UNIFORM_SCALE_EPSILON ||
-                Math.abs(sy - sz) > UNIFORM_SCALE_EPSILON ||
-                Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
-                throw new Error(`Entity "${entityLabel}" has a "ball" collider under a non-uniform world scale ` +
-                    `[${sx}, ${sy}, ${sz}]. Rapier ball colliders are always perfect spheres — a ` +
-                    `non-uniform scale cannot be represented and would silently simulate the wrong ` +
-                    `shape. Use a uniform scale on this entity (and every transformed ancestor), or ` +
-                    `switch to a "cuboid" collider.`);
-            }
-            const radius = collider.radius ?? DEFAULTS.collider.ball.radius;
-            return { radius: radius * sx };
-        }
-        case 'capsule': {
-            // Rapier capsules run their half-height along the local Y axis, with a
-            // circular cross-section in the XZ plane — so only X/Z need to match.
-            if (Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
-                throw new Error(`Entity "${entityLabel}" has a "capsule" collider whose X/Z world scale differs ` +
-                    `(x=${sx}, z=${sz}). Rapier capsule colliders have a circular cross-section — a ` +
-                    `non-uniform X/Z scale cannot be represented and would silently simulate the ` +
-                    `wrong shape. Use a uniform X/Z scale on this entity (and every transformed ` +
-                    `ancestor), or switch to a "cuboid" collider.`);
-            }
-            const radius = collider.radius ?? DEFAULTS.collider.capsule.radius;
-            const halfHeight = collider.halfHeight ?? DEFAULTS.collider.capsule.halfHeight;
-            return { radius: radius * sx, halfHeight: halfHeight * sy };
-        }
-        default:
-            return {};
-    }
-}
-/**
- * Compute a collider's WORLD-scaled translation offset (sibling to
- * {@link computeColliderWorldDimensions}, same input contract).
- *
- * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
- * notion of a parent Object3D's scale — like dimensions, an authored `offset`
- * (in the entity's own local units) must be scaled per-axis by the entity's
- * composed world scale before being handed to Rapier, or the collider's center
- * silently drifts away from its visual anchor point under any non-1 scale.
- * Applies to every collider type (including trimesh, which is otherwise not
- * handled by {@link computeColliderWorldDimensions}).
- *
- * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
- * guard call sites already use.
- */
-export function computeColliderWorldOffset(offset, worldScale) {
-    if (!offset)
-        return undefined;
-    const [sx, sy, sz] = worldScale;
-    return [offset[0] * sx, offset[1] * sy, offset[2] * sz];
-}

package/dist/scene/component-registry.d.ts

@@ -1,22 +0,0 @@
-import type * as THREE from 'three';
-import type { ComponentManager } from '../ecs/component-manager';
-import { type GameComponentClass } from '../ecs/game-component';
-/** A registry mapping component names to GameComponent classes. */
-export type ComponentRegistry = Record<string, GameComponentClass>;
-/** Type guard: is this value a GameComponent class? `instanceof` alone is NOT
- *  enough: a scaffolded project's node-side scripts resolve TWO physical
- *  copies of the engine (published `@vgai/engine/*` + the `@engine/*` source
- *  alias), and a class extending the OTHER copy's `GameComponent` fails the
- *  prototype-chain check — so this also accepts the cross-copy
- *  {@link GAME_COMPONENT_BRAND}. */
-export declare function isGameComponentClass(entry: unknown): entry is GameComponentClass;
-/**
- * Apply components from scene JSON data onto an entity (an Object3D).
- *
- * For each named component: look up its class in the registry, validate +
- * default the authored data through the optional `static schema` (Zod), assign
- * onto a fresh instance, and attach it via the ComponentManager (which wires the
- * Object3D + physics refs and queues init()).
- */
-export declare function applyComponents(registry: ComponentRegistry, object3D: THREE.Object3D, components: Record<string, Record<string, unknown>>, manager: ComponentManager): void;
-//# sourceMappingURL=component-registry.d.ts.map

package/dist/scene/component-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"component-registry.d.ts","sourceRoot":"","sources":["../../src/scene/component-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAEnE;;;;;oCAKoC;AACpC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAIhF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ,EACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnD,OAAO,EAAE,gBAAgB,GACxB,IAAI,CAcN"}

package/dist/scene/component-registry.js

@@ -1,37 +0,0 @@
-import { GAME_COMPONENT_BRAND, GameComponent, } from '../ecs/game-component';
-/** Type guard: is this value a GameComponent class? `instanceof` alone is NOT
- *  enough: a scaffolded project's node-side scripts resolve TWO physical
- *  copies of the engine (published `@vgai/engine/*` + the `@engine/*` source
- *  alias), and a class extending the OTHER copy's `GameComponent` fails the
- *  prototype-chain check — so this also accepts the cross-copy
- *  {@link GAME_COMPONENT_BRAND}. */
-export function isGameComponentClass(entry) {
-    if (typeof entry !== 'function')
-        return false;
-    if (entry.prototype instanceof GameComponent)
-        return true;
-    return entry[GAME_COMPONENT_BRAND] === true;
-}
-/**
- * Apply components from scene JSON data onto an entity (an Object3D).
- *
- * For each named component: look up its class in the registry, validate +
- * default the authored data through the optional `static schema` (Zod), assign
- * onto a fresh instance, and attach it via the ComponentManager (which wires the
- * Object3D + physics refs and queues init()).
- */
-export function applyComponents(registry, object3D, components, manager) {
-    for (const [name, data] of Object.entries(components)) {
-        const Klass = registry[name];
-        if (!Klass) {
-            throw new Error(`Component "${name}" not found in registry`);
-        }
-        const parsed = Klass.schema ? Klass.schema.parse(data) : data;
-        const inst = new Klass();
-        Object.assign(inst, parsed);
-        // T5.4: record the registry name + raw authored data so a later `hotSwap`
-        // keys on this stable identity (not the live `constructor.name`) and can
-        // re-validate `data` against a NEW class version's schema.
-        manager.attach(object3D, inst, { key: name, props: data });
-    }
-}