@codehz/ecs 0.0.0 → 0.0.2

package/README.md

@@ -4,10 +4,11 @@
 
 ## 特性
 
-- 🚀 高性能：基于原型的组件存储和高效的查询系统
+- 🚀 高性能：基于 Archetype 的组件存储和高效的查询系统
 - 🔧 类型安全：完整的 TypeScript 支持
 - 🏗️ 模块化：清晰的架构，支持自定义系统和组件
 - 📦 轻量级：零依赖，易于集成
+- ⚡ 内存高效：连续内存布局，优化的迭代性能
 
 ## 安装
 
@@ -44,14 +45,48 @@ world.flushCommands();
 
 // 创建查询并更新
 const query = world.createQuery([PositionId, VelocityId]);
+const deltaTime = 1.0 / 60.0; // 假设60FPS
 query.forEach([PositionId, VelocityId], (entity, position, velocity) => {
   position.x += velocity.x * deltaTime;
   position.y += velocity.y * deltaTime;
 });
 ```
 
+### 组件生命周期钩子
+
+ECS 支持在组件添加或移除时执行回调函数：
+
+```typescript
+// 注册组件生命周期钩子
+world.registerComponentLifecycleHook(PositionId, {
+  onAdded: (entityId, componentType, component) => {
+    console.log(`组件 ${componentType} 被添加到实体 ${entityId}`);
+  },
+  onRemoved: (entityId, componentType) => {
+    console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
+  }
+});
+
+// 你也可以只注册其中一个钩子
+world.registerComponentLifecycleHook(VelocityId, {
+  onRemoved: (entityId, componentType) => {
+    console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
+  }
+});
+
+// 添加组件时会触发钩子
+world.addComponent(entity, PositionId, { x: 0, y: 0 });
+world.flushCommands(); // 钩子在这里被调用
+```
+
 ### 运行示例
 
+```bash
+bun run demo
+```
+
+或者直接运行：
+
 ```bash
 bun run examples/simple/demo.ts
 ```
@@ -65,6 +100,8 @@ bun run examples/simple/demo.ts
 - `removeComponent(entity, componentId)`: 从实体移除组件
 - `createQuery(componentIds)`: 创建查询
 - `registerSystem(system)`: 注册系统
+- `registerComponentLifecycleHook(componentId, hook)`: 注册组件生命周期钩子
+- `unregisterComponentLifecycleHook(componentId, hook)`: 注销组件生命周期钩子
 - `update(deltaTime)`: 更新世界
 - `flushCommands()`: 应用命令缓冲区
 
@@ -75,6 +112,8 @@ bun run examples/simple/demo.ts
 ### Query
 
 - `forEach(componentIds, callback)`: 遍历匹配的实体
+- `getEntities()`: 获取所有匹配实体的ID列表
+- `getEntitiesWithComponents(componentIds)`: 获取实体及其组件数据
 
 ### System
 
@@ -88,6 +127,13 @@ class MySystem implements System {
 }
 ```
 
+## 性能特点
+
+- **Archetype 系统**：实体按组件组合分组，实现连续内存访问
+- **缓存查询**：查询结果自动缓存，减少重复计算
+- **命令缓冲区**：延迟执行组件添加/移除，提高批处理效率
+- **类型安全**：编译时类型检查，无运行时开销
+
 ## 开发
 
 ### 运行测试
@@ -106,20 +152,28 @@ bunx tsc --noEmit
 
 ```
 src/
-├── index.ts          # 入口文件
-├── entity.ts         # 实体和组件管理
-├── world.ts          # 世界管理
-├── archetype.ts      # 原型系统
-├── query.ts          # 查询系统
-├── system.ts         # 系统接口
-├── command-buffer.ts # 命令缓冲区
-├── types.ts          # 类型定义
-└── utils.ts          # 工具函数
+├── index.ts              # 入口文件
+├── entity.ts             # 实体和组件管理
+├── world.ts              # 世界管理
+├── archetype.ts          # Archetype 系统（高效组件存储）
+├── query.ts              # 查询系统
+├── query-filter.ts       # 查询过滤器
+├── system.ts             # 系统接口
+├── command-buffer.ts     # 命令缓冲区
+├── types.ts              # 类型定义
+├── utils.ts              # 工具函数
+├── *.test.ts             # 单元测试
+├── query.example.ts      # 查询示例
+└── *.perf.test.ts        # 性能测试
 
 examples/
 └── simple/
-    ├── demo.ts       # 基本示例
-    └── README.md     # 示例说明
+    ├── demo.ts           # 基本示例
+    └── README.md         # 示例说明
+
+scripts/
+├── build.ts             # 构建脚本
+└── release.ts           # 发布脚本
 ```
 
 ## 许可证

