@vgai/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1,11 @@
+import type * as THREE from 'three';
+/** All objects in the graph carrying the given tag (depth-first, document order). */
+export declare function queryByTag(root: THREE.Object3D, tag: string): THREE.Object3D[];
+/** All objects in the graph with the given name (depth-first, document order). */
+export declare function queryByName(root: THREE.Object3D, name: string): THREE.Object3D[];
+/**
+ * All objects in the graph that have the named component attached
+ * (depth-first, document order).
+ */
+export declare function queryByComponent(root: THREE.Object3D, componentName: string): THREE.Object3D[];
+//# sourceMappingURL=scene-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-query.d.ts","sourceRoot":"","sources":["../../src/scene/scene-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAkCpC,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,CAM9E;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,CAMhF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,CAM9F"}

package/dist/scene/scene-query.js

@@ -0,0 +1,63 @@
+import { getUserData } from './user-data';
+/**
+ * Runtime queries over a loaded THREE scene graph (P1.6d).
+ *
+ * The scene's `tags` schema field is documented as "for runtime queries" but,
+ * until now, no query existed. These helpers walk a THREE.Object3D graph and
+ * read entity metadata off `userData`, so gameplay code can find objects by tag,
+ * name, or attached component without bookkeeping its own indexes.
+ *
+ * Canonical metadata locations (in priority order):
+ *   - tags:       `userData['tags']` (string[])     — falls back to `userData['entity'].tags`
+ *   - name:       `Object3D.name`
+ *   - components: `userData['components']` (record or string[]) — falls back to
+ *                 `userData['entity'].components` (record keyed by component name)
+ */
+function getTags(obj) {
+    const direct = getUserData(obj, 'tags');
+    if (Array.isArray(direct))
+        return direct;
+    const fromDef = getUserData(obj, 'entity')?.tags;
+    return Array.isArray(fromDef) ? fromDef : [];
+}
+function getComponentNames(obj) {
+    const direct = getUserData(obj, 'components');
+    if (Array.isArray(direct))
+        return direct;
+    if (direct && typeof direct === 'object')
+        return Object.keys(direct);
+    const fromDef = getUserData(obj, 'entity')?.components;
+    if (fromDef && typeof fromDef === 'object')
+        return Object.keys(fromDef);
+    return [];
+}
+/** All objects in the graph carrying the given tag (depth-first, document order). */
+export function queryByTag(root, tag) {
+    const matches = [];
+    root.traverse((obj) => {
+        if (getTags(obj).includes(tag))
+            matches.push(obj);
+    });
+    return matches;
+}
+/** All objects in the graph with the given name (depth-first, document order). */
+export function queryByName(root, name) {
+    const matches = [];
+    root.traverse((obj) => {
+        if (obj.name === name)
+            matches.push(obj);
+    });
+    return matches;
+}
+/**
+ * All objects in the graph that have the named component attached
+ * (depth-first, document order).
+ */
+export function queryByComponent(root, componentName) {
+    const matches = [];
+    root.traverse((obj) => {
+        if (getComponentNames(obj).includes(componentName))
+            matches.push(obj);
+    });
+    return matches;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Scene file types — derived from Zod schemas (single source of truth).
+ *
+ * Raw types for the .vscn.json file format. Both the editor and the runtime
+ * loader work with these directly, applying DEFAULTS (./defaults.ts) for omitted
+ * fields — DEFAULTS is the single source of truth for default values.
+ */
+export type { InstancesFile, MaterialFile, PrefabFile, SceneAnimation, SceneAudio, SceneCamera, SceneCollider, SceneEntity, SceneEnvironment, SceneFile, SceneJoint, SceneLight, SceneMaterial, SceneMesh, SceneNavigation, SceneParticles, ScenePhysics, ScenePhysicsSettings, ScenePostProcessing, SceneSpline, SceneToneMapping, UIRoot, } from './schema';
+export { mergePrefabInstance } from './schema';
+//# sourceMappingURL=scene-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-types.d.ts","sourceRoot":"","sources":["../../src/scene/scene-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,UAAU,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,MAAM,GACP,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}

package/dist/scene/scene-types.js

@@ -0,0 +1,8 @@
+/**
+ * Scene file types — derived from Zod schemas (single source of truth).
+ *
+ * Raw types for the .vscn.json file format. Both the editor and the runtime
+ * loader work with these directly, applying DEFAULTS (./defaults.ts) for omitted
+ * fields — DEFAULTS is the single source of truth for default values.
+ */
+export { mergePrefabInstance } from './schema';

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

@@ -0,0 +1,26 @@
+/**
+ * The scene/prefab file format `version` range this engine checkout can
+ * load (T2.3/D3 §1.E, docs/ENGINE-UPGRADE-DESIGN.md). `[min, max]` — today
+ * `[1, 1]`: every shipped `.vscn.json`/`.prefab.json` is version 1, and no
+ * migration machinery exists yet (a future format bump widens `max`, and a
+ * future engine that drops support for `1` would raise `min`).
+ *
+ * Deliberately NOT in `./schema/` (that directory's byte contents are
+ * pinned by `packages/engine/schemas/engine-capabilities.json`'s
+ * `schemaDirHash`, refreshed only by `scripts/capabilities-hash.ts` — this
+ * slice does not run that script). This is also why the check below is a
+ * POST-Zod-parse function here in `scene/`, not a Zod refinement inside
+ * `SceneFileSchema`/`PrefabFileSchema`: the generated `vscn.schema.json`/
+ * `prefab.schema.json` stay byte-identical (the `version` field itself is
+ * still just `z.number()`).
+ */
+export declare const SUPPORTED_SCENE_VERSION_RANGE: readonly [number, number];
+/**
+ * Throw if `version` falls outside `SUPPORTED_SCENE_VERSION_RANGE`; silently
+ * accept in-range versions. `fileKind` only changes the error message's noun
+ * (`.vscn.json` and `.prefab.json` share this single version axis — verified
+ * both schemas declare their own `version: z.number()` field, not a shared
+ * ref, but the same counter/semantics per docs/ENGINE-UPGRADE-DESIGN.md).
+ */
+export declare function checkSceneVersionInRange(version: number, fileKind?: 'scene' | 'prefab'): void;
+//# sourceMappingURL=scene-version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-version.d.ts","sourceRoot":"","sources":["../../src/scene/scene-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC;AAE/E;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,OAAO,GAAG,QAAkB,GACrC,IAAI,CAWN"}

package/dist/scene/scene-version.js

@@ -0,0 +1,34 @@
+/**
+ * The scene/prefab file format `version` range this engine checkout can
+ * load (T2.3/D3 §1.E, docs/ENGINE-UPGRADE-DESIGN.md). `[min, max]` — today
+ * `[1, 1]`: every shipped `.vscn.json`/`.prefab.json` is version 1, and no
+ * migration machinery exists yet (a future format bump widens `max`, and a
+ * future engine that drops support for `1` would raise `min`).
+ *
+ * Deliberately NOT in `./schema/` (that directory's byte contents are
+ * pinned by `packages/engine/schemas/engine-capabilities.json`'s
+ * `schemaDirHash`, refreshed only by `scripts/capabilities-hash.ts` — this
+ * slice does not run that script). This is also why the check below is a
+ * POST-Zod-parse function here in `scene/`, not a Zod refinement inside
+ * `SceneFileSchema`/`PrefabFileSchema`: the generated `vscn.schema.json`/
+ * `prefab.schema.json` stay byte-identical (the `version` field itself is
+ * still just `z.number()`).
+ */
+export const SUPPORTED_SCENE_VERSION_RANGE = [1, 1];
+/**
+ * Throw if `version` falls outside `SUPPORTED_SCENE_VERSION_RANGE`; silently
+ * accept in-range versions. `fileKind` only changes the error message's noun
+ * (`.vscn.json` and `.prefab.json` share this single version axis — verified
+ * both schemas declare their own `version: z.number()` field, not a shared
+ * ref, but the same counter/semantics per docs/ENGINE-UPGRADE-DESIGN.md).
+ */
+export function checkSceneVersionInRange(version, fileKind = 'scene') {
+    const [min, max] = SUPPORTED_SCENE_VERSION_RANGE;
+    if (version >= min && version <= max)
+        return;
+    const cause = version > max
+        ? `the engine checkout is older than this ${fileKind}`
+        : `this ${fileKind} predates the oldest supported format version`;
+    throw new Error(`${fileKind} version ${version} is outside the supported range [${min}, ${max}] — ` +
+        `${cause}; see docs/ENGINE-UPGRADE-DESIGN.md`);
+}

package/dist/scene/schema/animation.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare const SceneAnimationSchema: z.ZodObject<{
+    autoplay: z.ZodOptional<z.ZodString>;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    clipAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type SceneAnimation = z.infer<typeof SceneAnimationSchema>;
+//# sourceMappingURL=animation.d.ts.map

package/dist/scene/schema/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/animation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkCxB,eAAO,MAAM,oBAAoB;;;;iBASc,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/scene/schema/animation.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// D8 — declarative property tracks (formerly F5,
+// docs/VSCN-STRUCTURAL-GAPS-DESIGN.md) were REMOVED: Theatre
+// (`@theatre/core`) is the sole authored continuous-animation source (spec
+// §3.2, §10 D2-D4/D8). `PropertyTrackSchema`/`PropertyTrackRunner` and the
+// `tracks` field are deleted, not deprecated-in-place — see
+// packages/engine/src/scene/parse.ts (`assertNoRemovedPropertyTracks`) for
+// the loud migration-error guard that rejects any `.vscn`/`.prefab.json`
+// still authoring `animation.tracks`, since Zod would otherwise silently
+// strip an unrecognized field rather than failing loudly (Global AC §6).
+//
+// E5 — the AnimGraph state-machine runtime, `.animgraph.json` format, and
+// every consumer were removed (spec §3.3, §11 E5; XState + native Three
+// `AnimationMixer` replace it — see `xstate-animation-binding.ts`). The
+// `animGraph` field is deleted outright, not deprecated-in-place, for the
+// same reason as `tracks` above: Zod's default object mode would otherwise
+// silently STRIP an authored `animation.animGraph` rather than reporting it,
+// violating Global AC §6 ("Removed formats fail with a concise migration/
+// removal error rather than being partially read"). The raw-JSON guard
+// (`assertNoRemovedAnimGraph` in packages/engine/src/scene/parse.ts) rejects
+// any `.vscn`/`.prefab.json` still authoring it before Zod ever parses the
+// data — see packages/engine/test/anim-graph-removed.test.ts.
+//
+// `parameters` is deleted alongside `animGraph`, though it isn't itself named
+// in the spec/removal-inventory: its ONLY documented purpose was seeding an
+// `AnimGraph`'s initial parameter values (its only readers were
+// `scene-loader.ts`'s former animGraph branch, the editor's entity-factory.ts,
+// and AnimationSection.tsx's parameter-row UI — all deleted with the runtime).
+// Leaving it declared with zero remaining readers would violate this repo's
+// "no schema field without a runtime reader" policy (CLAUDE.md).
+// ---------------------------------------------------------------------------
+export const SceneAnimationSchema = z
+    .object({
+    autoplay: z.string().optional().describe('Clip name to play automatically on load'),
+    loop: z.boolean().optional().describe('Whether the autoplay clip should loop'),
+    clipAliases: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Map raw GLTF clip names to clean names'),
+})
+    .describe('Animation playback configuration');

package/dist/scene/schema/audio.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const SceneAudioSchema: z.ZodObject<{
+    src: z.ZodOptional<z.ZodString>;
+    spatial: z.ZodOptional<z.ZodBoolean>;
+    volume: z.ZodOptional<z.ZodNumber>;
+    refDistance: z.ZodOptional<z.ZodNumber>;
+    rolloffFactor: z.ZodOptional<z.ZodNumber>;
+    maxDistance: z.ZodOptional<z.ZodNumber>;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    autoplay: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SceneAudio = z.infer<typeof SceneAudioSchema>;
+//# sourceMappingURL=audio.d.ts.map

package/dist/scene/schema/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/audio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;iBAoBY,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/scene/schema/audio.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export const SceneAudioSchema = z
+    .object({
+    src: z.string().optional().describe('Path to audio file (WAV, MP3, OGG)'),
+    spatial: z.boolean().optional().describe('Enable 3D spatial audio (positional sound)'),
+    volume: z.number().optional().describe('Playback volume 0–1'),
+    refDistance: z
+        .number()
+        .optional()
+        .describe('Distance at which volume starts to attenuate (spatial only)'),
+    rolloffFactor: z
+        .number()
+        .optional()
+        .describe('How quickly volume attenuates with distance (spatial only)'),
+    maxDistance: z
+        .number()
+        .optional()
+        .describe('Maximum distance at which sound is audible (spatial only)'),
+    loop: z.boolean().optional().describe('Whether the audio should loop'),
+    autoplay: z.boolean().optional().describe('Start playing automatically when the scene loads'),
+})
+    .describe('Audio source configuration');

package/dist/scene/schema/camera.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const SceneCameraSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        perspective: "perspective";
+        orthographic: "orthographic";
+    }>;
+    fov: z.ZodOptional<z.ZodNumber>;
+    near: z.ZodOptional<z.ZodNumber>;
+    far: z.ZodOptional<z.ZodNumber>;
+    orthoSize: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Partial schema for prefab instance overrides (type not required). */
+export declare const SceneCameraOverrideSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        perspective: "perspective";
+        orthographic: "orthographic";
+    }>>;
+    fov: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    near: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    far: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    orthoSize: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    width: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    height: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SceneCamera = z.infer<typeof SceneCameraSchema>;
+//# sourceMappingURL=camera.d.ts.map

package/dist/scene/schema/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAaK,CAAC;AAEpC,wEAAwE;AACxE,eAAO,MAAM,yBAAyB;;;;;;;;;;;iBAA8B,CAAC;AAErE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/scene/schema/camera.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const SceneCameraSchema = z
+    .object({
+    type: z.enum(['perspective', 'orthographic']).describe('Camera projection type'),
+    fov: z.number().optional().describe('Vertical field of view in degrees (perspective only)'),
+    near: z.number().optional().describe('Near clipping plane distance'),
+    far: z.number().optional().describe('Far clipping plane distance'),
+    orthoSize: z
+        .number()
+        .optional()
+        .describe('Half-height of the orthographic frustum (orthographic only)'),
+    width: z.number().optional().describe('Render width in pixels. Defaults to viewport width'),
+    height: z.number().optional().describe('Render height in pixels. Defaults to viewport height'),
+})
+    .describe('Camera configuration');
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneCameraOverrideSchema = SceneCameraSchema.partial();

package/dist/scene/schema/collider.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const SceneColliderSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        cuboid: "cuboid";
+        ball: "ball";
+        capsule: "capsule";
+        trimesh: "trimesh";
+    }>;
+    halfExtents: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    radius: z.ZodOptional<z.ZodNumber>;
+    halfHeight: z.ZodOptional<z.ZodNumber>;
+    friction: z.ZodOptional<z.ZodNumber>;
+    restitution: z.ZodOptional<z.ZodNumber>;
+    density: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    isSensor: z.ZodOptional<z.ZodBoolean>;
+    collisionGroups: z.ZodOptional<z.ZodNumber>;
+    collisionFilter: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Partial schema for prefab instance overrides (type not required). */
+export declare const SceneColliderOverrideSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        cuboid: "cuboid";
+        ball: "ball";
+        capsule: "capsule";
+        trimesh: "trimesh";
+    }>>;
+    halfExtents: z.ZodOptional<z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+    radius: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    halfHeight: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    friction: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    restitution: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    density: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+    isSensor: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    collisionGroups: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    collisionFilter: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SceneCollider = z.infer<typeof SceneColliderSchema>;
+//# sourceMappingURL=collider.d.ts.map

