@vgai/engine 0.5.5 → 0.5.7

package/dist/asset-formats/render-env.js

@@ -0,0 +1,300 @@
+/**
+ * Render settings — the tone-mapping / post-processing / render-feature scope
+ * the engine's renderer setup reads (`setup/setup-renderer.ts`).
+ *
+ * This used to be the `environment` block of the retired `.vscn.json` scene
+ * format (WO-8). The format is gone; these three scopes stayed because
+ * `setup-renderer.ts` genuinely reads every field and builds the
+ * postprocessing chain from them. Everything that was `.vscn`-only (`skybox`,
+ * `fog`, `ambient`, `background`, `envMapIntensity`, `navigation`, `physics`)
+ * went with the format.
+ */
+import { z } from 'zod';
+import { buildRenderingZod } from '../render/render-features';
+export const ToneMappingDescriptorSchema = z
+    .object({
+    mode: z
+        .enum(['none', 'linear', 'reinhard', 'cineon', 'aces', 'agx'])
+        .optional()
+        .describe('Tone mapping operator'),
+    exposure: z.number().optional().describe('Exposure level'),
+})
+    .describe('Tone mapping configuration');
+export const PostProcessingDescriptorSchema = z
+    .object({
+    // ── Bloom & Vignette ──────────────────────────────────────────────────
+    bloom: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable bloom effect'),
+        intensity: z.number().optional().describe('Bloom intensity multiplier'),
+        luminanceThreshold: z.number().optional().describe('Minimum luminance to trigger bloom'),
+        luminanceSmoothing: z
+            .number()
+            .optional()
+            .describe('Smoothing applied to luminance threshold'),
+    })
+        .optional()
+        .describe('Bloom glow effect'),
+    vignette: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable vignette effect'),
+        darkness: z.number().optional().describe('Vignette darkness intensity'),
+        offset: z.number().optional().describe('Vignette offset from center'),
+    })
+        .optional()
+        .describe('Screen-edge darkening effect'),
+    // ── Color adjustments ─────────────────────────────────────────────────
+    brightnessContrast: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable brightness/contrast adjustment'),
+        brightness: z.number().optional().describe('Brightness adjustment (-1 to 1)'),
+        contrast: z.number().optional().describe('Contrast adjustment (-1 to 1)'),
+    })
+        .optional()
+        .describe('Brightness and contrast color adjustment'),
+    hueSaturation: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable hue/saturation adjustment'),
+        hue: z.number().optional().describe('Hue rotation in radians'),
+        saturation: z.number().optional().describe('Saturation adjustment (-1 to 1)'),
+    })
+        .optional()
+        .describe('Hue rotation and saturation color adjustment'),
+    sepia: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable sepia tone'),
+        intensity: z.number().optional().describe('Sepia effect intensity (0 to 1)'),
+    })
+        .optional()
+        .describe('Warm sepia tone for vintage photograph look'),
+    colorDepth: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable color depth reduction'),
+        bits: z.number().optional().describe('Number of color bits per channel (1–16)'),
+    })
+        .optional()
+        .describe('Reduce color bit depth for posterized/banded look'),
+    // ── Lens effects ──────────────────────────────────────────────────────
+    chromaticAberration: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable chromatic aberration'),
+        offsetX: z.number().optional().describe('Horizontal color fringe offset'),
+        offsetY: z.number().optional().describe('Vertical color fringe offset'),
+        radialModulation: z.boolean().optional().describe('Increase effect toward screen edges'),
+        modulationOffset: z.number().optional().describe('Radial modulation offset from center'),
+    })
+        .optional()
+        .describe('Lens chromatic aberration (color fringing at screen edges)'),
+    lensDistortion: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable lens distortion'),
+        distortionX: z.number().optional().describe('Horizontal barrel/pincushion distortion'),
+        distortionY: z.number().optional().describe('Vertical barrel/pincushion distortion'),
+        focalLengthX: z.number().optional().describe('Horizontal focal length'),
+        focalLengthY: z.number().optional().describe('Vertical focal length'),
+        skew: z.number().optional().describe('Lens skew angle'),
+    })
+        .optional()
+        .describe('Barrel/pincushion lens distortion'),
+    depthOfField: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable depth of field'),
+        worldFocusDistance: z.number().optional().describe('Focus distance in world units'),
+        worldFocusRange: z.number().optional().describe('Focus range in world units'),
+        bokehScale: z.number().optional().describe('Bokeh blur scale'),
+        focalLength: z.number().optional().describe('Camera focal length in mm'),
+    })
+        .optional()
+        .describe('Physically-based depth of field with bokeh blur'),
+    tiltShift: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable tilt-shift effect'),
+        offset: z.number().optional().describe('Focus band offset from center'),
+        rotation: z.number().optional().describe('Focus band rotation in radians'),
+        focusArea: z.number().optional().describe('Focus band width (0–1)'),
+        feather: z.number().optional().describe('Blur falloff smoothness'),
+    })
+        .optional()
+        .describe('Tilt-shift miniature-world blur effect'),
+    // ── Film / retro ──────────────────────────────────────────────────────
+    noise: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable film grain noise'),
+        premultiply: z
+            .boolean()
+            .optional()
+            .describe('Multiply noise with input color instead of adding'),
+    })
+        .optional()
+        .describe('Random per-pixel noise overlay (film grain)'),
+    scanline: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable scanline overlay'),
+        density: z.number().optional().describe('Number of scanlines across screen height'),
+    })
+        .optional()
+        .describe('Horizontal scanline overlay (CRT monitor look)'),
+    dotScreen: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable dot screen halftone'),
+        angle: z.number().optional().describe('Pattern angle in radians'),
+        scale: z.number().optional().describe('Pattern dot scale'),
+    })
+        .optional()
+        .describe('Halftone dot pattern (newspaper/comic look)'),
+    grid: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable grid overlay'),
+        scale: z.number().optional().describe('Grid cell scale'),
+        lineWidth: z.number().optional().describe('Grid line width'),
+    })
+        .optional()
+        .describe('Visible grid pattern overlay'),
+    pixelation: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable pixelation'),
+        granularity: z.number().optional().describe('Pixel size (higher = more pixelated)'),
+    })
+        .optional()
+        .describe('Reduce resolution for pixel-art / mosaic effect'),
+    glitch: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable digital glitch effect'),
+        delayX: z.number().optional().describe('Minimum delay between glitches (seconds)'),
+        delayY: z.number().optional().describe('Maximum delay between glitches (seconds)'),
+        durationX: z.number().optional().describe('Minimum glitch duration (seconds)'),
+        durationY: z.number().optional().describe('Maximum glitch duration (seconds)'),
+        strengthX: z.number().optional().describe('Minimum glitch strength'),
+        strengthY: z.number().optional().describe('Maximum glitch strength'),
+        columns: z.number().optional().describe('Number of glitch columns'),
+        ratio: z.number().optional().describe('Glitch ratio (0–1)'),
+    })
+        .optional()
+        .describe('Random digital glitch artifacts (block displacement, color shifting)'),
+    // ── Distortion ────────────────────────────────────────────────────────
+    shockWave: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable shock wave distortion'),
+        speed: z.number().optional().describe('Wave propagation speed'),
+        maxRadius: z.number().optional().describe('Maximum wave radius'),
+        waveSize: z.number().optional().describe('Width of the distortion wave'),
+        amplitude: z.number().optional().describe('Distortion strength'),
+        positionX: z.number().optional().describe('Wave origin X in world space'),
+        positionY: z.number().optional().describe('Wave origin Y in world space'),
+        positionZ: z.number().optional().describe('Wave origin Z in world space'),
+    })
+        .optional()
+        .describe('Expanding spherical distortion wave from a point'),
+    // ── Anti-aliasing ─────────────────────────────────────────────────────
+    smaa: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable SMAA anti-aliasing'),
+        preset: z
+            .enum(['low', 'medium', 'high', 'ultra'])
+            .optional()
+            .describe('Quality preset (higher = better quality, more cost)'),
+    })
+        .optional()
+        .describe('Subpixel Morphological Anti-Aliasing'),
+    // ── Ambient occlusion ─────────────────────────────────────────────────
+    ssao: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable screen-space ambient occlusion'),
+        radius: z.number().optional().describe('Occlusion sampling radius'),
+        intensity: z.number().optional().describe('Occlusion intensity multiplier'),
+        bias: z.number().optional().describe('Depth bias to reduce self-occlusion artifacts'),
+        samples: z.number().optional().describe('Number of occlusion samples per pixel'),
+        rings: z.number().optional().describe('Number of spiral sample rings'),
+        fade: z.number().optional().describe('Distance at which occlusion fades out'),
+        color: z.string().optional().describe('Occlusion tint color as CSS hex'),
+    })
+        .optional()
+        .describe('Screen-space ambient occlusion (darken creases and crevices)'),
+    n8ao: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable N8AO ambient occlusion'),
+        aoSamples: z.number().optional().describe('Number of AO samples (default 16)'),
+        aoRadius: z.number().optional().describe('AO sampling radius in world units'),
+        intensity: z.number().optional().describe('AO intensity multiplier'),
+        denoiseSamples: z.number().optional().describe('Number of denoise samples'),
+        denoiseRadius: z.number().optional().describe('Denoise blur radius'),
+        distanceFalloff: z.number().optional().describe('AO distance falloff'),
+        screenSpaceRadius: z
+            .boolean()
+            .optional()
+            .describe('Use screen-space radius instead of world-space'),
+        color: z.string().optional().describe('AO tint color as CSS hex'),
+        halfRes: z.boolean().optional().describe('Render AO at half resolution for performance'),
+    })
+        .optional()
+        .describe('High-quality ambient occlusion (N8AO — alternative to SSAO)'),
+    // ── Entity-referencing effects ────────────────────────────────────────
+    godRays: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable god rays'),
+        sourceEntity: z.string().optional().describe('Entity ID of the light source mesh'),
+        density: z.number().optional().describe('Ray density'),
+        decay: z.number().optional().describe('Ray intensity decay along distance'),
+        weight: z.number().optional().describe('Ray weight / brightness'),
+        exposure: z.number().optional().describe('Overall god ray exposure'),
+        samples: z.number().optional().describe('Number of ray-march samples'),
+    })
+        .optional()
+        .describe('Volumetric light shafts from a light source entity'),
+    outline: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable outline effect'),
+        tags: z.array(z.string()).optional().describe('Entity tags to outline'),
+        edgeStrength: z.number().optional().describe('Outline edge thickness / strength'),
+        pulseSpeed: z.number().optional().describe('Outline pulse animation speed (0 = no pulse)'),
+        visibleEdgeColor: z.string().optional().describe('Color of visible edges as CSS hex'),
+        hiddenEdgeColor: z
+            .string()
+            .optional()
+            .describe('Color of hidden/occluded edges as CSS hex'),
+        xRay: z.boolean().optional().describe('Show outline through occluding objects'),
+    })
+        .optional()
+        .describe('Highlight entities matching tags with colored outlines'),
+    // ── Screen-space reflections & GI (realism-effects) ───────────────────
+    ssr: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable screen-space reflections'),
+        intensity: z.number().optional().describe('Reflection intensity'),
+        exponent: z.number().optional().describe('Reflection falloff exponent'),
+        distance: z.number().optional().describe('Maximum reflection ray distance'),
+        thickness: z.number().optional().describe('Depth thickness for hit testing'),
+        maxRoughness: z.number().optional().describe('Maximum roughness for reflections (0–1)'),
+    })
+        .optional()
+        .describe('Screen-space reflections for reflective/glossy surfaces'),
+    ssgi: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable screen-space global illumination'),
+        intensity: z.number().optional().describe('Indirect light intensity'),
+        distance: z.number().optional().describe('Maximum GI ray distance'),
+        thickness: z.number().optional().describe('Depth thickness for hit testing'),
+        maxRoughness: z.number().optional().describe('Maximum roughness for GI (0–1)'),
+    })
+        .optional()
+        .describe('Screen-space global illumination (indirect lighting bounce)'),
+    motionBlur: z
+        .object({
+        enabled: z.boolean().optional().describe('Enable motion blur'),
+        intensity: z.number().optional().describe('Motion blur intensity'),
+        jitter: z.number().optional().describe('Sample jitter amount'),
+        samples: z.number().optional().describe('Number of blur samples'),
+    })
+        .optional()
+        .describe('Per-object motion blur from camera and object movement'),
+})
+    .describe('Post-processing effects');
+export const RenderEnvironmentSchema = z
+    .object({
+    toneMapping: ToneMappingDescriptorSchema.optional().describe('Tone mapping configuration'),
+    postProcessing: PostProcessingDescriptorSchema.optional().describe('Post-processing effects (bloom, vignette, SSAO, SSR, ...)'),
+    rendering: buildRenderingZod()
+        .optional()
+        .describe('Render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry.'),
+})
+    .describe('Renderer-level settings read by setup/setup-renderer.ts');