package/archetype.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from "./entity";
+import type { EntityId, WildcardRelationId } from "./entity";
 import type { ComponentTuple } from "./types";
 /**
  * Archetype class for ECS architecture
@@ -60,6 +60,13 @@ export declare class Archetype {
      * @param entityId The entity to check
      */
     hasEntity(entityId: EntityId): boolean;
+    /**
+     * Get component data for a specific entity and wildcard relation type
+     * Returns an array of all matching relation instances
+     * @param entityId The entity
+     * @param componentType The wildcard relation type
+     */
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
     /**
      * Get component data for a specific entity and component type
      * @param entityId The entity

package/index.d.ts

@@ -3,3 +3,4 @@ export * from "./world";
 export * from "./archetype";
 export * from "./query";
 export * from "./system";
+export * from "./types";

package/index.js

@@ -275,9 +275,29 @@ class Archetype {
   getComponent(entityId, componentType) {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
-      return;
+      if (getIdType(componentType) === "wildcard-relation") {
+        return [];
+      } else {
+        return;
+      }
+    }
+    if (getIdType(componentType) === "wildcard-relation") {
+      const decoded = decodeRelationId(componentType);
+      const componentId = decoded.componentId;
+      const relations = [];
+      for (const relType of this.componentTypes) {
+        const relDecoded = decodeRelationId(relType);
+        if (relDecoded.componentId === componentId && (getIdType(relType) === "entity-relation" || getIdType(relType) === "component-relation")) {
+          const dataArray = this.componentData.get(relType);
+          if (dataArray && dataArray[index] !== undefined) {
+            relations.push([relDecoded.targetId, dataArray[index]]);
+          }
+        }
+      }
+      return relations;
+    } else {
+      return this.componentData.get(componentType)?.[index];
     }
-    return this.componentData.get(componentType)?.[index];
   }
   setComponent(entityId, componentType, data) {
     const index = this.entityToIndex.get(entityId);
@@ -374,17 +394,26 @@ class CommandBuffer {
     this.commands.push({ type: "destroyEntity", entityId });
   }
   execute() {
-    const entityCommands = new Map;
-    for (const cmd of this.commands) {
-      if (!entityCommands.has(cmd.entityId)) {
-        entityCommands.set(cmd.entityId, []);
+    const MAX_ITERATIONS = 100;
+    let iterations = 0;
+    while (this.commands.length > 0) {
+      if (iterations >= MAX_ITERATIONS) {
+        throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
+      }
+      iterations++;
+      const currentCommands = [...this.commands];
+      this.commands = [];
+      const entityCommands = new Map;
+      for (const cmd of currentCommands) {
+        if (!entityCommands.has(cmd.entityId)) {
+          entityCommands.set(cmd.entityId, []);
+        }
+        entityCommands.get(cmd.entityId).push(cmd);
+      }
+      for (const [entityId, commands] of entityCommands) {
+        this.executeEntityCommands(entityId, commands);
       }
-      entityCommands.get(cmd.entityId).push(cmd);
-    }
-    for (const [entityId, commands] of entityCommands) {
-      this.executeEntityCommands(entityId, commands);
     }
-    this.commands = [];
   }
   getCommands() {
     return [...this.commands];
@@ -512,6 +541,9 @@ class World {
   queries = [];
   commandBuffer;
   componentToArchetypes = new Map;
+  componentLifecycleHooks = new Map;
+  wildcardRelationLifecycleHooks = new Map;
+  entityReverseIndex = new Map;
   constructor() {
     this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   }
@@ -530,7 +562,36 @@ class World {
     if (!archetype) {
       return;
     }
+    const componentReferences = this.getComponentReferences(entityId);
+    for (const { sourceEntityId, componentType } of componentReferences) {
+      const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
+      if (sourceArchetype) {
+        const currentComponents = new Map;
+        for (const compType of sourceArchetype.componentTypes) {
+          if (compType !== componentType) {
+            const data = sourceArchetype.getComponent(sourceEntityId, compType);
+            if (data !== undefined) {
+              currentComponents.set(compType, data);
+            }
+          }
+        }
+        const newComponentTypes = Array.from(currentComponents.keys()).sort((a, b) => a - b);
+        const newArchetype = this.getOrCreateArchetype(newComponentTypes);
+        sourceArchetype.removeEntity(sourceEntityId);
+        if (sourceArchetype.getEntities().length === 0) {
+          this.removeEmptyArchetype(sourceArchetype);
+        }
+        newArchetype.addEntity(sourceEntityId, currentComponents);
+        this.entityToArchetype.set(sourceEntityId, newArchetype);
+        this.removeComponentReference(sourceEntityId, componentType, entityId);
+        this.executeComponentLifecycleHooks(sourceEntityId, new Map, new Set([componentType]));
+      }
+    }
+    this.entityReverseIndex.delete(entityId);
     archetype.removeEntity(entityId);
+    if (archetype.getEntities().length === 0) {
+      this.removeEmptyArchetype(archetype);
+    }
     this.entityToArchetype.delete(entityId);
     this.entityIdManager.deallocate(entityId);
   }
@@ -541,12 +602,23 @@ class World {
     if (!this.hasEntity(entityId)) {
       throw new Error(`Entity ${entityId} does not exist`);
     }
+    const detailedType = getDetailedIdType(componentType);
+    if (detailedType.type === "invalid") {
+      throw new Error(`Invalid component type: ${componentType}`);
+    }
+    if (detailedType.type === "wildcard-relation") {
+      throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
+    }
     this.commandBuffer.addComponent(entityId, componentType, component);
   }
   removeComponent(entityId, componentType) {
     if (!this.hasEntity(entityId)) {
       throw new Error(`Entity ${entityId} does not exist`);
     }
+    const detailedType = getDetailedIdType(componentType);
+    if (detailedType.type === "invalid") {
+      throw new Error(`Invalid component type: ${componentType}`);
+    }
     this.commandBuffer.removeComponent(entityId, componentType);
   }
   destroyEntity(entityId) {
@@ -558,7 +630,14 @@ class World {
   }
   getComponent(entityId, componentType) {
     const archetype = this.entityToArchetype.get(entityId);
-    return archetype ? archetype.getComponent(entityId, componentType) : undefined;
+    if (!archetype) {
+      if (getIdType(componentType) === "wildcard-relation") {
+        return [];
+      } else {
+        return;
+      }
+    }
+    return archetype.getComponent(entityId, componentType);
   }
   registerSystem(system) {
     this.systems.push(system);
@@ -569,6 +648,36 @@ class World {
       this.systems.splice(index, 1);
     }
   }
+  registerComponentLifecycleHook(componentType, hook) {
+    if (!this.componentLifecycleHooks.has(componentType)) {
+      this.componentLifecycleHooks.set(componentType, new Set);
+    }
+    this.componentLifecycleHooks.get(componentType).add(hook);
+  }
+  unregisterComponentLifecycleHook(componentType, hook) {
+    const hooks = this.componentLifecycleHooks.get(componentType);
+    if (hooks) {
+      hooks.delete(hook);
+      if (hooks.size === 0) {
+        this.componentLifecycleHooks.delete(componentType);
+      }
+    }
+  }
+  registerWildcardRelationLifecycleHook(baseComponentType, hook) {
+    if (!this.wildcardRelationLifecycleHooks.has(baseComponentType)) {
+      this.wildcardRelationLifecycleHooks.set(baseComponentType, new Set);
+    }
+    this.wildcardRelationLifecycleHooks.get(baseComponentType).add(hook);
+  }
+  unregisterWildcardRelationLifecycleHook(baseComponentType, hook) {
+    const hooks = this.wildcardRelationLifecycleHooks.get(baseComponentType);
+    if (hooks) {
+      hooks.delete(hook);
+      if (hooks.size === 0) {
+        this.wildcardRelationLifecycleHooks.delete(baseComponentType);
+      }
+    }
+  }
   update(...params) {
     for (const system of this.systems) {
       system.update(this, ...params);
@@ -687,8 +796,22 @@ class World {
           break;
         case "removeComponent":
           if (cmd.componentType) {
-            removes.add(cmd.componentType);
-            adds.delete(cmd.componentType);
+            const detailedType = getDetailedIdType(cmd.componentType);
+            if (detailedType.type === "wildcard-relation") {
+              const baseComponentId = detailedType.componentId;
+              for (const componentType of currentArchetype.componentTypes) {
+                const componentDetailedType = getDetailedIdType(componentType);
+                if (componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") {
+                  if (componentDetailedType.componentId === baseComponentId) {
+                    removes.add(componentType);
+                    adds.delete(componentType);
+                  }
+                }
+              }
+            } else {
+              removes.add(cmd.componentType);
+              adds.delete(cmd.componentType);
+            }
           }
           break;
       }
@@ -713,6 +836,25 @@ class World {
         currentArchetype.setComponent(entityId, componentType, component);
       }
     }
+    for (const componentType of removes) {
+      const detailedType = getDetailedIdType(componentType);
+      if (detailedType.type === "entity-relation") {
+        const targetEntityId = detailedType.targetId;
+        this.removeComponentReference(entityId, componentType, targetEntityId);
+      } else if (detailedType.type === "entity") {
+        this.removeComponentReference(entityId, componentType, componentType);
+      }
+    }
+    for (const [componentType, component] of adds) {
+      const detailedType = getDetailedIdType(componentType);
+      if (detailedType.type === "entity-relation") {
+        const targetEntityId = detailedType.targetId;
+        this.addComponentReference(entityId, componentType, targetEntityId);
+      } else if (detailedType.type === "entity") {
+        this.addComponentReference(entityId, componentType, componentType);
+      }
+    }
+    this.executeComponentLifecycleHooks(entityId, adds, removes);
   }
   getOrCreateArchetype(componentTypes) {
     const sortedTypes = [...componentTypes].sort((a, b) => a - b);
@@ -731,6 +873,96 @@ class World {
       return newArchetype;
     });
   }
+  addComponentReference(sourceEntityId, componentType, targetEntityId) {
+    if (!this.entityReverseIndex.has(targetEntityId)) {
+      this.entityReverseIndex.set(targetEntityId, new Set);
+    }
+    this.entityReverseIndex.get(targetEntityId).add({ sourceEntityId, componentType });
+  }
+  removeComponentReference(sourceEntityId, componentType, targetEntityId) {
+    const references = this.entityReverseIndex.get(targetEntityId);
+    if (references) {
+      references.forEach((ref) => {
+        if (ref.sourceEntityId === sourceEntityId && ref.componentType === componentType) {
+          references.delete(ref);
+        }
+      });
+      if (references.size === 0) {
+        this.entityReverseIndex.delete(targetEntityId);
+      }
+    }
+  }
+  getComponentReferences(targetEntityId) {
+    const references = this.entityReverseIndex.get(targetEntityId);
+    return references ? Array.from(references) : [];
+  }
+  removeEmptyArchetype(archetype) {
+    if (archetype.getEntities().length > 0) {
+      return;
+    }
+    const index = this.archetypes.indexOf(archetype);
+    if (index !== -1) {
+      this.archetypes.splice(index, 1);
+    }
+    const hashKey = this.getComponentTypesHash(archetype.componentTypes);
+    this.archetypeMap.delete(hashKey);
+    for (const componentType of archetype.componentTypes) {
+      const archetypes = this.componentToArchetypes.get(componentType);
+      if (archetypes) {
+        const compIndex = archetypes.indexOf(archetype);
+        if (compIndex !== -1) {
+          archetypes.splice(compIndex, 1);
+          if (archetypes.length === 0) {
+            this.componentToArchetypes.delete(componentType);
+          }
+        }
+      }
+    }
+  }
+  executeComponentLifecycleHooks(entityId, addedComponents, removedComponents) {
+    for (const [componentType, component] of addedComponents) {
+      const hooks = this.componentLifecycleHooks.get(componentType);
+      if (hooks) {
+        for (const hook of hooks) {
+          if (hook.onAdded) {
+            hook.onAdded(entityId, componentType, component);
+          }
+        }
+      }
+      const detailedType = getDetailedIdType(componentType);
+      if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
+        const wildcardHooks = this.wildcardRelationLifecycleHooks.get(detailedType.componentId);
+        if (wildcardHooks) {
+          for (const hook of wildcardHooks) {
+            if (hook.onAdded) {
+              hook.onAdded(entityId, componentType, component);
+            }
+          }
+        }
+      }
+    }
+    for (const componentType of removedComponents) {
+      const hooks = this.componentLifecycleHooks.get(componentType);
+      if (hooks) {
+        for (const hook of hooks) {
+          if (hook.onRemoved) {
+            hook.onRemoved(entityId, componentType);
+          }
+        }
+      }
+      const detailedType = getDetailedIdType(componentType);
+      if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
+        const wildcardHooks = this.wildcardRelationLifecycleHooks.get(detailedType.componentId);
+        if (wildcardHooks) {
+          for (const hook of wildcardHooks) {
+            if (hook.onRemoved) {
+              hook.onRemoved(entityId, componentType);
+            }
+          }
+        }
+      }
+    }
+  }
 }
 export {
   isRelationId,

package/package.json

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

package/types.d.ts

@@ -1,4 +1,17 @@
 import type { EntityId, WildcardRelationId } from "./entity";
+/**
+ * Hook types for component lifecycle events
+ */
+export interface LifecycleHook<T = unknown> {
+    /**
+     * Called when a component is added to an entity
+     */
+    onAdded?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+    /**
+     * Called when a component is removed from an entity
+     */
+    onRemoved?: (entityId: EntityId, componentType: EntityId<T>) => void;
+}
 /**
  * Type helper for component tuples extracted from EntityId array
  */

