@relu-interactives/spatial-ecs 0.2.5 → 0.2.7

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

@@ -647,11 +647,11 @@ type InstanceTransform = {
         z: number;
     };
 };
-/** Primitive geometry kinds supported by instanced mesh rendering. */
-type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "plane" | "sphere";
+/** Primitive geometry kinds and custom 3D model kind supported by instanced mesh rendering. */
+type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
 /** Default identity instance transform. */
 declare const DEFAULT_INSTANCE_TRANSFORM: InstanceTransform;
-/** Default geometry parameters per instanced mesh kind. */
+/** Default geometry parameters per instanced mesh kind. For "model" kind, cube params are stored as a placeholder (unused). */
 declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshGeometryParameters>;
 /**
  * Holds authored instanced-mesh data for an entity that renders as a
@@ -665,9 +665,14 @@ declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshG
  * @category Components
  */
 declare class InstancedMeshComponent extends Component {
-    /** Primitive geometry kind shared by all instances. */
+    /** Geometry kind for all instances. Use `"model"` for a custom GLTF/GLB asset. */
     meshKind: InstancedMeshKind;
-    /** Editable geometry parameters (width/height/depth, radius, etc.). */
+    /**
+     * Path to the GLTF/GLB asset when `meshKind === "model"`.
+     * Serialized in snapshots and restored on hydration.
+     */
+    modelPath: string;
+    /** Editable geometry parameters (width/height/depth, radius, etc.). Ignored when `meshKind === "model"`. */
     meshParameters: MeshGeometryParameters;
     /** Whether all instances cast shadows. */
     castShadow: boolean;
@@ -676,14 +681,17 @@ declare class InstancedMeshComponent extends Component {
     /** Per-instance transforms stored in local space relative to the anchor object. */
     instances: InstanceTransform[];
     /**
-     * Live `THREE.InstancedMesh` managed by {@link InstancedMeshSystem}.
+     * Live runtime container managed by {@link InstancedMeshSystem}:
+     * - For primitive kinds: a `THREE.InstancedMesh`.
+     * - For `"model"` kind: a `THREE.Group` containing per-mesh `THREE.InstancedMesh` objects.
      * Excluded from snapshot serialization — do **not** read this in hydration code.
      */
-    instancedMesh: THREE.InstancedMesh | null;
+    instancedMesh: THREE.Object3D | null;
     constructor(meshKind?: InstancedMeshKind, meshParameters?: Partial<MeshGeometryParameters>, options?: {
         castShadow?: boolean;
         receiveShadow?: boolean;
         instances?: InstanceTransform[];
+        modelPath?: string;
     });
     /** Sanitize and return a copy of the current mesh parameters with valid values. */
     getSanitizedParameters(): MeshGeometryParameters;

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

@@ -647,11 +647,11 @@ type InstanceTransform = {
         z: number;
     };
 };
-/** Primitive geometry kinds supported by instanced mesh rendering. */
-type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "plane" | "sphere";
+/** Primitive geometry kinds and custom 3D model kind supported by instanced mesh rendering. */
+type InstancedMeshKind = "capsule" | "cube" | "cylinder" | "model" | "plane" | "sphere";
 /** Default identity instance transform. */
 declare const DEFAULT_INSTANCE_TRANSFORM: InstanceTransform;
-/** Default geometry parameters per instanced mesh kind. */
+/** Default geometry parameters per instanced mesh kind. For "model" kind, cube params are stored as a placeholder (unused). */
 declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshGeometryParameters>;
 /**
  * Holds authored instanced-mesh data for an entity that renders as a
@@ -665,9 +665,14 @@ declare const DEFAULT_INSTANCED_MESH_PARAMETERS: Record<InstancedMeshKind, MeshG
  * @category Components
  */
 declare class InstancedMeshComponent extends Component {
-    /** Primitive geometry kind shared by all instances. */
+    /** Geometry kind for all instances. Use `"model"` for a custom GLTF/GLB asset. */
     meshKind: InstancedMeshKind;
-    /** Editable geometry parameters (width/height/depth, radius, etc.). */
+    /**
+     * Path to the GLTF/GLB asset when `meshKind === "model"`.
+     * Serialized in snapshots and restored on hydration.
+     */
+    modelPath: string;
+    /** Editable geometry parameters (width/height/depth, radius, etc.). Ignored when `meshKind === "model"`. */
     meshParameters: MeshGeometryParameters;
     /** Whether all instances cast shadows. */
     castShadow: boolean;
@@ -676,14 +681,17 @@ declare class InstancedMeshComponent extends Component {
     /** Per-instance transforms stored in local space relative to the anchor object. */
     instances: InstanceTransform[];
     /**
-     * Live `THREE.InstancedMesh` managed by {@link InstancedMeshSystem}.
+     * Live runtime container managed by {@link InstancedMeshSystem}:
+     * - For primitive kinds: a `THREE.InstancedMesh`.
+     * - For `"model"` kind: a `THREE.Group` containing per-mesh `THREE.InstancedMesh` objects.
      * Excluded from snapshot serialization — do **not** read this in hydration code.
      */
-    instancedMesh: THREE.InstancedMesh | null;
+    instancedMesh: THREE.Object3D | null;
     constructor(meshKind?: InstancedMeshKind, meshParameters?: Partial<MeshGeometryParameters>, options?: {
         castShadow?: boolean;
         receiveShadow?: boolean;
         instances?: InstanceTransform[];
+        modelPath?: string;
     });
     /** Sanitize and return a copy of the current mesh parameters with valid values. */
     getSanitizedParameters(): MeshGeometryParameters;

package/dist/{chunk-RXCUHGRB.js → chunk-2F6T3BVO.js}

@@ -1,5 +1,5 @@
-import { resolveDracoDecoderPath, applyTransform } from './chunk-CRP3W2GK.js';
-import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, AudioComponent, VideoComponent } from './chunk-KRZLEPRI.js';
+import { resolveDracoDecoderPath, applyTransform } from './chunk-FDWNCXU3.js';
+import { AnimationComponent, ModelComponent, CameraComponent, Object3DRef, Environment, Postprocessing, TransformComponent, PhysicsComponent, LightComponent, MaterialComponent, DEFAULT_MESH_GEOMETRY_PARAMETERS, MeshGeometryComponent, InstancedMeshComponent, ParentId, ScriptComponent, AudioComponent, VideoComponent } from './chunk-R5D5PWXV.js';
 import { __name } from './chunk-OY7ZODZP.js';
 import * as THREE7 from 'three';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
@@ -2269,6 +2269,32 @@ var _MeshGeometrySystem = class _MeshGeometrySystem {
 };
 __name(_MeshGeometrySystem, "MeshGeometrySystem");
 var MeshGeometrySystem = _MeshGeometrySystem;
+var DRACO_DECODER_PATH = resolveDracoDecoderPath();
+var loadGLTF = /* @__PURE__ */ __name((path) => {
+  return new Promise((resolve, reject) => {
+    const loader = new GLTFLoader();
+    try {
+      const dracoLoader = new DRACOLoader();
+      dracoLoader.setDecoderPath(DRACO_DECODER_PATH);
+      loader.setDRACOLoader(dracoLoader);
+    } catch (error) {
+      console.debug("DRACOLoader setup failed or unavailable", error);
+    }
+    loader.load(
+      path,
+      (gltf) => {
+        resolve(gltf);
+      },
+      void 0,
+      (error) => {
+        console.debug("GLTFLoader failed to load", error);
+        reject(error);
+      }
+    );
+  });
+}, "loadGLTF");
+
+// core/systems/InstancedMeshSystem.ts
 function buildGeometry(component) {
   const p = component.getSanitizedParameters();
   switch (component.meshKind) {
@@ -2292,6 +2318,8 @@ function buildGeometry(component) {
       const params = p;
       return new THREE7.CapsuleGeometry(params.radius, params.height, 4, 8);
     }
+    default:
+      return new THREE7.BoxGeometry(1, 1, 1);
   }
 }
 __name(buildGeometry, "buildGeometry");
@@ -2300,6 +2328,7 @@ var _quaternion = new THREE7.Quaternion();
 var _euler = new THREE7.Euler();
 var _scale = new THREE7.Vector3();
 var _matrix = new THREE7.Matrix4();
+var _modelMatrix = new THREE7.Matrix4();
 function instanceTransformToMatrix4(inst, out) {
   _position.set(inst.position.x, inst.position.y, inst.position.z);
   _euler.set(inst.rotation.x, inst.rotation.y, inst.rotation.z, "XYZ");
@@ -2308,51 +2337,165 @@ function instanceTransformToMatrix4(inst, out) {
   out.compose(_position, _quaternion, _scale);
 }
 __name(instanceTransformToMatrix4, "instanceTransformToMatrix4");
+function disposePrimitiveInstancedMesh(mesh) {
+  mesh.geometry.dispose();
+  if (Array.isArray(mesh.material)) {
+    for (const m of mesh.material) {
+      m.dispose();
+    }
+  } else {
+    mesh.material.dispose();
+  }
+}
+__name(disposePrimitiveInstancedMesh, "disposePrimitiveInstancedMesh");
+function disposeModelGroup(group) {
+  group.traverse((child) => {
+    const im = child;
+    if (im.isInstancedMesh) {
+      im.geometry.dispose();
+      if (Array.isArray(im.material)) {
+        for (const m of im.material) {
+          m.dispose();
+        }
+      } else {
+        im.material.dispose();
+      }
+    }
+  });
+}
+__name(disposeModelGroup, "disposeModelGroup");
 var _InstancedMeshSystem = class _InstancedMeshSystem {
   constructor() {
     /** Signature tracking for geometry + instance count changes. */
     this.geometrySignatures = /* @__PURE__ */ new Map();
+    /** Signature being loaded per entity. Maps entityId → geometrySignature in-flight.
+     * Prevents re-dispatching a load every frame while comp.instancedMesh is still null. */
+    this.loadingSignatures = /* @__PURE__ */ new Map();
+    /** Per-mesh data for model kind, populated after GLTF load. */
+    this.modelMeshEntries = /* @__PURE__ */ new Map();
   }
   update(world) {
     const entityIds = world.query(InstancedMeshComponent);
     const alive = new Set(entityIds);
     for (const trackedId of this.geometrySignatures.keys()) {
-      if (!alive.has(trackedId)) {
-        this.geometrySignatures.delete(trackedId);
-      }
+      if (!alive.has(trackedId)) this.geometrySignatures.delete(trackedId);
+    }
+    for (const trackedId of this.loadingSignatures.keys()) {
+      if (!alive.has(trackedId)) this.loadingSignatures.delete(trackedId);
+    }
+    for (const trackedId of this.modelMeshEntries.keys()) {
+      if (!alive.has(trackedId)) this.modelMeshEntries.delete(trackedId);
     }
     for (const entityId of entityIds) {
       const comp = world.getComponent(
         entityId,
         InstancedMeshComponent
       );
-      if (!comp) {
-        continue;
-      }
-      let anchor = null;
+      if (!comp) continue;
       const objectRef = world.getComponent(entityId, Object3DRef);
-      if (objectRef?.object) {
-        anchor = objectRef.object;
-      }
-      if (!anchor) {
-        continue;
-      }
+      const anchor = objectRef?.object ?? null;
+      if (!anchor) continue;
       const instanceCount = comp.instances.length;
-      const geometrySignature = `${comp.meshKind}:${JSON.stringify(comp.meshParameters)}:${instanceCount}`;
-      const needsRebuild = comp.instancedMesh === null || this.geometrySignatures.get(entityId) !== geometrySignature;
+      const geometrySignature = comp.meshKind === "model" ? `model:${comp.modelPath}:${instanceCount}` : `${comp.meshKind}:${JSON.stringify(comp.meshParameters)}:${instanceCount}`;
+      const pendingLoadSignature = this.loadingSignatures.get(entityId);
+      const needsRebuild = (comp.instancedMesh === null || this.geometrySignatures.get(entityId) !== geometrySignature) && pendingLoadSignature !== geometrySignature;
       if (needsRebuild) {
         if (comp.instancedMesh) {
           anchor.remove(comp.instancedMesh);
-          comp.instancedMesh.geometry.dispose();
-          if (Array.isArray(comp.instancedMesh.material)) {
-            for (const m of comp.instancedMesh.material) {
-              m.dispose();
-            }
+          if (comp.instancedMesh.isInstancedMesh) {
+            disposePrimitiveInstancedMesh(comp.instancedMesh);
           } else {
-            comp.instancedMesh.material.dispose();
+            disposeModelGroup(comp.instancedMesh);
           }
           comp.instancedMesh = null;
         }
+        if (pendingLoadSignature !== void 0 && pendingLoadSignature !== geometrySignature) {
+          this.loadingSignatures.delete(entityId);
+          this.modelMeshEntries.delete(entityId);
+        }
+        if (comp.meshKind === "model") {
+          if (comp.modelPath && !this.loadingSignatures.has(entityId)) {
+            this.loadingSignatures.set(entityId, geometrySignature);
+            const targetSignature = geometrySignature;
+            const targetEntityId = entityId;
+            loadGLTF(comp.modelPath).then((gltf) => {
+              if (!world.hasEntity(targetEntityId)) {
+                this.loadingSignatures.delete(targetEntityId);
+                return;
+              }
+              const currentComp = world.getComponent(
+                targetEntityId,
+                InstancedMeshComponent
+              );
+              if (!currentComp) {
+                this.loadingSignatures.delete(targetEntityId);
+                return;
+              }
+              const currentSig = `model:${currentComp.modelPath}:${currentComp.instances.length}`;
+              if (currentSig !== targetSignature) {
+                this.loadingSignatures.delete(targetEntityId);
+                return;
+              }
+              const currentRef = world.getComponent(targetEntityId, Object3DRef);
+              const currentAnchor = currentRef?.object ?? null;
+              if (!currentAnchor) {
+                this.loadingSignatures.delete(targetEntityId);
+                return;
+              }
+              if (currentComp.instancedMesh) {
+                currentAnchor.remove(currentComp.instancedMesh);
+                disposeModelGroup(currentComp.instancedMesh);
+                currentComp.instancedMesh = null;
+              }
+              const count2 = Math.max(1, currentComp.instances.length);
+              const entries = [];
+              gltf.scene.updateWorldMatrix(true, true);
+              gltf.scene.traverse((child) => {
+                const meshChild = child;
+                if (!meshChild.isMesh) return;
+                const geometry2 = meshChild.geometry.clone();
+                const sourceMaterial = Array.isArray(meshChild.material) ? meshChild.material.map((m) => m.clone()) : meshChild.material.clone();
+                meshChild.updateWorldMatrix(true, false);
+                const localMatrix = meshChild.matrixWorld.clone();
+                const instancedMesh2 = new THREE7.InstancedMesh(
+                  geometry2,
+                  Array.isArray(sourceMaterial) ? sourceMaterial : sourceMaterial,
+                  count2
+                );
+                instancedMesh2.castShadow = currentComp.castShadow;
+                instancedMesh2.receiveShadow = currentComp.receiveShadow;
+                for (let i = 0; i < count2; i++) {
+                  const inst = currentComp.instances[i] ?? {
+                    position: { x: 0, y: 0, z: 0 },
+                    rotation: { x: 0, y: 0, z: 0 },
+                    scale: { x: 1, y: 1, z: 1 }
+                  };
+                  instanceTransformToMatrix4(inst, _matrix);
+                  _modelMatrix.multiplyMatrices(_matrix, localMatrix);
+                  instancedMesh2.setMatrixAt(i, _modelMatrix);
+                }
+                instancedMesh2.instanceMatrix.needsUpdate = true;
+                entries.push({ localMatrix, instancedMesh: instancedMesh2 });
+              });
+              if (entries.length === 0) {
+                this.loadingSignatures.delete(targetEntityId);
+                return;
+              }
+              const group = new THREE7.Group();
+              for (const entry of entries) {
+                group.add(entry.instancedMesh);
+              }
+              currentAnchor.add(group);
+              currentComp.instancedMesh = group;
+              this.modelMeshEntries.set(targetEntityId, entries);
+              this.geometrySignatures.set(targetEntityId, targetSignature);
+              this.loadingSignatures.delete(targetEntityId);
+            }).catch(() => {
+              this.loadingSignatures.delete(targetEntityId);
+            });
+          }
+          continue;
+        }
         const count = Math.max(1, instanceCount);
         const geometry = buildGeometry(comp);
         const material = new THREE7.MeshStandardMaterial({ color: "#ffffff" });
@@ -2373,15 +2516,32 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
         comp.instancedMesh = instancedMesh;
         this.geometrySignatures.set(entityId, geometrySignature);
       } else {
-        const im = comp.instancedMesh;
-        const count = comp.instances.length;
-        for (let i = 0; i < count; i++) {
-          instanceTransformToMatrix4(comp.instances[i], _matrix);
-          im.setMatrixAt(i, _matrix);
+        if (comp.meshKind === "model") {
+          const entries = this.modelMeshEntries.get(entityId);
+          if (entries) {
+            const count = comp.instances.length;
+            for (const entry of entries) {
+              for (let i = 0; i < count; i++) {
+                instanceTransformToMatrix4(comp.instances[i], _matrix);
+                _modelMatrix.multiplyMatrices(_matrix, entry.localMatrix);
+                entry.instancedMesh.setMatrixAt(i, _modelMatrix);
+              }
+              entry.instancedMesh.instanceMatrix.needsUpdate = true;
+              entry.instancedMesh.castShadow = comp.castShadow;
+              entry.instancedMesh.receiveShadow = comp.receiveShadow;
+            }
+          }
+        } else {
+          const im = comp.instancedMesh;
+          const count = comp.instances.length;
+          for (let i = 0; i < count; i++) {
+            instanceTransformToMatrix4(comp.instances[i], _matrix);
+            im.setMatrixAt(i, _matrix);
+          }
+          im.instanceMatrix.needsUpdate = true;
+          im.castShadow = comp.castShadow;
+          im.receiveShadow = comp.receiveShadow;
         }
-        im.instanceMatrix.needsUpdate = true;
-        im.castShadow = comp.castShadow;
-        im.receiveShadow = comp.receiveShadow;
       }
     }
   }
@@ -3419,5 +3579,5 @@ __name(_VideoSystem, "VideoSystem");
 var VideoSystem = _VideoSystem;
 
 export { AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, ObjectVisibilitySystem, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, ScriptBehaviourSystem, TransformSyncSystem, VideoSystem };
-//# sourceMappingURL=chunk-RXCUHGRB.js.map
-//# sourceMappingURL=chunk-RXCUHGRB.js.map
+//# sourceMappingURL=chunk-2F6T3BVO.js.map
+//# sourceMappingURL=chunk-2F6T3BVO.js.map