@codehz/ecs 0.0.1 → 0.0.3

package/README.md

@@ -4,10 +4,12 @@
 
 ## 特性
 
-- 🚀 高性能：基于原型的组件存储和高效的查询系统
+- 🚀 高性能：基于 Archetype 的组件存储和高效的查询系统
 - 🔧 类型安全：完整的 TypeScript 支持
 - 🏗️ 模块化：清晰的架构，支持自定义系统和组件
 - 📦 轻量级：零依赖，易于集成
+- ⚡ 内存高效：连续内存布局，优化的迭代性能
+- 🎣 生命周期钩子：支持组件和通配符关系的事件监听
 
 ## 安装
 
@@ -21,15 +23,15 @@ bun install
 
 ```typescript
 import { World } from "@codehz/ecs";
-import { createComponentId } from "@codehz/ecs";
+import { component } from "@codehz/ecs";
 
 // 定义组件类型
 type Position = { x: number; y: number };
 type Velocity = { x: number; y: number };
 
 // 定义组件ID
-const PositionId = createComponentId<Position>(1);
-const VelocityId = createComponentId<Velocity>(2);
+const PositionId = component<Position>(1);
+const VelocityId = component<Velocity>(2);
 
 // 创建世界
 const world = new World();
@@ -44,6 +46,7 @@ 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;
@@ -56,20 +59,20 @@ ECS 支持在组件添加或移除时执行回调函数：
 
 ```typescript
 // 注册组件生命周期钩子