package/world.d.ts

@@ -1,9 +1,9 @@
 import { Archetype } from "./archetype";
 import { type Command } from "./command-buffer";
-import type { EntityId } from "./entity";
+import type { EntityId, WildcardRelationId } from "./entity";
 import { Query } from "./query";
 import type { QueryFilter } from "./query-filter";
-import type { ComponentTuple } from "./types";
+import type { ComponentTuple, LifecycleHook } from "./types";
 import type { System } from "./system";
 /**
  * World class for ECS architecture
@@ -18,6 +18,21 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     private queries;
     private commandBuffer;
     private componentToArchetypes;
+    /**
+     * Hook storage for component lifecycle events
+     */
+    private componentLifecycleHooks;
+    /**
+     * Hook storage for wildcard relation lifecycle events
+     * Maps base component type to set of wildcard relation hooks
+     */
+    private wildcardRelationLifecycleHooks;
+    /**
+     * Reverse index tracking which entities use each entity as a component type
+     * Maps entity ID to set of {sourceEntityId, componentType} pairs where componentType uses this entity
+     * This includes both relation components and direct usage of entities as component types
+     */
+    private entityReverseIndex;
     constructor();
     /**
      * Generate a hash key for component types array
@@ -51,6 +66,10 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * Check if an entity has a specific component
      */
     hasComponent<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
