@relu-interactives/spatial-ecs 0.2.3 → 0.2.5

package/dist/{System-BTyYvKVH.d.cts → System-CIiWteft.d.cts}

@@ -86,7 +86,7 @@ type EntityId = number;
  * maps to an object factory in `core/factories/objects/*` that creates the
  * baseline component set.
  */
-type EcsEntityKind = "cube" | "sphere" | "plane" | "capsule" | "cylinder" | "empty" | "model" | "image" | "imageTarget" | "sprite" | "audio" | "camera" | "video" | "ambientLight" | "directionalLight" | "pointLight" | "spotLight" | "areaLight";
+type EcsEntityKind = "cube" | "sphere" | "plane" | "capsule" | "cylinder" | "empty" | "model" | "image" | "imageTarget" | "sprite" | "audio" | "camera" | "video" | "ambientLight" | "directionalLight" | "pointLight" | "spotLight" | "areaLight" | "instancedMesh";
 /** {@link EcsEntityKind} extended with editor-only utility entities (gizmos, helpers). */
 type EcsEntityEditorKind = EcsEntityKind | "editorUtility";
 /** Callback invoked when the selected entity changes. `null` indicates a deselection. */
@@ -235,7 +235,7 @@ type CreateContext = {
     isEditor?: boolean;
 };
 type EntityFactory = (context: CreateContext) => EntityId;
