@relu-interactives/spatial-ecs 0.2.6 → 0.2.8

package/dist/index.cjs

@@ -150,6 +150,13 @@ function normalizeDebugValue(value, ctx) {
       crossFadeDuration: typeof objectValue.crossFadeDuration === "number" && Number.isFinite(objectValue.crossFadeDuration) ? Math.max(0, objectValue.crossFadeDuration) : 0
     };
   }
+  if (constructorName === "InstanceSlotComponent") {
+    return {
+      __type: "InstanceSlotComponent",
+      groupEntityId: typeof objectValue.groupEntityId === "number" ? objectValue.groupEntityId : -1,
+      slotIndex: typeof objectValue.slotIndex === "number" ? objectValue.slotIndex : 0
+    };
+  }
   if (constructorName === "InstancedMeshComponent") {
     const imCtx = {
       seen: ctx.seen,
@@ -163,7 +170,7 @@ function normalizeDebugValue(value, ctx) {
       meshParameters: normalizeDebugValue(objectValue.meshParameters, imCtx),
       castShadow: Boolean(objectValue.castShadow),
       receiveShadow: Boolean(objectValue.receiveShadow),
-      instances: normalizeDebugValue(objectValue.instances, imCtx)
+      instanceEntityIds: Array.isArray(objectValue.instanceEntityIds) ? [...objectValue.instanceEntityIds] : []
     };
   }
   if (constructorName === "PhysicsComponent") {
@@ -2238,7 +2245,7 @@ var _InstancedMeshComponent = class _InstancedMeshComponent extends Component {
     };
     this.castShadow = options?.castShadow ?? false;
     this.receiveShadow = options?.receiveShadow ?? false;
-    this.instances = options?.instances && options.instances.length > 0 ? options.instances : [{ ...DEFAULT_INSTANCE_TRANSFORM }];
+    this.instanceEntityIds = options?.instanceEntityIds ?? [];
     this.instancedMesh = null;
   }
   /** Sanitize and return a copy of the current mesh parameters with valid values. */
@@ -2290,6 +2297,25 @@ function createInstancedMeshComponent(world, entityId, meshKind, meshParameters,
 }
 __name(createInstancedMeshComponent, "createInstancedMeshComponent");
 
+// core/components/InstanceSlotComponent.ts
+var _InstanceSlotComponent = class _InstanceSlotComponent extends Component {
+  constructor(groupEntityId, slotIndex) {
+    super();
+    this.groupEntityId = groupEntityId;
+    this.slotIndex = slotIndex;
+  }
+};
+__name(_InstanceSlotComponent, "InstanceSlotComponent");
+var InstanceSlotComponent = _InstanceSlotComponent;
+
+// core/factories/components/InstanceSlotComponentFactory.ts
+function createInstanceSlotComponent(world, entityId, groupEntityId, slotIndex) {
+  const component = new InstanceSlotComponent(groupEntityId, slotIndex);
+  world.addComponent(entityId, component);
+  return component;
+}
+__name(createInstanceSlotComponent, "createInstanceSlotComponent");
+
 // core/components/Video.ts
 var DEFAULT_VIDEO_OPTIONS = {
   autoplay: false,
@@ -3052,13 +3078,32 @@ function createImageTarget({
 }
 __name(createImageTarget, "createImageTarget");
 function isInstancedMeshKind(value) {
-  return value === "cube" || value === "sphere" || value === "plane" || value === "cylinder" || value === "capsule";
+  return value === "cube" || value === "sphere" || value === "plane" || value === "cylinder" || value === "capsule" || value === "model";
 }
 __name(isInstancedMeshKind, "isInstancedMeshKind");
-function isInstanceTransformArray(value) {
-  return Array.isArray(value);
+function createInstanceSlotEntity(world, groupEntityId, slotIndex, label, transform) {
+  const instanceEntityId = world.createEntity();
+  world.addComponent(instanceEntityId, new Name(label));
+  world.addComponent(
+    instanceEntityId,
+    createTransform(
+      transform ? {
+        position: transform.position,
+        rotation: transform.rotation,
+        scale: transform.scale
+      } : void 0
+    )
+  );
+  world.addComponent(
+    instanceEntityId,
+    new InstanceSlotComponent(groupEntityId, slotIndex)
+  );
+  world.addComponent(instanceEntityId, new EntityType("instanceSlot"));
+  world.addComponent(instanceEntityId, new Selectable(true));
+  world.addComponent(instanceEntityId, new ParentId(groupEntityId));
+  return instanceEntityId;
 }
-__name(isInstanceTransformArray, "isInstanceTransformArray");
+__name(createInstanceSlotEntity, "createInstanceSlotEntity");
 function createInstancedMesh({
   world,
   scene,
@@ -3068,25 +3113,68 @@ function createInstancedMesh({
   const opts = payload.options ?? {};
   const meshKind = isInstancedMeshKind(opts.meshKind) ? opts.meshKind : "cube";
   const meshParameters = opts.meshParameters && typeof opts.meshParameters === "object" ? opts.meshParameters : void 0;
-  const instances = isInstanceTransformArray(
-    opts.instances
-  ) ? opts.instances : void 0;
   const castShadow = typeof opts.castShadow === "boolean" ? opts.castShadow : false;
   const receiveShadow = typeof opts.receiveShadow === "boolean" ? opts.receiveShadow : false;
+  const modelPath = typeof opts.modelPath === "string" ? opts.modelPath : void 0;
   const entityId = createBaseEntity(world, anchor, {
     label: payload.name ?? "Instanced Mesh",
     entityType: "instancedMesh",
     transformInput: payload.transform
   });
+  let instanceEntityIds = [];
+  if (Array.isArray(opts.instanceEntityIds)) {
+    instanceEntityIds = [];
+  } else if (Array.isArray(opts.instances) && opts.instances.length > 0) {
+    const legacyInstances = opts.instances;
+    for (let i = 0; i < legacyInstances.length; i++) {
+      const slotId = createInstanceSlotEntity(
+        world,
+        entityId,
+        i,
+        `Instance ${i + 1}`,
+        legacyInstances[i]
+      );
+      instanceEntityIds.push(slotId);
+    }
+  } else {
+    const slotId = createInstanceSlotEntity(
+      world,
+      entityId,
+      0,
+      "Instance 1",
+      { ...DEFAULT_INSTANCE_TRANSFORM }
+    );
+    instanceEntityIds = [slotId];
+  }
   createInstancedMeshComponent(world, entityId, meshKind, meshParameters, {
     castShadow,
     receiveShadow,
-    instances
+    instanceEntityIds,
+    modelPath
   });
   scene.add(anchor);
   return entityId;
 }
 __name(createInstancedMesh, "createInstancedMesh");
+
+// core/factories/objects/InstanceSlotFactory.ts
+function createInstanceSlot({ world, payload }) {
+  const opts = payload.options ?? {};
+  const groupEntityId = typeof opts.groupEntityId === "number" ? opts.groupEntityId : -1;
+  const slotIndex = typeof opts.slotIndex === "number" ? opts.slotIndex : 0;
+  const entityId = world.createEntity();
+  world.addComponent(
+    entityId,
+    new Name(payload.name ?? `Instance ${slotIndex + 1}`)
+  );
+  world.addComponent(entityId, createTransform(payload.transform));
+  world.addComponent(entityId, new InstanceSlotComponent(groupEntityId, slotIndex));
+  world.addComponent(entityId, new EntityType("instanceSlot"));
+  world.addComponent(entityId, new Selectable(true));
+  world.addComponent(entityId, new ParentId(groupEntityId !== -1 ? groupEntityId : null));
+  return entityId;
+}
+__name(createInstanceSlot, "createInstanceSlot");
 function createAmbientLight({
   world,
   scene,
@@ -3260,6 +3348,7 @@ __export(components_exports, {
   ImageComponent: () => ImageComponent,
   ImageTarget: () => ImageTarget,
   ImageTargetAnchor: () => ImageTargetAnchor,
+  InstanceSlotComponent: () => InstanceSlotComponent,
   InstancedMeshComponent: () => InstancedMeshComponent,
   LightComponent: () => LightComponent,
   MaterialComponent: () => MaterialComponent,
@@ -3657,6 +3746,7 @@ function registerDefaultFactories(objectManagementSystem) {
   objectManagementSystem.register("image", createImage);
   objectManagementSystem.register("imageTarget", createImageTarget);
   objectManagementSystem.register("instancedMesh", createInstancedMesh);
+  objectManagementSystem.register("instanceSlot", createInstanceSlot);
   objectManagementSystem.register("sprite", createSprite);
   objectManagementSystem.register("audio", createAudio);
   objectManagementSystem.register("camera", createCamera);
@@ -5979,14 +6069,14 @@ var _euler = new THREE34__namespace.Euler();
 var _scale = new THREE34__namespace.Vector3();
 var _matrix = new THREE34__namespace.Matrix4();
 var _modelMatrix = new THREE34__namespace.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");
+function instanceTransformFromComponent(transform, out) {
+  _position.set(transform.position.x, transform.position.y, transform.position.z);
+  _euler.set(transform.rotation.x, transform.rotation.y, transform.rotation.z, "XYZ");
   _quaternion.setFromEuler(_euler);
-  _scale.set(inst.scale.x, inst.scale.y, inst.scale.z);
+  _scale.set(transform.scale.x, transform.scale.y, transform.scale.z);
   out.compose(_position, _quaternion, _scale);
 }
-__name(instanceTransformToMatrix4, "instanceTransformToMatrix4");
+__name(instanceTransformFromComponent, "instanceTransformFromComponent");
 function disposePrimitiveInstancedMesh(mesh) {
   mesh.geometry.dispose();
   if (Array.isArray(mesh.material)) {
@@ -6018,8 +6108,9 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
   constructor() {
     /** Signature tracking for geometry + instance count changes. */
     this.geometrySignatures = /* @__PURE__ */ new Map();
-    /** Entities whose GLTF model is currently loading. Prevents duplicate load triggers. */
-    this.loadingEntities = /* @__PURE__ */ new Set();
+    /** 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();
   }
@@ -6029,8 +6120,8 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
     for (const trackedId of this.geometrySignatures.keys()) {
       if (!alive.has(trackedId)) this.geometrySignatures.delete(trackedId);
     }
-    for (const trackedId of this.loadingEntities) {
-      if (!alive.has(trackedId)) this.loadingEntities.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);
@@ -6044,9 +6135,10 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
       const objectRef = world.getComponent(entityId, Object3DRef);
       const anchor = objectRef?.object ?? null;
       if (!anchor) continue;
-      const instanceCount = comp.instances.length;
+      const instanceCount = comp.instanceEntityIds.length;
       const geometrySignature = comp.meshKind === "model" ? `model:${comp.modelPath}:${instanceCount}` : `${comp.meshKind}:${JSON.stringify(comp.meshParameters)}:${instanceCount}`;
-      const needsRebuild = comp.instancedMesh === null || this.geometrySignatures.get(entityId) !== geometrySignature;
+      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);
@@ -6057,16 +6149,18 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
           }
           comp.instancedMesh = null;
         }
-        this.loadingEntities.delete(entityId);
-        this.modelMeshEntries.delete(entityId);
+        if (pendingLoadSignature !== void 0 && pendingLoadSignature !== geometrySignature) {
+          this.loadingSignatures.delete(entityId);
+          this.modelMeshEntries.delete(entityId);
+        }
         if (comp.meshKind === "model") {
-          if (comp.modelPath && !this.loadingEntities.has(entityId)) {
-            this.loadingEntities.add(entityId);
+          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.loadingEntities.delete(targetEntityId);
+                this.loadingSignatures.delete(targetEntityId);
                 return;
               }
               const currentComp = world.getComponent(
@@ -6074,21 +6168,26 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
                 InstancedMeshComponent
               );
               if (!currentComp) {
-                this.loadingEntities.delete(targetEntityId);
+                this.loadingSignatures.delete(targetEntityId);
                 return;
               }
-              const currentSig = `model:${currentComp.modelPath}:${currentComp.instances.length}`;
+              const currentSig = `model:${currentComp.modelPath}:${currentComp.instanceEntityIds.length}`;
               if (currentSig !== targetSignature) {
-                this.loadingEntities.delete(targetEntityId);
+                this.loadingSignatures.delete(targetEntityId);
                 return;
               }
               const currentRef = world.getComponent(targetEntityId, Object3DRef);
               const currentAnchor = currentRef?.object ?? null;
               if (!currentAnchor) {
-                this.loadingEntities.delete(targetEntityId);
+                this.loadingSignatures.delete(targetEntityId);
                 return;
               }
-              const count2 = Math.max(1, currentComp.instances.length);
+              if (currentComp.instancedMesh) {
+                currentAnchor.remove(currentComp.instancedMesh);
+                disposeModelGroup(currentComp.instancedMesh);
+                currentComp.instancedMesh = null;
+              }
+              const count2 = Math.max(1, currentComp.instanceEntityIds.length);
               const entries = [];
               gltf.scene.updateWorldMatrix(true, true);
               gltf.scene.traverse((child) => {
@@ -6106,12 +6205,13 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
                 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);
+                  const instanceEntityId = currentComp.instanceEntityIds[i];
+                  const instTransform = instanceEntityId !== void 0 ? world.getComponent(instanceEntityId, TransformComponent) ?? null : null;
+                  if (instTransform) {
+                    instanceTransformFromComponent(instTransform, _matrix);
+                  } else {
+                    _matrix.identity();
+                  }
                   _modelMatrix.multiplyMatrices(_matrix, localMatrix);
                   instancedMesh2.setMatrixAt(i, _modelMatrix);
                 }
@@ -6119,7 +6219,7 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
                 entries.push({ localMatrix, instancedMesh: instancedMesh2 });
               });
               if (entries.length === 0) {
-                this.loadingEntities.delete(targetEntityId);
+                this.loadingSignatures.delete(targetEntityId);
                 return;
               }
               const group = new THREE34__namespace.Group();
@@ -6130,9 +6230,9 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
               currentComp.instancedMesh = group;
               this.modelMeshEntries.set(targetEntityId, entries);
               this.geometrySignatures.set(targetEntityId, targetSignature);
-              this.loadingEntities.delete(targetEntityId);
+              this.loadingSignatures.delete(targetEntityId);
             }).catch(() => {
-              this.loadingEntities.delete(targetEntityId);
+              this.loadingSignatures.delete(targetEntityId);
             });
           }
           continue;
@@ -6144,12 +6244,13 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
         instancedMesh.castShadow = comp.castShadow;
         instancedMesh.receiveShadow = comp.receiveShadow;
         for (let i = 0; i < count; i++) {
-          const inst = comp.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);
+          const instanceEntityId = comp.instanceEntityIds[i];
+          const instTransform = instanceEntityId !== void 0 ? world.getComponent(instanceEntityId, TransformComponent) ?? null : null;
+          if (instTransform) {
+            instanceTransformFromComponent(instTransform, _matrix);
+          } else {
+            _matrix.identity();
+          }
           instancedMesh.setMatrixAt(i, _matrix);
         }
         instancedMesh.instanceMatrix.needsUpdate = true;
@@ -6160,10 +6261,16 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
         if (comp.meshKind === "model") {
           const entries = this.modelMeshEntries.get(entityId);
           if (entries) {
-            const count = comp.instances.length;
+            const count = comp.instanceEntityIds.length;
             for (const entry of entries) {
               for (let i = 0; i < count; i++) {
-                instanceTransformToMatrix4(comp.instances[i], _matrix);
+                const instanceEntityId = comp.instanceEntityIds[i];
+                const instTransform = instanceEntityId !== void 0 ? world.getComponent(instanceEntityId, TransformComponent) ?? null : null;
+                if (instTransform) {
+                  instanceTransformFromComponent(instTransform, _matrix);
+                } else {
+                  _matrix.identity();
+                }
                 _modelMatrix.multiplyMatrices(_matrix, entry.localMatrix);
                 entry.instancedMesh.setMatrixAt(i, _modelMatrix);
               }
@@ -6174,9 +6281,15 @@ var _InstancedMeshSystem = class _InstancedMeshSystem {
           }
         } else {
           const im = comp.instancedMesh;
-          const count = comp.instances.length;
+          const count = comp.instanceEntityIds.length;
           for (let i = 0; i < count; i++) {
-            instanceTransformToMatrix4(comp.instances[i], _matrix);
+            const instanceEntityId = comp.instanceEntityIds[i];
+            const instTransform = instanceEntityId !== void 0 ? world.getComponent(instanceEntityId, TransformComponent) ?? null : null;
+            if (instTransform) {
+              instanceTransformFromComponent(instTransform, _matrix);
+            } else {
+              _matrix.identity();
+            }
             im.setMatrixAt(i, _matrix);
           }
           im.instanceMatrix.needsUpdate = true;
@@ -8138,7 +8251,8 @@ function buildComponentValueMaps(snapshot) {
     animationValues: readByComponent(snapshot.components, "AnimationComponent"),
     imageTargetAnchorValues: readByComponent(snapshot.components, "ImageTargetAnchor"),
     scriptValues: readByComponent(snapshot.components, "ScriptComponent"),
-    instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent")
+    instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
+    instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent")
   };
 }
 __name(buildComponentValueMaps, "buildComponentValueMaps");
@@ -8252,6 +8366,20 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       new ScriptComponent(entries)
     );
   }
+  {
+    const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
+    if (imComponent && imComponent.instanceEntityIds.length > 0) {
+      imComponent.instanceEntityIds = imComponent.instanceEntityIds.map(
+        (oldId) => idMap.get(oldId) ?? oldId
+      );
+    }
+  }
+  {
+    const slotComponent = world.getComponent(targetEntityId, InstanceSlotComponent);
+    if (slotComponent && slotComponent.groupEntityId !== -1) {
+      slotComponent.groupEntityId = idMap.get(slotComponent.groupEntityId) ?? slotComponent.groupEntityId;
+    }
+  }
 }
 __name(restorePostCreateComponents, "restorePostCreateComponents");
 
@@ -8755,12 +8883,21 @@ function restoreComponentState(world, objectManagementSystem, targetEntityId, so
       if (typeof sourceInstancedMesh.receiveShadow === "boolean") {
         imComponent.receiveShadow = sourceInstancedMesh.receiveShadow;
       }
-      if (Array.isArray(sourceInstancedMesh.instances)) {
-        imComponent.instances = sourceInstancedMesh.instances;
+      if (Array.isArray(sourceInstancedMesh.instanceEntityIds)) {
+        imComponent.instanceEntityIds = sourceInstancedMesh.instanceEntityIds;
       }
       imComponent.instancedMesh = null;
     }
   }
+  const sourceInstanceSlot = asRecord3(values.instanceSlotValues.get(sourceEntityId));
+  if (sourceInstanceSlot) {
+    const slotComponent = world.getComponent(targetEntityId, InstanceSlotComponent);
+    if (slotComponent) {
+      if (typeof sourceInstanceSlot.slotIndex === "number") {
+        slotComponent.slotIndex = sourceInstanceSlot.slotIndex;
+      }
+    }
+  }
 }
 __name(restoreComponentState, "restoreComponentState");
 
@@ -8784,7 +8921,8 @@ var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "pointLight",
   "spotLight",
   "areaLight",
-  "instancedMesh"
+  "instancedMesh",
+  "instanceSlot"
 ]);
 
 // core/hydration/hydrateWorld.ts
@@ -8866,10 +9004,23 @@ function buildEntityCreationPayload(sourceEntityId, kind, componentValues) {
     if (im) {
       payload.options = {
         meshKind: typeof im.meshKind === "string" ? im.meshKind : "cube",
+        modelPath: typeof im.modelPath === "string" ? im.modelPath : void 0,
         meshParameters: asRecord3(im.meshParameters) ?? void 0,
         castShadow: typeof im.castShadow === "boolean" ? im.castShadow : false,
         receiveShadow: typeof im.receiveShadow === "boolean" ? im.receiveShadow : false,
-        instances: Array.isArray(im.instances) ? im.instances : void 0
+        // New format: signal the factory to skip child entity creation.
+        // Old format (instances[]): pass through for migration — factory will
+        // create slot entities from the legacy InstanceTransform array.
+        ...Array.isArray(im.instanceEntityIds) ? { instanceEntityIds: im.instanceEntityIds } : Array.isArray(im.instances) ? { instances: im.instances } : {}
+      };
+    }
+  }
+  if (kind === "instanceSlot") {
+    const slot = asRecord3(componentValues.instanceSlotValues.get(sourceEntityId));
+    if (slot) {
+      payload.options = {
+        groupEntityId: typeof slot.groupEntityId === "number" ? slot.groupEntityId : -1,
+        slotIndex: typeof slot.slotIndex === "number" ? slot.slotIndex : 0
       };
     }
   }
@@ -9017,6 +9168,7 @@ exports.createEnvironmentComponent = createEnvironmentComponent;
 exports.createImageComponent = createImageComponent;
 exports.createImageTargetAnchorComponent = createImageTargetAnchorComponent;
 exports.createImageTargetComponent = createImageTargetComponent;
+exports.createInstanceSlotComponent = createInstanceSlotComponent;
 exports.createInstancedMeshComponent = createInstancedMeshComponent;
 exports.createLightComponent = createLightComponent;
 exports.createMaterialComponent = createMaterialComponent;