+    /**
+     * Get wildcard relations from an entity
+     */
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
     /**
      * Get a component from an entity
      */
@@ -63,6 +82,23 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * Unregister a system
      */
     unregisterSystem(system: System<ExtraParams>): void;
+    /**
+     * Register a lifecycle hook for component events
+     */
+    registerComponentLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    /**
+     * Unregister a lifecycle hook for component events
+     */
+    unregisterComponentLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    /**
+     * Register a lifecycle hook for wildcard relation events
+     * The hook will be triggered for any component that matches the wildcard relation pattern
+     */
+    registerWildcardRelationLifecycleHook<T>(baseComponentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    /**
+     * Unregister a lifecycle hook for wildcard relation events
+     */
+    unregisterWildcardRelationLifecycleHook<T>(baseComponentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
      * Update the world (run all systems)
      */
@@ -103,4 +139,32 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * Get or create an archetype for the given component types
      */
     private getOrCreateArchetype;
+    /**
+     * Add a component reference to the reverse index when an entity is used as a component type
+     * @param sourceEntityId The entity that has the component
+     * @param componentType The component type (which may be an entity ID used as component type)
+     * @param targetEntityId The entity being used as component type
+     */
+    private addComponentReference;
+    /**
+     * Remove a component reference from the reverse index
+     * @param sourceEntityId The entity that has the component
+     * @param componentType The component type
+     * @param targetEntityId The entity being used as component type
+     */
+    private removeComponentReference;
+    /**
+     * Get all component references where a target entity is used as a component type
+     * @param targetEntityId The target entity
+     * @returns Array of {sourceEntityId, componentType} pairs
+     */
+    private getComponentReferences;
+    /**
+     * Remove an empty archetype from all internal data structures
+     */
+    private removeEmptyArchetype;
+    /**
+     * Execute component lifecycle hooks for added and removed components
+     */
+    private executeComponentLifecycleHooks;
 }