package/dist/scene/schema/collider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collider.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/collider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;iBA4DoB,CAAC;AAErD,wEAAwE;AACxE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;iBAAgC,CAAC;AAEzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/scene/schema/collider.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+export const SceneColliderSchema = z
+    .object({
+    type: z
+        .enum(['cuboid', 'ball', 'capsule', 'trimesh'])
+        .describe("Collider shape type. T1.2: every shape scales with the entity's composed world scale " +
+        "(self × ancestors) — for trimesh this means the entity's own mesh geometry vertices " +
+        'are pre-scaled per-axis before building the Rapier trimesh, so it matches whatever ' +
+        "size ends up on screen; it does not require the collider's own dimension fields."),
+    halfExtents: Vec3Schema.optional().describe("Half-size [x, y, z] for cuboid colliders, in the ENTITY'S OWN LOCAL units. T1.2: " +
+        "scales with the entity — the actual Rapier collider is this value times the entity's " +
+        'composed world scale (self × every transformed ancestor), per axis, baked in once at ' +
+        "load time (Rapier has no live notion of an Object3D's scale)."),
+    radius: z
+        .number()
+        .optional()
+        .describe("Radius for ball and capsule colliders, in the ENTITY'S OWN LOCAL units. T1.2: scales " +
+        "with the entity's composed world scale, which MUST be uniform on the collider's round " +
+        'axes (ball: all of x/y/z; capsule: x and z) — a non-uniform scale there throws a loud ' +
+        'load error (Rapier balls/capsules cannot represent an ellipse).'),
+    halfHeight: z
+        .number()
+        .optional()
+        .describe("Half-height for capsule colliders, in the entity's own local units, along the capsule's " +
+        "axis (Y). T1.2: scales by the entity's composed world scale on that axis."),
+    friction: z.number().optional().describe('Surface friction coefficient'),
+    restitution: z
+        .number()
+        .optional()
+        .describe('Bounciness coefficient (0 = no bounce, 1 = perfect bounce)'),
+    density: z
+        .number()
+        .optional()
+        .describe('Mass density. Used to compute mass from collider volume'),
+    offset: Vec3Schema.optional().describe("Translation offset relative to body origin, in the ENTITY'S OWN LOCAL units. T1.2/R1c: " +
+        "scales with the entity's composed world scale (self × every transformed ancestor), " +
+        'per axis, the same way halfExtents/radius/halfHeight do — an unscaled offset would ' +
+        "silently drift away from the entity's visual anchor point under any non-1 scale."),
+    isSensor: z
+        .boolean()
+        .optional()
+        .describe('When true, detects overlaps without physical blocking (trigger volume)'),
+    collisionGroups: z
+        .number()
+        .optional()
+        .describe('Bitmask: collision layers this collider belongs to (max 16 bits)'),
+    collisionFilter: z
+        .number()
+        .optional()
+        .describe('Bitmask: collision layers this collider interacts with (max 16 bits)'),
+})
+    .describe('Physics collider shape and properties');
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneColliderOverrideSchema = SceneColliderSchema.partial();

