@codehz/ecs 0.3.4 → 0.3.6

package/archetype.d.ts

@@ -117,6 +117,14 @@ export declare class Archetype {
      * @returns An array of component data or undefined if not present
      */
     getOptionalComponentData<T>(componentType: EntityId<T>): T[] | undefined;
+    /**
+     * Helper: compute or return cached data sources for provided componentTypes
+     */
+    private getCachedComponentDataSources;
+    /**
+     * Helper: build component tuples for a specific entity index using precomputed data sources
+     */
+    private buildComponentsForIndex;
     /**
      * Get entities with their component data for specified component types
      * Optimized for bulk component access with pre-computed indices
@@ -127,6 +135,15 @@ export declare class Archetype {
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
+    /**
+     * Iterate over entities with their component data for specified component types
+     * implemented as a generator returning each entity/components pair lazily
+     * @param componentTypes Array of component types to retrieve
+     */
+    iterateWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
     /**
      * Iterate over entities with their component data for specified component types
      * Optimized for bulk component access

package/index.js

@@ -402,16 +402,9 @@ class Archetype {
   getOptionalComponentData(componentType) {
     return this.componentData.get(componentType);
   }
-  getEntitiesWithComponents(componentTypes) {
-    const result = [];
-    this.forEachWithComponents(componentTypes, (entity, ...components) => {
-      result.push({ entity, components });
-    });
-    return result;
-  }
-  forEachWithComponents(componentTypes, callback) {
+  getCachedComponentDataSources(componentTypes) {
     const cacheKey = componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
-    const componentDataSources = getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
+    return getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
       return componentTypes.map((compType) => {
         let optional = false;
         if (isOptionalEntityId(compType)) {
@@ -433,46 +426,67 @@ class Archetype {
         }
       });
     });
-    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
-      const entity = this.entities[entityIndex];
-      const components = componentDataSources.map((dataSource, i) => {
-        let compType = componentTypes[i];
-        let optional = false;
-        if (isOptionalEntityId(compType)) {
-          compType = compType.optional;
-          optional = true;
-        }
-        if (getIdType(compType) === "wildcard-relation") {
-          if (dataSource === undefined) {
-            if (optional) {
-              return;
-            } else {
-              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
-            }
-          }
-          const matchingRelations = dataSource;
-          const relations = [];
-          for (const relType of matchingRelations) {
-            const dataArray = this.getComponentData(relType);
-            const data = dataArray[entityIndex];
-            const decodedRel = decodeRelationId(relType);
-            relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
-          }
-          return optional ? { value: relations } : relations;
-        } else {
-          if (dataSource === undefined) {
-            if (optional) {
-              return;
-            } else {
-              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
-            }
+  }
+  buildComponentsForIndex(componentTypes, componentDataSources, entityIndex) {
+    return componentDataSources.map((dataSource, i) => {
+      let compType = componentTypes[i];
+      let optional = false;
+      if (isOptionalEntityId(compType)) {
+        compType = compType.optional;
+        optional = true;
+      }
+      if (getIdType(compType) === "wildcard-relation") {
+        if (dataSource === undefined) {
+          if (optional) {
+            return;
+          } else {
+            throw new Error(`No matching relations found for mandatory wildcard relation component type`);
           }
-          const dataArray = dataSource;
+        }
+        const matchingRelations = dataSource;
+        const relations = [];
+        for (const relType of matchingRelations) {
+          const dataArray = this.getComponentData(relType);
           const data = dataArray[entityIndex];
-          const result = data === MISSING_COMPONENT ? undefined : data;
-          return optional ? { value: result } : result;
+          const decodedRel = decodeRelationId(relType);
+          relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
         }
-      });
+        return optional ? { value: relations } : relations;
+      } else {
+        if (dataSource === undefined) {
+          if (optional) {
+            return;
+          } else {
+            throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+          }
+        }
+        const dataArray = dataSource;
+        const data = dataArray[entityIndex];
+        const result = data === MISSING_COMPONENT ? undefined : data;
+        return optional ? { value: result } : result;
+      }
+    });
+  }
+  getEntitiesWithComponents(componentTypes) {
+    const result = [];
+    this.forEachWithComponents(componentTypes, (entity, ...components) => {
+      result.push({ entity, components });
+    });
+    return result;
+  }
+  *iterateWithComponents(componentTypes) {
+    const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
+      const entity = this.entities[entityIndex];
+      const components = this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex);
+      yield { entity, components };
+    }
+  }
+  forEachWithComponents(componentTypes, callback) {
+    const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
+      const entity = this.entities[entityIndex];
+      const components = this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex);
       callback(entity, ...components);
     }
   }
@@ -756,6 +770,14 @@ class Query {
       archetype.forEachWithComponents(componentTypes, callback);
     }
   }
+  *iterate(componentTypes) {
+    if (this.isDisposed) {
+      throw new Error("Query has been disposed");
+    }
+    for (const archetype of this.cachedArchetypes) {
+      yield* archetype.iterateWithComponents(componentTypes);
+    }
+  }
   getComponentData(componentType) {
     if (this.isDisposed) {
       throw new Error("Query has been disposed");
@@ -884,6 +906,7 @@ class World {
   commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   hooks = new Map;
   exclusiveComponents = new Set;
+  cascadeDeleteComponents = new Set;
   constructor(snapshot) {
     if (snapshot && typeof snapshot === "object") {
       if (snapshot.entityManager) {
@@ -953,14 +976,29 @@ class World {
     return entityId;
   }
   destroyEntityImmediate(entityId) {
-    const archetype = this.entityToArchetype.get(entityId);
-    if (!archetype) {
-      return;
-    }
-    const componentReferences = this.getEntityReferences(entityId);
-    for (const [sourceEntityId, componentType] of componentReferences) {
-      const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
-      if (sourceArchetype) {
+    const queue = [entityId];
+    const visited = new Set;
+    while (queue.length > 0) {
+      const cur = queue.shift();
+      if (visited.has(cur))
+        continue;
+      visited.add(cur);
+      const archetype = this.entityToArchetype.get(cur);
+      if (!archetype) {
+        continue;
+      }
+      const componentReferences = Array.from(this.getEntityReferences(cur));
+      for (const [sourceEntityId, componentType] of componentReferences) {
+        const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
+        if (!sourceArchetype)
+          continue;
+        const detailedType = getDetailedIdType(componentType);
+        if (detailedType.type === "entity-relation" && this.cascadeDeleteComponents.has(detailedType.componentId)) {
+          if (!visited.has(sourceEntityId)) {
+            queue.push(sourceEntityId);
+          }
+          continue;
+        }
         const currentComponents = new Map;
         let removedComponent = sourceArchetype.get(sourceEntityId, componentType);
         for (const archetypeComponentType of sourceArchetype.componentTypes) {
@@ -976,17 +1014,17 @@ class World {
         }
         newArchetype.addEntity(sourceEntityId, currentComponents);
         this.entityToArchetype.set(sourceEntityId, newArchetype);
-        this.untrackEntityReference(sourceEntityId, componentType, entityId);
+        this.untrackEntityReference(sourceEntityId, componentType, cur);
         this.triggerLifecycleHooks(sourceEntityId, new Map, new Map([[componentType, removedComponent]]));
       }
+      this.entityReferences.delete(cur);
+      archetype.removeEntity(cur);
+      if (archetype.getEntities().length === 0) {
+        this.cleanupEmptyArchetype(archetype);
+      }
+      this.entityToArchetype.delete(cur);
+      this.entityIdManager.deallocate(cur);
     }
-    this.entityReferences.delete(entityId);
-    archetype.removeEntity(entityId);
-    if (archetype.getEntities().length === 0) {
-      this.cleanupEmptyArchetype(archetype);
-    }
-    this.entityToArchetype.delete(entityId);
-    this.entityIdManager.deallocate(entityId);
   }
   exists(entityId) {
     return this.entityToArchetype.has(entityId);
@@ -1066,6 +1104,9 @@ class World {
   setExclusive(componentId) {
     this.exclusiveComponents.add(componentId);
   }
+  setCascadeDelete(componentId) {
+    this.cascadeDeleteComponents.add(componentId);
+  }
   update(...params) {
     const result = this.systemScheduler.update(...params);
     if (result instanceof Promise) {
@@ -1293,14 +1334,14 @@ class World {
   untrackEntityReference(sourceEntityId, componentType, targetEntityId) {
     const references = this.entityReferences.get(targetEntityId);
     if (references) {
-      references.get(sourceEntityId).delete(componentType);
+      references.remove(sourceEntityId, componentType);
       if (references.keyCount === 0) {
         this.entityReferences.delete(targetEntityId);
       }
     }
   }
   getEntityReferences(targetEntityId) {
-    return this.entityReferences.get(targetEntityId) ?? [];
+    return this.entityReferences.get(targetEntityId) ?? new MultiMap;
   }
   cleanupEmptyArchetype(archetype) {
     if (archetype.getEntities().length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/query.d.ts

@@ -32,6 +32,14 @@ export declare class Query {
      * @param callback Function called for each entity with its components
      */
     forEach<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    /**
+     * Iterate over entities with their component data (generator)
+     * @param componentTypes Array of component types to retrieve
+     */
+    iterate<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
     /**
      * Get component data arrays for all matching entities
      * @param componentType The component type to retrieve

package/world.d.ts

@@ -35,6 +35,8 @@ export declare class World<UpdateParams extends any[] = []> {
     private hooks;
     /** Set of component IDs marked as exclusive relations */
     private exclusiveComponents;
+    /** Set of component IDs that will cascade delete when the relation target is deleted */
+    private cascadeDeleteComponents;
     /**
      * Create a new World.
      * If an optional snapshot object is provided (previously produced by `world.serialize()`),
@@ -108,6 +110,13 @@ export declare class World<UpdateParams extends any[] = []> {
      * For exclusive relations, an entity can have at most one relation per base component
      */
     setExclusive(componentId: EntityId): void;
+    /**
+     * Mark a component as cascade-delete relation
+     * For cascade relations, when the relation target entity is deleted,
+     * the referencing entity will also be deleted (cascade).
+     * Only applicable to entity-relation components
+     */
+    setCascadeDelete(componentId: EntityId): void;
     /**
      * Update the world (run all systems in dependency order)
      * This function is synchronous when all systems are synchronous,