-type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video";
+type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video" | "instancedMesh";
 type ComponentFactory = (world: World, entityId: EntityId, ...args: any[]) => unknown;
 declare class ObjectManagementSystem implements EcsSystem {
     private readonly scene;

package/dist/{System-BTyYvKVH.d.ts → System-CIiWteft.d.ts}

@@ -86,7 +86,7 @@ type EntityId = number;
  * maps to an object factory in `core/factories/objects/*` that creates the
  * baseline component set.
  */
-type EcsEntityKind = "cube" | "sphere" | "plane" | "capsule" | "cylinder" | "empty" | "model" | "image" | "imageTarget" | "sprite" | "audio" | "camera" | "video" | "ambientLight" | "directionalLight" | "pointLight" | "spotLight" | "areaLight";
+type EcsEntityKind = "cube" | "sphere" | "plane" | "capsule" | "cylinder" | "empty" | "model" | "image" | "imageTarget" | "sprite" | "audio" | "camera" | "video" | "ambientLight" | "directionalLight" | "pointLight" | "spotLight" | "areaLight" | "instancedMesh";
 /** {@link EcsEntityKind} extended with editor-only utility entities (gizmos, helpers). */
 type EcsEntityEditorKind = EcsEntityKind | "editorUtility";
 /** Callback invoked when the selected entity changes. `null` indicates a deselection. */
@@ -235,7 +235,7 @@ type CreateContext = {
     isEditor?: boolean;
 };
 type EntityFactory = (context: CreateContext) => EntityId;
-type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video";
+type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video" | "instancedMesh";
 type ComponentFactory = (world: World, entityId: EntityId, ...args: any[]) => unknown;
 declare class ObjectManagementSystem implements EcsSystem {
     private readonly scene;

package/dist/{Video-D2H5H-K3.d.cts → Video-ChVFs9Tl.d.cts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { C as Component, e as EcsEntityKind, m as EcsEntityEditorKind, n as EntityId } from './System-BTyYvKVH.cjs';
+import { C as Component, e as EcsEntityKind, m as EcsEntityEditorKind, n as EntityId } from './System-CIiWteft.cjs';
 import * as RAPIER from '@dimforge/rapier3d-compat';
 
 interface StateMachine {
@@ -552,6 +552,143 @@ declare class Postprocessing extends Component {
     constructor(values?: Partial<PostprocessingState>);
 }
 
+/** Editable primitive kinds the mesh-geometry system can rebuild on the fly. `model` is a passthrough placeholder for entities that own a loaded GLTF/GLB instead. */
+type EditableMeshObjectKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
+/** Box geometry parameters in world units. */
+type CubeMeshParameters = {
+    /** Box width along X. */
+    width: number;
+    /** Box height along Y. */
+    height: number;
+    /** Box depth along Z. */
+    depth: number;
+};
+/** Plane geometry parameters in world units. */
+type PlaneMeshParameters = {
+    /** Plane width along X. */
+    width: number;
+    /** Plane height along Y. */
+    height: number;
+};
+/** Radius-only primitive parameters (sphere). */
+type RadiusMeshParameters = {
+    /** Sphere radius in world units. */
+    radius: number;
+};
+/** Radius + height primitive parameters (capsule, cylinder). */
+type RadiusHeightMeshParameters = {
+    /** Radius of the cap/cylinder cross-section. */
+    radius: number;
+    /** Length of the straight section between caps (capsule) or full height (cylinder). */
+    height: number;
+};
+/** Empty parameter set for `model` entities. */
+type ModelMeshParameters = Record<string, never>;
+/** Map from {@link EditableMeshObjectKind} to its parameter shape. */
+type MeshGeometryParametersByKind = {
+    capsule: RadiusHeightMeshParameters;
+    cube: CubeMeshParameters;
+    cylinder: RadiusHeightMeshParameters;
+    model: ModelMeshParameters;
+    plane: PlaneMeshParameters;
+    sphere: RadiusMeshParameters;
+};
+type MeshGeometryParameters = MeshGeometryParametersByKind[EditableMeshObjectKind];
+declare const DEFAULT_MESH_GEOMETRY_PARAMETERS: MeshGeometryParametersByKind;
+/**
+ * Editable geometry parameters for primitive meshes (cube, sphere, plane,
+ * capsule, cylinder) and the placeholder for `model` entities. Holds the
+ * authoring values plus shadow casting/receiving flags. The mesh-geometry
+ * system rebuilds the underlying `BufferGeometry` when parameters change.
+ *
+ * @category Components
+ */
+declare class MeshGeometryComponent extends Component {
+    /** Primitive kind (`cube`, `sphere`, `plane`, `capsule`, `cylinder`) or `model` for loaded assets. */
+    readonly kind: EditableMeshObjectKind;
+    /** Three.js geometry class name (e.g. `"BoxGeometry"`, `"SphereGeometry"`). Derived from {@link kind}. */
+    readonly geometryType: string;
+    /** Editable parameters whose shape depends on {@link kind}. The mesh-geometry system rebuilds geometry when these change. */
+    parameters: MeshGeometryParameters;
+    /** Live three.js object whose geometry is being managed. `null` until the object is built. */
+    object: THREE.Object3D | null;
+    /** Human-readable model name shown in the inspector for `model` entities; empty for primitives. */
+    modelName: string;
+    /** Whether the mesh casts shadows in the renderer. */
+    castShadow: boolean;
+    /** Whether the mesh receives shadows in the renderer. */
+    receiveShadow: boolean;
+    constructor(kind: EditableMeshObjectKind, object: THREE.Object3D | null, parameters?: Partial<MeshGeometryParameters>, options?: {
+        modelName?: string;
+        castShadow?: boolean;
+        receiveShadow?: boolean;
+    });
+}
+
+/**
+ * Per-instance transform stored inside {@link InstancedMeshComponent}.
+ * All rotations are in radians.
+ */
+type InstanceTransform = {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Euler rotation in radians (XYZ order). */
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/** Primitive geometry kinds supported by instanced mesh rendering. */
+type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "plane" | "sphere";
+/** Default identity instance transform. */
+declare const DEFAULT_INSTANCE_TRANSFORM: InstanceTransform;
+/** Default geometry parameters per instanced mesh kind. */
+declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshGeometryParameters>;
+/**
+ * Holds authored instanced-mesh data for an entity that renders as a
+ * `THREE.InstancedMesh`. Supports primitive geometry kinds (cube, sphere,
+ * plane, capsule, cylinder).
+ *
+ * The `instancedMesh` field is a live runtime reference that is **not**
+ * serialized into snapshots — it is excluded by the snapshot normalizer in
+ * `worldSnapshotUtils.ts` to prevent history churn.
+ *
+ * @category Components
+ */
+declare class InstancedMeshComponent extends Component {
+    /** Primitive geometry kind shared by all instances. */
+    meshKind: InstancedMeshKind;
+    /** Editable geometry parameters (width/height/depth, radius, etc.). */
+    meshParameters: MeshGeometryParameters;
+    /** Whether all instances cast shadows. */
+    castShadow: boolean;
+    /** Whether all instances receive shadows. */
+    receiveShadow: boolean;
+    /** Per-instance transforms stored in local space relative to the anchor object. */
+    instances: InstanceTransform[];
+    /**
+     * Live `THREE.InstancedMesh` managed by {@link InstancedMeshSystem}.
+     * Excluded from snapshot serialization — do **not** read this in hydration code.
+     */
+    instancedMesh: THREE.InstancedMesh | null;
+    constructor(meshKind?: InstancedMeshKind, meshParameters?: Partial<MeshGeometryParameters>, options?: {
+        castShadow?: boolean;
+        receiveShadow?: boolean;
+        instances?: InstanceTransform[];
+    });
+    /** Sanitize and return a copy of the current mesh parameters with valid values. */
+    getSanitizedParameters(): MeshGeometryParameters;
+}
+
 type RapierRigidBody = RAPIER.RigidBody;
 type RapierCollider = RAPIER.Collider;
 /**
@@ -937,79 +1074,6 @@ declare class MeshComponent extends Component {
     constructor(mesh: THREE.Object3D);
 }
 
-/** Editable primitive kinds the mesh-geometry system can rebuild on the fly. `model` is a passthrough placeholder for entities that own a loaded GLTF/GLB instead. */
-type EditableMeshObjectKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
-/** Box geometry parameters in world units. */
-type CubeMeshParameters = {
-    /** Box width along X. */
-    width: number;
-    /** Box height along Y. */
-    height: number;
-    /** Box depth along Z. */
-    depth: number;
-};
-/** Plane geometry parameters in world units. */
-type PlaneMeshParameters = {
-    /** Plane width along X. */
-    width: number;
-    /** Plane height along Y. */
-    height: number;
-};
-/** Radius-only primitive parameters (sphere). */
-type RadiusMeshParameters = {
-    /** Sphere radius in world units. */
-    radius: number;
-};
-/** Radius + height primitive parameters (capsule, cylinder). */
-type RadiusHeightMeshParameters = {
-    /** Radius of the cap/cylinder cross-section. */
-    radius: number;
-    /** Length of the straight section between caps (capsule) or full height (cylinder). */
-    height: number;
-};
-/** Empty parameter set for `model` entities. */
-type ModelMeshParameters = Record<string, never>;
-/** Map from {@link EditableMeshObjectKind} to its parameter shape. */
-type MeshGeometryParametersByKind = {
-    capsule: RadiusHeightMeshParameters;
-    cube: CubeMeshParameters;
-    cylinder: RadiusHeightMeshParameters;
-    model: ModelMeshParameters;
-    plane: PlaneMeshParameters;
-    sphere: RadiusMeshParameters;
-};
-type MeshGeometryParameters = MeshGeometryParametersByKind[EditableMeshObjectKind];
-declare const DEFAULT_MESH_GEOMETRY_PARAMETERS: MeshGeometryParametersByKind;
-/**
- * Editable geometry parameters for primitive meshes (cube, sphere, plane,
- * capsule, cylinder) and the placeholder for `model` entities. Holds the
- * authoring values plus shadow casting/receiving flags. The mesh-geometry
- * system rebuilds the underlying `BufferGeometry` when parameters change.
- *
- * @category Components
- */
-declare class MeshGeometryComponent extends Component {
-    /** Primitive kind (`cube`, `sphere`, `plane`, `capsule`, `cylinder`) or `model` for loaded assets. */
-    readonly kind: EditableMeshObjectKind;
-    /** Three.js geometry class name (e.g. `"BoxGeometry"`, `"SphereGeometry"`). Derived from {@link kind}. */
-    readonly geometryType: string;
-    /** Editable parameters whose shape depends on {@link kind}. The mesh-geometry system rebuilds geometry when these change. */
-    parameters: MeshGeometryParameters;
-    /** Live three.js object whose geometry is being managed. `null` until the object is built. */
-    object: THREE.Object3D | null;
-    /** Human-readable model name shown in the inspector for `model` entities; empty for primitives. */
-    modelName: string;
-    /** Whether the mesh casts shadows in the renderer. */
-    castShadow: boolean;
-    /** Whether the mesh receives shadows in the renderer. */
-    receiveShadow: boolean;
-    constructor(kind: EditableMeshObjectKind, object: THREE.Object3D | null, parameters?: Partial<MeshGeometryParameters>, options?: {
-        modelName?: string;
-        castShadow?: boolean;
-        receiveShadow?: boolean;
-    });
-}
-
 /**
  * References a GLTF/GLB asset loaded from `path`. The model loading system
  * resolves the asset asynchronously and populates {@link ModelComponent.object}
@@ -1258,4 +1322,4 @@ declare class VideoComponent extends Component {
     stop(): void;
 }
 
-export { Selectable as $, AnimationComponent as A, type MaterialTypeValue as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, type MaterialValueState as F, MeshComponent as G, MeshGeometryComponent as H, ImageComponent as I, type MeshGeometryParameters as J, type MeshGeometryParametersByKind as K, LightComponent as L, MaterialComponent as M, ModelComponent as N, Name as O, Object3DRef as P, PhysicsComponent as Q, type PhysicsState as R, type PlaneMeshParameters as S, Postprocessing as T, type PostprocessingState as U, type RadiusHeightMeshParameters as V, type RadiusMeshParameters as W, type RigidbodyState as X, type RigidbodyType as Y, ScriptComponent as Z, type ScriptEntry as _, type AnimationComponentOptions as a, SelectionTransformState as a0, SpriteComponent as a1, type TextureFilteringValue as a2, type TransformModeValue as a3, type TransformSpaceValue as a4, VideoComponent as a5, normalizePhysicsState as a6, type AnimationStateCallbacks as a7, AnimationStateMachine as a8, AnimationStateManager as a9, type StateMachine as aa, AudioComponent as b, type CameraComponentOptions as c, type CameraProjection as d, type CameraRuntimeType as e, type ColliderShape as f, type ColliderState as g, type CubeMeshParameters as h, DEFAULT_ENVIRONMENT_STATE as i, DEFAULT_MESH_GEOMETRY_PARAMETERS as j, DEFAULT_PHYSICS_STATE as k, DEFAULT_POSTPROCESSING_STATE as l, DEFAULT_RIGIDBODY_STATE as m, EntityType as n, Environment as o, type EnvironmentFogState as p, type EnvironmentFogType as q, type EnvironmentGradientEffect as r, type EnvironmentSkyboxState as s, type EnvironmentSkyboxType as t, type EnvironmentState as u, ImageTarget as v, ImageTargetAnchor as w, type ImageTargetAnchorOptions as x, type ImageTargetReference as y, type LightValueState as z };
+export { type RadiusMeshParameters as $, AnimationComponent as A, type ImageTargetReference as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, type InstanceTransform as F, InstancedMeshComponent as G, type InstancedMeshKind as H, ImageComponent as I, type LightValueState as J, type MaterialTypeValue as K, LightComponent as L, MaterialComponent as M, type MaterialValueState as N, MeshComponent as O, MeshGeometryComponent as P, type MeshGeometryParameters as Q, type MeshGeometryParametersByKind as R, ModelComponent as S, Name as T, Object3DRef as U, PhysicsComponent as V, type PhysicsState as W, type PlaneMeshParameters as X, Postprocessing as Y, type PostprocessingState as Z, type RadiusHeightMeshParameters as _, type AnimationComponentOptions as a, type RigidbodyState as a0, type RigidbodyType as a1, ScriptComponent as a2, type ScriptEntry as a3, Selectable as a4, SelectionTransformState as a5, SpriteComponent as a6, type TextureFilteringValue as a7, type TransformModeValue as a8, type TransformSpaceValue as a9, VideoComponent as aa, normalizePhysicsState as ab, type AnimationStateCallbacks as ac, AnimationStateMachine as ad, AnimationStateManager as ae, type StateMachine as af, AudioComponent as b, type CameraComponentOptions as c, type CameraProjection as d, type CameraRuntimeType as e, type ColliderShape as f, type ColliderState as g, type CubeMeshParameters as h, DEFAULT_ENVIRONMENT_STATE as i, DEFAULT_INSTANCED_MESH_PARAMETERS as j, DEFAULT_INSTANCE_TRANSFORM as k, DEFAULT_MESH_GEOMETRY_PARAMETERS as l, DEFAULT_PHYSICS_STATE as m, DEFAULT_POSTPROCESSING_STATE as n, DEFAULT_RIGIDBODY_STATE as o, EntityType as p, Environment as q, type EnvironmentFogState as r, type EnvironmentFogType as s, type EnvironmentGradientEffect as t, type EnvironmentSkyboxState as u, type EnvironmentSkyboxType as v, type EnvironmentState as w, ImageTarget as x, ImageTargetAnchor as y, type ImageTargetAnchorOptions as z };

package/dist/{Video-BWhbvVPg.d.ts → Video-DCMCLInA.d.ts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { C as Component, e as EcsEntityKind, m as EcsEntityEditorKind, n as EntityId } from './System-BTyYvKVH.js';
+import { C as Component, e as EcsEntityKind, m as EcsEntityEditorKind, n as EntityId } from './System-CIiWteft.js';
 import * as RAPIER from '@dimforge/rapier3d-compat';
 
 interface StateMachine {
@@ -552,6 +552,143 @@ declare class Postprocessing extends Component {
     constructor(values?: Partial<PostprocessingState>);
 }
 
+/** Editable primitive kinds the mesh-geometry system can rebuild on the fly. `model` is a passthrough placeholder for entities that own a loaded GLTF/GLB instead. */
+type EditableMeshObjectKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
+/** Box geometry parameters in world units. */
+type CubeMeshParameters = {
+    /** Box width along X. */
+    width: number;
+    /** Box height along Y. */
+    height: number;
+    /** Box depth along Z. */
+    depth: number;
+};
+/** Plane geometry parameters in world units. */
+type PlaneMeshParameters = {
+    /** Plane width along X. */
+    width: number;
+    /** Plane height along Y. */
+    height: number;
+};
+/** Radius-only primitive parameters (sphere). */
+type RadiusMeshParameters = {
+    /** Sphere radius in world units. */
+    radius: number;
+};
+/** Radius + height primitive parameters (capsule, cylinder). */
+type RadiusHeightMeshParameters = {
+    /** Radius of the cap/cylinder cross-section. */
+    radius: number;
+    /** Length of the straight section between caps (capsule) or full height (cylinder). */
+    height: number;
+};
+/** Empty parameter set for `model` entities. */
+type ModelMeshParameters = Record<string, never>;
+/** Map from {@link EditableMeshObjectKind} to its parameter shape. */
+type MeshGeometryParametersByKind = {
+    capsule: RadiusHeightMeshParameters;
+    cube: CubeMeshParameters;
+    cylinder: RadiusHeightMeshParameters;
+    model: ModelMeshParameters;
+    plane: PlaneMeshParameters;
+    sphere: RadiusMeshParameters;
+};
+type MeshGeometryParameters = MeshGeometryParametersByKind[EditableMeshObjectKind];
+declare const DEFAULT_MESH_GEOMETRY_PARAMETERS: MeshGeometryParametersByKind;
+/**
+ * Editable geometry parameters for primitive meshes (cube, sphere, plane,
+ * capsule, cylinder) and the placeholder for `model` entities. Holds the
+ * authoring values plus shadow casting/receiving flags. The mesh-geometry
+ * system rebuilds the underlying `BufferGeometry` when parameters change.
+ *
+ * @category Components
+ */
+declare class MeshGeometryComponent extends Component {
+    /** Primitive kind (`cube`, `sphere`, `plane`, `capsule`, `cylinder`) or `model` for loaded assets. */
+    readonly kind: EditableMeshObjectKind;
+    /** Three.js geometry class name (e.g. `"BoxGeometry"`, `"SphereGeometry"`). Derived from {@link kind}. */
+    readonly geometryType: string;
+    /** Editable parameters whose shape depends on {@link kind}. The mesh-geometry system rebuilds geometry when these change. */
+    parameters: MeshGeometryParameters;
+    /** Live three.js object whose geometry is being managed. `null` until the object is built. */
+    object: THREE.Object3D | null;
+    /** Human-readable model name shown in the inspector for `model` entities; empty for primitives. */
+    modelName: string;
+    /** Whether the mesh casts shadows in the renderer. */
+    castShadow: boolean;
+    /** Whether the mesh receives shadows in the renderer. */
+    receiveShadow: boolean;
+    constructor(kind: EditableMeshObjectKind, object: THREE.Object3D | null, parameters?: Partial<MeshGeometryParameters>, options?: {
+        modelName?: string;
+        castShadow?: boolean;
+        receiveShadow?: boolean;
+    });
+}
+
+/**
+ * Per-instance transform stored inside {@link InstancedMeshComponent}.
+ * All rotations are in radians.
+ */
+type InstanceTransform = {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Euler rotation in radians (XYZ order). */
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/** Primitive geometry kinds supported by instanced mesh rendering. */
+type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "plane" | "sphere";
+/** Default identity instance transform. */
+declare const DEFAULT_INSTANCE_TRANSFORM: InstanceTransform;
+/** Default geometry parameters per instanced mesh kind. */
+declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshGeometryParameters>;
+/**
+ * Holds authored instanced-mesh data for an entity that renders as a
+ * `THREE.InstancedMesh`. Supports primitive geometry kinds (cube, sphere,
+ * plane, capsule, cylinder).
+ *
+ * The `instancedMesh` field is a live runtime reference that is **not**
+ * serialized into snapshots — it is excluded by the snapshot normalizer in
+ * `worldSnapshotUtils.ts` to prevent history churn.
+ *
+ * @category Components
+ */
+declare class InstancedMeshComponent extends Component {
+    /** Primitive geometry kind shared by all instances. */
+    meshKind: InstancedMeshKind;
+    /** Editable geometry parameters (width/height/depth, radius, etc.). */
+    meshParameters: MeshGeometryParameters;
+    /** Whether all instances cast shadows. */
+    castShadow: boolean;
+    /** Whether all instances receive shadows. */
+    receiveShadow: boolean;
+    /** Per-instance transforms stored in local space relative to the anchor object. */
+    instances: InstanceTransform[];
+    /**
+     * Live `THREE.InstancedMesh` managed by {@link InstancedMeshSystem}.
+     * Excluded from snapshot serialization — do **not** read this in hydration code.
+     */
+    instancedMesh: THREE.InstancedMesh | null;
+    constructor(meshKind?: InstancedMeshKind, meshParameters?: Partial<MeshGeometryParameters>, options?: {
+        castShadow?: boolean;
+        receiveShadow?: boolean;
+        instances?: InstanceTransform[];
+    });
+    /** Sanitize and return a copy of the current mesh parameters with valid values. */
+    getSanitizedParameters(): MeshGeometryParameters;
+}
+
 type RapierRigidBody = RAPIER.RigidBody;
 type RapierCollider = RAPIER.Collider;
 /**
@@ -937,79 +1074,6 @@ declare class MeshComponent extends Component {
     constructor(mesh: THREE.Object3D);
 }
 
-/** Editable primitive kinds the mesh-geometry system can rebuild on the fly. `model` is a passthrough placeholder for entities that own a loaded GLTF/GLB instead. */
-type EditableMeshObjectKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
-/** Box geometry parameters in world units. */
-type CubeMeshParameters = {
-    /** Box width along X. */
-    width: number;
-    /** Box height along Y. */
-    height: number;
-    /** Box depth along Z. */
-    depth: number;
-};
-/** Plane geometry parameters in world units. */
-type PlaneMeshParameters = {
-    /** Plane width along X. */
-    width: number;
-    /** Plane height along Y. */
-    height: number;
-};
-/** Radius-only primitive parameters (sphere). */
-type RadiusMeshParameters = {
-    /** Sphere radius in world units. */
-    radius: number;
-};
-/** Radius + height primitive parameters (capsule, cylinder). */
-type RadiusHeightMeshParameters = {
-    /** Radius of the cap/cylinder cross-section. */
-    radius: number;
-    /** Length of the straight section between caps (capsule) or full height (cylinder). */
-    height: number;
-};
-/** Empty parameter set for `model` entities. */
-type ModelMeshParameters = Record<string, never>;
-/** Map from {@link EditableMeshObjectKind} to its parameter shape. */
-type MeshGeometryParametersByKind = {
-    capsule: RadiusHeightMeshParameters;
-    cube: CubeMeshParameters;
-    cylinder: RadiusHeightMeshParameters;
-    model: ModelMeshParameters;
-    plane: PlaneMeshParameters;
-    sphere: RadiusMeshParameters;
-};
-type MeshGeometryParameters = MeshGeometryParametersByKind[EditableMeshObjectKind];
-declare const DEFAULT_MESH_GEOMETRY_PARAMETERS: MeshGeometryParametersByKind;
-/**
- * Editable geometry parameters for primitive meshes (cube, sphere, plane,
- * capsule, cylinder) and the placeholder for `model` entities. Holds the
- * authoring values plus shadow casting/receiving flags. The mesh-geometry
- * system rebuilds the underlying `BufferGeometry` when parameters change.
- *
- * @category Components
- */
-declare class MeshGeometryComponent extends Component {
-    /** Primitive kind (`cube`, `sphere`, `plane`, `capsule`, `cylinder`) or `model` for loaded assets. */
-    readonly kind: EditableMeshObjectKind;
-    /** Three.js geometry class name (e.g. `"BoxGeometry"`, `"SphereGeometry"`). Derived from {@link kind}. */
-    readonly geometryType: string;
-    /** Editable parameters whose shape depends on {@link kind}. The mesh-geometry system rebuilds geometry when these change. */
-    parameters: MeshGeometryParameters;
-    /** Live three.js object whose geometry is being managed. `null` until the object is built. */
-    object: THREE.Object3D | null;
-    /** Human-readable model name shown in the inspector for `model` entities; empty for primitives. */
-    modelName: string;
-    /** Whether the mesh casts shadows in the renderer. */
-    castShadow: boolean;
-    /** Whether the mesh receives shadows in the renderer. */
-    receiveShadow: boolean;
-    constructor(kind: EditableMeshObjectKind, object: THREE.Object3D | null, parameters?: Partial<MeshGeometryParameters>, options?: {
-        modelName?: string;
-        castShadow?: boolean;
-        receiveShadow?: boolean;
-    });
-}
-
 /**
  * References a GLTF/GLB asset loaded from `path`. The model loading system
  * resolves the asset asynchronously and populates {@link ModelComponent.object}
@@ -1258,4 +1322,4 @@ declare class VideoComponent extends Component {
     stop(): void;
 }
 
-export { Selectable as $, AnimationComponent as A, type MaterialTypeValue as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, type MaterialValueState as F, MeshComponent as G, MeshGeometryComponent as H, ImageComponent as I, type MeshGeometryParameters as J, type MeshGeometryParametersByKind as K, LightComponent as L, MaterialComponent as M, ModelComponent as N, Name as O, Object3DRef as P, PhysicsComponent as Q, type PhysicsState as R, type PlaneMeshParameters as S, Postprocessing as T, type PostprocessingState as U, type RadiusHeightMeshParameters as V, type RadiusMeshParameters as W, type RigidbodyState as X, type RigidbodyType as Y, ScriptComponent as Z, type ScriptEntry as _, type AnimationComponentOptions as a, SelectionTransformState as a0, SpriteComponent as a1, type TextureFilteringValue as a2, type TransformModeValue as a3, type TransformSpaceValue as a4, VideoComponent as a5, normalizePhysicsState as a6, type AnimationStateCallbacks as a7, AnimationStateMachine as a8, AnimationStateManager as a9, type StateMachine as aa, AudioComponent as b, type CameraComponentOptions as c, type CameraProjection as d, type CameraRuntimeType as e, type ColliderShape as f, type ColliderState as g, type CubeMeshParameters as h, DEFAULT_ENVIRONMENT_STATE as i, DEFAULT_MESH_GEOMETRY_PARAMETERS as j, DEFAULT_PHYSICS_STATE as k, DEFAULT_POSTPROCESSING_STATE as l, DEFAULT_RIGIDBODY_STATE as m, EntityType as n, Environment as o, type EnvironmentFogState as p, type EnvironmentFogType as q, type EnvironmentGradientEffect as r, type EnvironmentSkyboxState as s, type EnvironmentSkyboxType as t, type EnvironmentState as u, ImageTarget as v, ImageTargetAnchor as w, type ImageTargetAnchorOptions as x, type ImageTargetReference as y, type LightValueState as z };
+export { type RadiusMeshParameters as $, AnimationComponent as A, type ImageTargetReference as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, type InstanceTransform as F, InstancedMeshComponent as G, type InstancedMeshKind as H, ImageComponent as I, type LightValueState as J, type MaterialTypeValue as K, LightComponent as L, MaterialComponent as M, type MaterialValueState as N, MeshComponent as O, MeshGeometryComponent as P, type MeshGeometryParameters as Q, type MeshGeometryParametersByKind as R, ModelComponent as S, Name as T, Object3DRef as U, PhysicsComponent as V, type PhysicsState as W, type PlaneMeshParameters as X, Postprocessing as Y, type PostprocessingState as Z, type RadiusHeightMeshParameters as _, type AnimationComponentOptions as a, type RigidbodyState as a0, type RigidbodyType as a1, ScriptComponent as a2, type ScriptEntry as a3, Selectable as a4, SelectionTransformState as a5, SpriteComponent as a6, type TextureFilteringValue as a7, type TransformModeValue as a8, type TransformSpaceValue as a9, VideoComponent as aa, normalizePhysicsState as ab, type AnimationStateCallbacks as ac, AnimationStateMachine as ad, AnimationStateManager as ae, type StateMachine as af, AudioComponent as b, type CameraComponentOptions as c, type CameraProjection as d, type CameraRuntimeType as e, type ColliderShape as f, type ColliderState as g, type CubeMeshParameters as h, DEFAULT_ENVIRONMENT_STATE as i, DEFAULT_INSTANCED_MESH_PARAMETERS as j, DEFAULT_INSTANCE_TRANSFORM as k, DEFAULT_MESH_GEOMETRY_PARAMETERS as l, DEFAULT_PHYSICS_STATE as m, DEFAULT_POSTPROCESSING_STATE as n, DEFAULT_RIGIDBODY_STATE as o, EntityType as p, Environment as q, type EnvironmentFogState as r, type EnvironmentFogType as s, type EnvironmentGradientEffect as t, type EnvironmentSkyboxState as u, type EnvironmentSkyboxType as v, type EnvironmentState as w, ImageTarget as x, ImageTargetAnchor as y, type ImageTargetAnchorOptions as z };