-world.registerComponentLifecycleHook(PositionId, {
+world.registerLifecycleHook(PositionId, {
   onAdded: (entityId, componentType, component) => {
     console.log(`组件 ${componentType} 被添加到实体 ${entityId}`);
   },
   onRemoved: (entityId, componentType) => {
     console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
-  }
+  },
 });
 
 // 你也可以只注册其中一个钩子
-world.registerComponentLifecycleHook(VelocityId, {
+world.registerLifecycleHook(VelocityId, {
   onRemoved: (entityId, componentType) => {
     console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
-  }
+  },
 });
 
 // 添加组件时会触发钩子
@@ -77,8 +80,53 @@ world.addComponent(entity, PositionId, { x: 0, y: 0 });
 world.flushCommands(); // 钩子在这里被调用
 ```
 
+### 通配符关系生命周期钩子
+
+ECS 还支持通配符关系生命周期钩子，可以监听特定组件的所有关系变化：
+
+```typescript
+import { World, component, relation } from "@codehz/ecs";
+
+// 定义组件类型
+type Position = { x: number; y: number };
+
+// 定义组件ID
+const PositionId = component<Position>(1);
+
+// 创建世界
+const world = new World();
+
+// 创建实体
+const entity = world.createEntity();
+
+// 创建通配符关系ID，用于监听所有 Position 相关的关系
+const wildcardPositionRelation = relation(PositionId, "*");
+
+// 注册通配符关系钩子
+world.registerLifecycleHook(wildcardPositionRelation, {
+  onAdded: (entityId, componentType, component) => {
+    console.log(`关系组件 ${componentType} 被添加到实体 ${entityId}`);
+  },
+  onRemoved: (entityId, componentType) => {
+    console.log(`关系组件 ${componentType} 被从实体 ${entityId} 移除`);
+  },
+});
+
+// 创建实体间的关系
+const entity2 = world.createEntity();
+const positionRelation = relation(PositionId, entity2);
+world.addComponent(entity, positionRelation, { x: 10, y: 20 });
+world.flushCommands(); // 通配符钩子会被触发
+```
+
 ### 运行示例
 
+```bash
+bun run demo
+```
+
+或者直接运行：
+
 ```bash
 bun run examples/simple/demo.ts
 ```
@@ -92,18 +140,20 @@ bun run examples/simple/demo.ts
 - `removeComponent(entity, componentId)`: 从实体移除组件
 - `createQuery(componentIds)`: 创建查询
 - `registerSystem(system)`: 注册系统
-- `registerComponentLifecycleHook(componentId, hook)`: 注册组件生命周期钩子
-- `unregisterComponentLifecycleHook(componentId, hook)`: 注销组件生命周期钩子
+- `registerLifecycleHook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
+- `unregisterLifecycleHook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
 - `update(deltaTime)`: 更新世界
 - `flushCommands()`: 应用命令缓冲区
 
 ### Entity
 
-- `createComponentId<T>(id)`: 创建类型安全的组件ID
+- `component<T>(id)`: 分配类型安全的组件ID（上限：1022个）
 
 ### Query
 
 - `forEach(componentIds, callback)`: 遍历匹配的实体
+- `getEntities()`: 获取所有匹配实体的ID列表
+- `getEntitiesWithComponents(componentIds)`: 获取实体及其组件数据
 
 ### System
 
@@ -117,6 +167,13 @@ class MySystem implements System {
 }
 ```
 
+## 性能特点
+
+- **Archetype 系统**：实体按组件组合分组，实现连续内存访问
+- **缓存查询**：查询结果自动缓存，减少重复计算
+- **命令缓冲区**：延迟执行组件添加/移除，提高批处理效率
+- **类型安全**：编译时类型检查，无运行时开销
+
 ## 开发
 
 ### 运行测试
@@ -135,20 +192,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/entity.d.ts

@@ -1,11 +1,11 @@
 /**
- * Brand for EntityId to create nominal typing with component type information
+ * Unique symbol brand for associating component type information with EntityId
  */
-declare const __entityIdBrand: unique symbol;
+declare const __componentTypeMarker: unique symbol;
 /**
- * Brand for wildcard relation IDs
+ * Unique symbol brand for tagging the kind of EntityId (e.g., 'component', 'entity-relation')
  */
-declare const __wildcardRelationBrand: unique symbol;
+declare const __entityIdTypeTag: unique symbol;
 /**
  * Entity ID type for ECS architecture
  * Based on 52-bit integers within safe integer range
@@ -13,12 +13,15 @@ declare const __wildcardRelationBrand: unique symbol;
  * - Entity IDs: 1024+
  * - Relation IDs: negative numbers encoding component and entity associations
  */
-export type EntityId<T = void> = number & {
-    readonly [__entityIdBrand]: T;
-};
-export type WildcardRelationId<T = void> = EntityId<T> & {
-    readonly [__wildcardRelationBrand]: true;
+export type EntityId<T = void, U = unknown> = number & {
+    readonly [__componentTypeMarker]: T;
+    readonly [__entityIdTypeTag]: U;
 };
+export type ComponentId<T = void> = EntityId<T, "component">;
+export type EntityRelationId<T = void> = EntityId<T, "entity-relation">;
+export type ComponentRelationId<T = void> = EntityId<T, "component-relation">;
+export type WildcardRelationId<T = void> = EntityId<T, "wildcard-relation">;
+export type RelationId<T = void> = EntityRelationId<T> | ComponentRelationId<T> | WildcardRelationId<T>;
 /**
  * Constants for ID ranges
  */
@@ -33,8 +36,9 @@ export declare const WILDCARD_TARGET_ID = 0;
 /**
  * Create a component ID
  * @param id Component identifier (1-1023)
+ * @see component
  */
-export declare function createComponentId<T = void>(id: number): EntityId<T>;
+export declare function createComponentId<T = void>(id: number): ComponentId<T>;
 /**
  * Create an entity ID
  * @param id Entity identifier (starting from 1024)
@@ -43,33 +47,37 @@ export declare function createEntityId(id: number): EntityId;
 /**
  * Type for relation ID based on component and target types
  */
-type RelationIdType<T, U> = U extends void ? EntityId<T> : T extends void ? EntityId<U> : EntityId<never>;
+type RelationIdType<T, R> = R extends ComponentId<infer U> ? U extends void ? ComponentRelationId<T> : ComponentRelationId<T & U> : R extends EntityId<any> ? EntityRelationId<T> : never;
 /**
  * Create a relation ID by associating a component with another ID (entity or component)
  * @param componentId The component ID (0-1023)
  * @param targetId The target ID (entity, component, or '*' for wildcard)
  */
-export declare function createRelationId<T>(componentId: EntityId<T>, targetId: "*"): WildcardRelationId<T>;
-export declare function createRelationId<T, U>(componentId: EntityId<T>, targetId: EntityId<U>): RelationIdType<T, U>;
+export declare function relation<T>(componentId: ComponentId<T>, targetId: "*"): WildcardRelationId<T>;
+export declare function relation<T, R extends EntityId<any>>(componentId: ComponentId<T>, targetId: R): RelationIdType<T, R>;
 /**
  * Check if an ID is a component ID
  */
-export declare function isComponentId(id: EntityId<any>): boolean;
+export declare function isComponentId<T>(id: EntityId<T>): id is ComponentId<T>;
 /**
  * Check if an ID is an entity ID
  */
-export declare function isEntityId(id: EntityId<any>): boolean;
+export declare function isEntityId<T>(id: EntityId<T>): id is EntityId<T>;
 /**
  * Check if an ID is a relation ID
  */
-export declare function isRelationId(id: EntityId): boolean;
+export declare function isRelationId<T>(id: EntityId<T>): id is RelationId<T>;
+/**
+ * Check if an ID is a wildcard relation id
+ */
+export declare function isWildcardRelationId<T>(id: EntityId<T>): id is WildcardRelationId<T>;
 /**
  * Decode a relation ID into component and target IDs
  * @param relationId The relation ID (must be negative)
  * @returns Object with componentId, targetId, and relation type
  */
-export declare function decodeRelationId(relationId: EntityId<any>): {
-    componentId: EntityId<any>;
+export declare function decodeRelationId(relationId: RelationId<any>): {
+    componentId: ComponentId<any>;
     targetId: EntityId<any>;
     type: "entity" | "component" | "wildcard";
 };
@@ -83,9 +91,13 @@ export declare function getIdType(id: EntityId<any>): "component" | "entity" | "
  * @returns Detailed type information including relation subtypes
  */
 export declare function getDetailedIdType(id: EntityId<any>): {
-    type: "component" | "entity" | "entity-relation" | "component-relation" | "wildcard-relation" | "invalid";
-    componentId?: EntityId<any>;
-    targetId?: EntityId<any>;
+    type: "component" | "entity" | "invalid";
+    componentId?: never;
+    targetId?: never;
+} | {
+    type: "entity-relation" | "component-relation" | "wildcard-relation";
+    componentId: ComponentId<any>;
+    targetId: EntityId<any>;
 };
 /**
  * Inspect an EntityId and return a human-readable string representation
@@ -122,13 +134,13 @@ export declare class EntityIdManager {
  * Component ID Manager for automatic allocation
  * Components are typically registered once and not recycled
  */
-export declare class ComponentIdManager {
+export declare class ComponentIdAllocator {
     private nextId;
     /**
      * Allocate a new component ID
      * Increments counter sequentially from 1
      */
-    allocate<T = void>(): EntityId<T>;
+    allocate<T = void>(): ComponentId<T>;
     /**
      * Get the next ID that would be allocated (for debugging)
      */
@@ -138,4 +150,8 @@ export declare class ComponentIdManager {
      */
     hasAvailableIds(): boolean;
 }
+/**
+ * Allocate a new component ID from the global allocator
+ */
+export declare function component<T>(): ComponentId<T>;
 export {};

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

@@ -16,7 +16,7 @@ function createEntityId(id) {
   }
   return id;
 }
-function createRelationId(componentId, targetId) {
+function relation(componentId, targetId) {
   if (!isComponentId(componentId)) {
     throw new Error("First argument must be a valid component ID");
   }
@@ -40,6 +40,14 @@ function isEntityId(id) {
 function isRelationId(id) {
   return id < 0;
 }
+function isWildcardRelationId(id) {
+  if (!isRelationId(id)) {
+    return false;
+  }
+  const absId = -id;
+  const targetId = absId % RELATION_SHIFT;
+  return targetId === WILDCARD_TARGET_ID;
+}
 function decodeRelationId(relationId) {
   if (!isRelationId(relationId)) {
     throw new Error("ID is not a relation ID");
@@ -178,7 +186,7 @@ class EntityIdManager {
   }
 }
 
-class ComponentIdManager {
+class ComponentIdAllocator {
   nextId = 1;
   allocate() {
     if (this.nextId > COMPONENT_ID_MAX) {
@@ -195,6 +203,10 @@ class ComponentIdManager {
     return this.nextId <= COMPONENT_ID_MAX;
   }
 }
+var globalComponentIdAllocator = new ComponentIdAllocator;
+function component() {
+  return globalComponentIdAllocator.allocate();
+}
 // src/utils.ts
 function getOrComputeCache(cache, key, compute) {
   let value = cache.get(key);
@@ -275,9 +287,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 (isWildcardRelationId(componentType)) {
+      const decoded = decodeRelationId(componentType);
+      const componentId = decoded.componentId;
+      const relations = [];
+      for (const relType of this.componentTypes) {
+        const relDetailed = getDetailedIdType(relType);
+        if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) {
+          const dataArray = this.componentData.get(relType);
+          if (dataArray && dataArray[index] !== undefined) {
+            relations.push([relDetailed.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);
@@ -307,15 +339,14 @@ class Archetype {
     const cacheKey = componentTypes.map((id) => id.toString()).join(",");
     const componentDataSources = getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
       return componentTypes.map((compType) => {
-        if (getIdType(compType) === "wildcard-relation") {
-          const decoded = decodeRelationId(compType);
-          const componentId = decoded.componentId;
+        const detailedType = getDetailedIdType(compType);
+        if (detailedType.type === "wildcard-relation") {
+          const componentId = detailedType.componentId;
           const matchingRelations = this.componentTypes.filter((ct) => {
-            const ctType = getIdType(ct);
-            if (ctType !== "entity-relation" && ctType !== "component-relation")
+            const detailedCt = getDetailedIdType(ct);
+            if (detailedCt.type !== "entity-relation" && detailedCt.type !== "component-relation")
               return false;
-            const decodedCt = decodeRelationId(ct);
-            return decodedCt.componentId === componentId;
+            return detailedCt.componentId === componentId;
           });
           return matchingRelations;
         } else {
@@ -364,8 +395,8 @@ class CommandBuffer {
   constructor(executeEntityCommands) {
     this.executeEntityCommands = executeEntityCommands;
   }
-  addComponent(entityId, componentType, component) {
-    this.commands.push({ type: "addComponent", entityId, componentType, component });
+  addComponent(entityId, componentType, component2) {
+    this.commands.push({ type: "addComponent", entityId, componentType, component: component2 });
   }
   removeComponent(entityId, componentType) {
     this.commands.push({ type: "removeComponent", entityId, componentType });
@@ -521,8 +552,7 @@ class World {
   queries = [];
   commandBuffer;
   componentToArchetypes = new Map;
-  componentLifecycleHooks = new Map;
-  wildcardRelationLifecycleHooks = new Map;
+  lifecycleHooks = new Map;
   entityReverseIndex = new Map;
   constructor() {
     this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
@@ -578,16 +608,27 @@ class World {
   hasEntity(entityId) {
     return this.entityToArchetype.has(entityId);
   }
-  addComponent(entityId, componentType, component) {
+  addComponent(entityId, componentType, component2) {
     if (!this.hasEntity(entityId)) {
       throw new Error(`Entity ${entityId} does not exist`);
     }
-    this.commandBuffer.addComponent(entityId, componentType, component);
+    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, component2);
   }
   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) {
@@ -599,7 +640,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);
@@ -610,33 +658,18 @@ class World {
       this.systems.splice(index, 1);
     }
   }
-  registerComponentLifecycleHook(componentType, hook) {
-    if (!this.componentLifecycleHooks.has(componentType)) {
-      this.componentLifecycleHooks.set(componentType, new Set);
+  registerLifecycleHook(componentType, hook) {
+    if (!this.lifecycleHooks.has(componentType)) {
+      this.lifecycleHooks.set(componentType, new Set);
     }
-    this.componentLifecycleHooks.get(componentType).add(hook);
+    this.lifecycleHooks.get(componentType).add(hook);
   }
-  unregisterComponentLifecycleHook(componentType, hook) {
-    const hooks = this.componentLifecycleHooks.get(componentType);
+  unregisterLifecycleHook(componentType, hook) {
+    const hooks = this.lifecycleHooks.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);
+        this.lifecycleHooks.delete(componentType);
       }
     }
   }
@@ -758,8 +791,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;
       }
@@ -768,8 +815,8 @@ class World {
     for (const componentType of removes) {
       finalComponents.delete(componentType);
     }
-    for (const [componentType, component] of adds) {
-      finalComponents.set(componentType, component);
+    for (const [componentType, component2] of adds) {
+      finalComponents.set(componentType, component2);
     }
     const finalComponentTypes = Array.from(finalComponents.keys()).sort((a, b) => a - b);
     const currentComponentTypes = currentArchetype.componentTypes.sort((a, b) => a - b);
@@ -780,8 +827,8 @@ class World {
       newArchetype.addEntity(entityId, finalComponents);
       this.entityToArchetype.set(entityId, newArchetype);
     } else {
-      for (const [componentType, component] of adds) {
-        currentArchetype.setComponent(entityId, componentType, component);
+      for (const [componentType, component2] of adds) {
+        currentArchetype.setComponent(entityId, componentType, component2);
       }
     }
     for (const componentType of removes) {
@@ -793,7 +840,7 @@ class World {
         this.removeComponentReference(entityId, componentType, componentType);
       }
     }
-    for (const [componentType, component] of adds) {
+    for (const [componentType, component2] of adds) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
@@ -868,31 +915,32 @@ class World {
     }
   }
   executeComponentLifecycleHooks(entityId, addedComponents, removedComponents) {
-    for (const [componentType, component] of addedComponents) {
-      const hooks = this.componentLifecycleHooks.get(componentType);
-      if (hooks) {
-        for (const hook of hooks) {
+    for (const [componentType, component2] of addedComponents) {
+      const directHooks = this.lifecycleHooks.get(componentType);
+      if (directHooks) {
+        for (const hook of directHooks) {
           if (hook.onAdded) {
-            hook.onAdded(entityId, componentType, component);
+            hook.onAdded(entityId, componentType, component2);
           }
         }
       }
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
-        const wildcardHooks = this.wildcardRelationLifecycleHooks.get(detailedType.componentId);
+        const wildcardRelationId = relation(detailedType.componentId, "*");
+        const wildcardHooks = this.lifecycleHooks.get(wildcardRelationId);
         if (wildcardHooks) {
           for (const hook of wildcardHooks) {
             if (hook.onAdded) {
-              hook.onAdded(entityId, componentType, component);
+              hook.onAdded(entityId, componentType, component2);
             }
           }
         }
       }
     }
     for (const componentType of removedComponents) {
-      const hooks = this.componentLifecycleHooks.get(componentType);
-      if (hooks) {
-        for (const hook of hooks) {
+      const directHooks = this.lifecycleHooks.get(componentType);
+      if (directHooks) {
+        for (const hook of directHooks) {
           if (hook.onRemoved) {
             hook.onRemoved(entityId, componentType);
           }
@@ -900,7 +948,8 @@ class World {
       }
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
-        const wildcardHooks = this.wildcardRelationLifecycleHooks.get(detailedType.componentId);
+        const wildcardRelationId = relation(detailedType.componentId, "*");
+        const wildcardHooks = this.lifecycleHooks.get(wildcardRelationId);
         if (wildcardHooks) {
           for (const hook of wildcardHooks) {
             if (hook.onRemoved) {
@@ -913,6 +962,8 @@ class World {
   }
 }
 export {
+  relation,
+  isWildcardRelationId,
   isRelationId,
   isEntityId,
   isComponentId,
@@ -920,9 +971,9 @@ export {
   getIdType,
   getDetailedIdType,
   decodeRelationId,
-  createRelationId,
   createEntityId,
   createComponentId,
+  component,
   World,
   WILDCARD_TARGET_ID,
   RELATION_SHIFT,
@@ -930,7 +981,7 @@ export {
   INVALID_COMPONENT_ID,
   EntityIdManager,
   ENTITY_ID_START,
-  ComponentIdManager,
+  ComponentIdAllocator,
   COMPONENT_ID_MAX,
   Archetype
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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,37 +1,10 @@
 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 { System } from "./system";
-/**
- * Hook types for component lifecycle events
- */
-export interface ComponentLifecycleHook<T> {
-    /**
-     * 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;
-}
-/**
- * Hook types for wildcard relation lifecycle events
- * These hooks are triggered for any component that matches a wildcard relation pattern
- */
-export interface WildcardRelationLifecycleHook<T = unknown> {
-    /**
-     * Called when any component matching the wildcard relation pattern is added to an entity
-     */
-    onAdded?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
-    /**
-     * Called when any component matching the wildcard relation pattern is removed from an entity
-     */
-    onRemoved?: (entityId: EntityId, componentType: EntityId<T>) => void;
-}
+import type { ComponentTuple, LifecycleHook } from "./types";
 /**
  * World class for ECS architecture
  * Manages entities, components, and systems
@@ -46,14 +19,9 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     private commandBuffer;
     private componentToArchetypes;
     /**
-     * Hook storage for component lifecycle events
+     * Hook storage for component and wildcard relation lifecycle events
      */
-    private componentLifecycleHooks;
-    /**
-     * Hook storage for wildcard relation lifecycle events
-     * Maps base component type to set of wildcard relation hooks
-     */
-    private wildcardRelationLifecycleHooks;
+    private lifecycleHooks;
     /**
      * 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
@@ -93,6 +61,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
      */
@@ -106,22 +78,13 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      */
     unregisterSystem(system: System<ExtraParams>): void;
     /**
-     * Register a lifecycle hook for component events
-     */
-    registerComponentLifecycleHook<T>(componentType: EntityId<T>, hook: ComponentLifecycleHook<T>): void;
-    /**
-     * Unregister a lifecycle hook for component events
-     */
-    unregisterComponentLifecycleHook<T>(componentType: EntityId<T>, hook: ComponentLifecycleHook<T>): void;
-    /**
-     * Register a lifecycle hook for wildcard relation events
-     * The hook will be triggered for any component that matches the wildcard relation pattern
+     * Register a lifecycle hook for component or wildcard relation events
      */
-    registerWildcardRelationLifecycleHook<T>(baseComponentType: EntityId<T>, hook: WildcardRelationLifecycleHook<T>): void;
+    registerLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
-     * Unregister a lifecycle hook for wildcard relation events
+     * Unregister a lifecycle hook for component or wildcard relation events
      */
-    unregisterWildcardRelationLifecycleHook<T>(baseComponentType: EntityId<T>, hook: WildcardRelationLifecycleHook<T>): void;
+    unregisterLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
      * Update the world (run all systems)
      */