package/dist/asset-formats/tuples.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const Vec3Schema: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+export declare const QuatSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+export type Vec3 = z.infer<typeof Vec3Schema>;
+export type Quat = z.infer<typeof QuatSchema>;
+export declare const TransformSchema: z.ZodObject<{
+    position: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    rotation: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    scale: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+export type Transform = z.infer<typeof TransformSchema>;
+//# sourceMappingURL=tuples.d.ts.map

package/dist/asset-formats/tuples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tuples.d.ts","sourceRoot":"","sources":["../../src/asset-formats/tuples.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,2DAEc,CAAC;AACtC,eAAO,MAAM,UAAU,wEAEkB,CAAC;AAE1C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,eAAO,MAAM,eAAe;;;;iBAM4B,CAAC;AAEzD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/asset-formats/tuples.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export const Vec3Schema = z
+    .tuple([z.number(), z.number(), z.number()])
+    .describe('3D vector as [x, y, z]');
+export const QuatSchema = z
+    .tuple([z.number(), z.number(), z.number(), z.number()])
+    .describe('Quaternion as [x, y, z, w]');
+export const TransformSchema = z
+    .object({
+    position: Vec3Schema.optional().describe('World-space position [x, y, z]'),
+    rotation: QuatSchema.optional().describe('Rotation quaternion [x, y, z, w]'),
+    scale: Vec3Schema.optional().describe('Scale factor per axis [x, y, z]. Defaults to [1, 1, 1]'),
+})
+    .describe('Local transform relative to parent entity');

package/dist/asset-loaders.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/engine/src/animation/xstate-animation-binding.ts.)
+ *
+ * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
+ * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
+ * (entity-factory, scene-sync). Previously this logic was duplicated across six
+ * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
+ * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
+ * not propagate. Everything funnels through the shared loaders in `../loader`
+ * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
+ * LoadingManager / asset-prefix rewrite).
+ *
+ * Cache lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
+ * 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 asset N times is bounded (one
+ * entry per distinct URL, not per load). They are released only on full runtime
+ * teardown via {@link clearAssetCaches}.
+ */
+import type { SplatMesh } from '@sparkjsdev/spark';
+import * as THREE from 'three';
+/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
+export declare function loadTexture(url: string): THREE.Texture;
+/**
+ * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
+ * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
+ *
+ * Clone-safety contract (P0.2 — load-bearing, tested):
+ * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
+ * We give each clone its OWN materials (so scene cleanup can dispose them
+ * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
+ * so cleanup (engine create-runtime fullCleanup + editor scene-sync
+ * disposeObject3D) skips disposing the shared geometry buffers.
+ */
+export declare function loadGLTF(url: string): Promise<{
+    scene: THREE.Group;
+    animations: THREE.AnimationClip[];
+}>;
+/**
+ * Load one native Gaussian-splat asset as Spark's own Object3D.
+ *
+ * The URL cache stores immutable source bytes, not a live SplatMesh: every scene
+ * entity needs its own transformable/disposable Object3D, while repeated uses of
+ * the same SPZ must not download the multi-megabyte source more than once.
+ * Spark stays a lazy chunk so games without splats do not pay its bundle cost.
+ */
+export declare function loadSplat(url: string, providedBytes?: Uint8Array): Promise<SplatMesh>;
+/**
+ * Resolve a single named node inside an already-loaded glTF scene graph (F4,
+ * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
+ * callers pass the `scene` they already got from {@link loadGLTF}.
+ *
+ * The returned node is the SAME object (and shares the SAME geometry) as
+ * found in `scene` — nothing is cloned or copied out. `scene` is already a
+ * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
+ * so mutating/detaching the returned node is safe.
+ *
+ * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
+ * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
+ * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
+ * throws a loud `AssetParseError` instead of silently producing broken skinning.
+ */
+export declare function resolveGltfNode(scene: THREE.Object3D, nodeName: string, src: string): THREE.Object3D;
+/**
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
+ *
+ * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
+ * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
+ * also clears that env cache.
+ */
+export declare function clearAssetCaches(): void;
+/**
+ * Drop the cached entry for ONE asset URL after its bytes changed on disk
+ * (editor asset-optimization write-back — W4a). Existing clones keep their
+ * shared geometry alive (the cache entry only owns the lookup, not the
+ * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
+ * rewritten file instead of serving stale bytes.
+ */
+export declare function invalidateCachedAsset(url: string): void;
+/**
+ * Test-only: current sizes of the module-level 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 assetCacheSizes(): {
+    textures: number;
+    gltf: number;
+    splat: number;
+};
+//# sourceMappingURL=asset-loaders.d.ts.map

package/dist/asset-loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-loaders.d.ts","sourceRoot":"","sources":["../src/asset-loaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,CAMtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,CAAA;CAAE,CAAC,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAiD3F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,KAAK,CAAC,QAAQ,CAuChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEnF"}

package/dist/asset-loaders.js

@@ -0,0 +1,209 @@
+/**
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/engine/src/animation/xstate-animation-binding.ts.)
+ *
+ * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
+ * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
+ * (entity-factory, scene-sync). Previously this logic was duplicated across six
+ * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
+ * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
+ * not propagate. Everything funnels through the shared loaders in `../loader`
+ * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
+ * LoadingManager / asset-prefix rewrite).
+ *
+ * Cache lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
+ * 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 asset N times is bounded (one
+ * entry per distinct URL, not per load). They are released only on full runtime
+ * teardown via {@link clearAssetCaches}.
+ */
+import * as THREE from 'three';
+import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+import { AssetParseError } from './asset-parse-error';
+import { setUserData } from './ecs/user-data';
+import { gltfLoader, resolveUrl, textureLoader } from './loader';
+const textureCache = new Map();
+const gltfCache = new Map();
+const splatBytesCache = new Map();
+/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
+export function loadTexture(url) {
+    const cached = textureCache.get(url);
+    if (cached)
+        return cached;
+    const tex = textureLoader.load(url);
+    textureCache.set(url, tex);
+    return tex;
+}
+/**
+ * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
+ * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
+ *
+ * Clone-safety contract (P0.2 — load-bearing, tested):
+ * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
+ * We give each clone its OWN materials (so scene cleanup can dispose them
+ * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
+ * so cleanup (engine create-runtime fullCleanup + editor scene-sync
+ * disposeObject3D) skips disposing the shared geometry buffers.
+ */
+export function loadGLTF(url) {
+    let cached = gltfCache.get(url);
+    if (!cached) {
+        cached = new Promise((resolve, reject) => {
+            gltfLoader.load(url, (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }), undefined, (err) => reject(err));
+        });
+        gltfCache.set(url, cached);
+    }
+    return cached.then((entry) => {
+        const scene = SkeletonUtils.clone(entry.scene);
+        scene.traverse((child) => {
+            if (child instanceof THREE.Mesh) {
+                child.material = Array.isArray(child.material)
+                    ? child.material.map((m) => m.clone())
+                    : child.material.clone();
+                setUserData(child, '__sharedGeometry', true);
+            }
+        });
+        return { scene, animations: entry.animations };
+    });
+}
+/**
+ * Load one native Gaussian-splat asset as Spark's own Object3D.
+ *
+ * The URL cache stores immutable source bytes, not a live SplatMesh: every scene
+ * entity needs its own transformable/disposable Object3D, while repeated uses of
+ * the same SPZ must not download the multi-megabyte source more than once.
+ * Spark stays a lazy chunk so games without splats do not pay its bundle cost.
+ */
+export async function loadSplat(url, providedBytes) {
+    let bytes = splatBytesCache.get(url);
+    if (!bytes && providedBytes) {
+        bytes = Promise.resolve(providedBytes);
+        splatBytesCache.set(url, bytes);
+    }
+    if (!bytes) {
+        bytes = fetch(resolveUrl(url)).then(async (response) => {
+            if (!response.ok) {
+                throw new Error(`Failed to load Gaussian splat: ${url} (${response.status} ${response.statusText})`);
+            }
+            return new Uint8Array(await response.arrayBuffer());
+        });
+        splatBytesCache.set(url, bytes);
+    }
+    try {
+        const [{ SplatMesh }, fileBytes] = await Promise.all([import('@sparkjsdev/spark'), bytes]);
+        const mesh = new SplatMesh({ fileBytes, fileName: url, raycastable: true });
+        await mesh.initialized;
+        setUserData(mesh, 'gaussianSplat', { src: url, numSplats: mesh.numSplats });
+        const bounds = mesh.getBoundingBox();
+        if (!bounds.isEmpty()) {
+            // Three's generic Box3.setFromObject only understands geometry-bearing
+            // Object3Ds. Spark intentionally renders without THREE.BufferGeometry,
+            // so give editor/runtime framing a hidden, non-pickable bounds proxy.
+            // It is infrastructure, never authored hierarchy or rendered content.
+            // Include a framing margin. This proxy is consumed by generic editor
+            // focus/selection bounds, while inspectors continue to report Spark's
+            // exact Gaussian bounds directly.
+            const size = bounds.getSize(new THREE.Vector3()).multiplyScalar(1.5);
+            const center = bounds.getCenter(new THREE.Vector3());
+            const proxy = new THREE.Mesh(new THREE.BoxGeometry(size.x, size.y, size.z));
+            proxy.name = '__vgai_splat_bounds';
+            proxy.position.copy(center);
+            proxy.visible = false;
+            proxy.raycast = () => { };
+            setUserData(proxy, 'engineInternal', true);
+            mesh.add(proxy);
+        }
+        return mesh;
+    }
+    catch (error) {
+        // A failed fetch must be retryable after the source is repaired or the
+        // network recovers; successful source bytes remain cached across instances.
+        splatBytesCache.delete(url);
+        throw error;
+    }
+}
+/**
+ * Resolve a single named node inside an already-loaded glTF scene graph (F4,
+ * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
+ * callers pass the `scene` they already got from {@link loadGLTF}.
+ *
+ * The returned node is the SAME object (and shares the SAME geometry) as
+ * found in `scene` — nothing is cloned or copied out. `scene` is already a
+ * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
+ * so mutating/detaching the returned node is safe.
+ *
+ * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
+ * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
+ * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
+ * throws a loud `AssetParseError` instead of silently producing broken skinning.
+ */
+export function resolveGltfNode(scene, nodeName, src) {
+    const node = scene.getObjectByName(nodeName);
+    if (!node) {
+        throw new AssetParseError([
+            {
+                code: 'custom',
+                path: ['mesh', 'node'],
+                message: `glTF "${src}" has no node named "${nodeName}" (getObjectByName found nothing)`,
+            },
+        ], src);
+    }
+    const isSkinned = (o) => o.isSkinnedMesh;
+    let containsSkinned = isSkinned(node);
+    if (!containsSkinned) {
+        node.traverse((child) => {
+            if (isSkinned(child))
+                containsSkinned = true;
+        });
+    }
+    if (containsSkinned) {
+        throw new AssetParseError([
+            {
+                code: 'custom',
+                path: ['mesh', 'node'],
+                message: `glTF "${src}" node "${nodeName}" is (or contains) a SkinnedMesh — a skinned mesh ` +
+                    'cannot be lifted out of its armature (atomic-subtree rule). Reference the whole ' +
+                    'file instead of a `node`, or bake/export a non-skinned sub-asset.',
+            },
+        ], src);
+    }
+    return node;
+}
+/**
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
+ *
+ * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
+ * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
+ * also clears that env cache.
+ */
+export function clearAssetCaches() {
+    textureCache.clear();
+    gltfCache.clear();
+    splatBytesCache.clear();
+}
+/**
+ * Drop the cached entry for ONE asset URL after its bytes changed on disk
+ * (editor asset-optimization write-back — W4a). Existing clones keep their
+ * shared geometry alive (the cache entry only owns the lookup, not the
+ * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
+ * rewritten file instead of serving stale bytes.
+ */
+export function invalidateCachedAsset(url) {
+    textureCache.delete(url);
+    gltfCache.delete(url);
+}
+/**
+ * Test-only: current sizes of the module-level 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 function assetCacheSizes() {
+    return { textures: textureCache.size, gltf: gltfCache.size, splat: splatBytesCache.size };
+}