package/dist/scene/schema/entity-ref.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/**
+ * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — a first-class, reusable
+ * reference from one entity to another, for a `GameComponent`'s own static
+ * Zod schema (e.g. `target: EntityRefSchema` — "this button opens THAT
+ * door"). A branded string: on disk (and through generic component-data
+ * validation) it is a plain string id, but a component field typed
+ * `EntityRef` is compile-time distinct from an arbitrary `string` field, so a
+ * bare label can't be assigned where a ref is expected.
+ *
+ * Resolution is a runtime concern, not a schema one: `scene-loader.ts`'s
+ * `resolveEntityRefs` (the post-spawn pass, modeled on `joint.target`'s
+ * existing resolution) rewrites the field from the authored string id to the
+ * live `THREE.Object3D` — through the SAME `idMap` `createSceneJoints`
+ * already uses, no new registry (G3) — before the referencing component's
+ * `init()` runs.
+ */
+export declare const EntityRefSchema: z.core.$ZodBranded<z.ZodString, "EntityRef", "out">;
+export type EntityRef = z.infer<typeof EntityRefSchema>;
+/**
+ * Is `schema` an {@link EntityRefSchema} field — including when wrapped by
+ * `.optional()`, `.default(...)`, or `.nullable()` (the common ways a
+ * component author would declare an optional ref)? Unwraps those via zod 4's
+ * internal `_def.innerType` (there is no public reflection API for this —
+ * `packages/editor/src/components/inspectors/zod-fields.ts` uses the same
+ * mechanism to introspect component schemas for the inspector) down to the
+ * core schema, then checks it against the registered `EntityRefSchema`
+ * instance by reference.
+ */
+export declare function isEntityRefSchema(schema: z.core.$ZodType): boolean;
+//# sourceMappingURL=entity-ref.d.ts.map

package/dist/scene/schema/entity-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-ref.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/entity-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,qDAOzB,CAAC;AAEJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AA8BxD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAUlE"}

package/dist/scene/schema/entity-ref.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — a first-class, reusable
+ * reference from one entity to another, for a `GameComponent`'s own static
+ * Zod schema (e.g. `target: EntityRefSchema` — "this button opens THAT
+ * door"). A branded string: on disk (and through generic component-data
+ * validation) it is a plain string id, but a component field typed
+ * `EntityRef` is compile-time distinct from an arbitrary `string` field, so a
+ * bare label can't be assigned where a ref is expected.
+ *
+ * Resolution is a runtime concern, not a schema one: `scene-loader.ts`'s
+ * `resolveEntityRefs` (the post-spawn pass, modeled on `joint.target`'s
+ * existing resolution) rewrites the field from the authored string id to the
+ * live `THREE.Object3D` — through the SAME `idMap` `createSceneJoints`
+ * already uses, no new registry (G3) — before the referencing component's
+ * `init()` runs.
+ */
+export const EntityRefSchema = z
+    .string()
+    .brand()
+    .describe('A reference to another entity by its authored id. On disk it is a plain string id; the ' +
+    'scene loader resolves it to the live THREE.Object3D (WorldNode-as-truth) before the ' +
+    "referencing component's init() runs. A ref to a missing id is a loud load error.");
+/**
+ * Identity registry of the `EntityRefSchema` object (there is exactly one —
+ * this module's export), used by {@link isEntityRefSchema}.
+ *
+ * Why identity rather than a Zod "type name" check: zod 4's `.brand()` is a
+ * type-only cast (see zod's own source — `inst.brand = () => inst`), not a
+ * distinct wrapper class runtime code could switch on. A branded schema is,
+ * at runtime, just the underlying `ZodString` (here, after `.describe()`
+ * clones it once more — see zod's `check()`/`clone()`). So "is this an
+ * EntityRef field" can only be answered by reference identity against the
+ * one schema object every ref field is declared with — which is exactly
+ * what we want anyway: a look-alike `z.string()` field must NOT count.
+ */
+const ENTITY_REF_SCHEMAS = new WeakSet();
+ENTITY_REF_SCHEMAS.add(EntityRefSchema);
+/**
+ * Is `schema` an {@link EntityRefSchema} field — including when wrapped by
+ * `.optional()`, `.default(...)`, or `.nullable()` (the common ways a
+ * component author would declare an optional ref)? Unwraps those via zod 4's
+ * internal `_def.innerType` (there is no public reflection API for this —
+ * `packages/editor/src/components/inspectors/zod-fields.ts` uses the same
+ * mechanism to introspect component schemas for the inspector) down to the
+ * core schema, then checks it against the registered `EntityRefSchema`
+ * instance by reference.
+ */
+export function isEntityRefSchema(schema) {
+    let cur = schema;
+    while (cur) {
+        if (ENTITY_REF_SCHEMAS.has(cur))
+            return true;
+        const inner = cur._def
+            ?.innerType;
+        if (!inner)
+            return false;
+        cur = inner;
+    }
+    return false;
+}