@codehz/ecs 0.2.4 → 0.3.1

package/README.md

@@ -60,18 +60,22 @@ ECS 支持在组件添加或移除时执行回调函数：
 
 ```typescript
 // 注册组件生命周期钩子
-world.registerLifecycleHook(PositionId, {
-  onAdded: (entityId, componentType, component) => {
+world.hook(PositionId, {
+  on_init: (entityId, componentType, component) => {
+    // 当钩子注册时，为现有实体上的组件调用
+    console.log(`现有组件 ${componentType} 在实体 ${entityId}`);
+  },
+  on_set: (entityId, componentType, component) => {
     console.log(`组件 ${componentType} 被添加到实体 ${entityId}`);
   },
-  onRemoved: (entityId, componentType) => {
+  on_remove: (entityId, componentType, component) => {
     console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
   },
 });
 
 // 你也可以只注册其中一个钩子
-world.registerLifecycleHook(VelocityId, {
-  onRemoved: (entityId, componentType) => {
+world.hook(VelocityId, {
+  on_remove: (entityId, componentType, component) => {
     console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
   },
 });
@@ -104,11 +108,11 @@ const entity = world.new();
 const wildcardPositionRelation = relation(PositionId, "*");
 
 // 注册通配符关系钩子
-world.registerLifecycleHook(wildcardPositionRelation, {
-  onAdded: (entityId, componentType, component) => {
+world.hook(wildcardPositionRelation, {
+  on_set: (entityId, componentType, component) => {
     console.log(`关系组件 ${componentType} 被添加到实体 ${entityId}`);
   },
-  onRemoved: (entityId, componentType) => {
+  on_remove: (entityId, componentType, component) => {
     console.log(`关系组件 ${componentType} 被从实体 ${entityId} 移除`);
   },
 });
@@ -177,8 +181,8 @@ bun run examples/simple/demo.ts
 - `setExclusive(componentId)`: 将组件标记为独占关系
 - `createQuery(componentIds)`: 创建查询
 - `registerSystem(system, dependencies?)`: 注册系统
-- `registerLifecycleHook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
-- `unregisterLifecycleHook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
+- `hook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
+- `unhook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
 - `update(...params)`: 更新世界（参数取决于泛型配置）
 - `sync()`: 应用命令缓冲区
 

package/archetype.d.ts

@@ -102,6 +102,10 @@ export declare class Archetype {
      * Get all entities in this archetype
      */
     getEntities(): EntityId[];
+    /**
+     * Get the mapping of entities to their indices in this archetype
+     */
+    getEntityToIndexMap(): Map<EntityId, number>;
     /**
      * Get component data for all entities of a specific component type
      * @param componentType The component type

package/index.js

@@ -389,6 +389,9 @@ class Archetype {
   getEntities() {
     return this.entities;
   }
+  getEntityToIndexMap() {
+    return this.entityToIndex;
+  }
   getComponentData(componentType) {
     const data = this.componentData.get(componentType);
     if (!data) {
@@ -791,7 +794,7 @@ class World {
   queryCache = new Map;
   systemScheduler = new SystemScheduler;
   commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
-  lifecycleHooks = new Map;
+  hooks = new Map;
   exclusiveComponents = new Set;
   constructor(snapshot) {
     if (snapshot && typeof snapshot === "object") {
@@ -876,6 +879,7 @@ class World {
       const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
       if (sourceArchetype) {
         const currentComponents = new Map;
+        let removedComponent = sourceArchetype.get(sourceEntityId, componentType);
         for (const archetypeComponentType of sourceArchetype.componentTypes) {
           if (archetypeComponentType !== componentType) {
             const componentData = sourceArchetype.get(sourceEntityId, archetypeComponentType);
@@ -890,7 +894,7 @@ class World {
         newArchetype.addEntity(sourceEntityId, currentComponents);
         this.entityToArchetype.set(sourceEntityId, newArchetype);
         this.untrackEntityReference(sourceEntityId, componentType, entityId);
-        this.triggerLifecycleHooks(sourceEntityId, new Map, new Set([componentType]));
+        this.triggerLifecycleHooks(sourceEntityId, new Map, new Map([[componentType, removedComponent]]));
       }
     }
     this.entityReferences.delete(entityId);
@@ -917,7 +921,7 @@ class World {
     }
     this.commandBuffer.set(entityId, componentType, component2);
   }
-  delete(entityId, componentType) {
+  remove(entityId, componentType) {
     if (!this.exists(entityId)) {
       throw new Error(`Entity ${entityId} does not exist`);
     }
@@ -927,7 +931,7 @@ class World {
     }
     this.commandBuffer.delete(entityId, componentType);
   }
-  destroy(entityId) {
+  delete(entityId) {
     this.commandBuffer.destroy(entityId);
   }
   has(entityId, componentType) {
@@ -950,18 +954,29 @@ class World {
   registerSystem(system, additionalDeps = []) {
     this.systemScheduler.addSystem(system, additionalDeps);
   }
-  registerLifecycleHook(componentType, hook) {
-    if (!this.lifecycleHooks.has(componentType)) {
-      this.lifecycleHooks.set(componentType, new Set);
+  hook(componentType, hook) {
+    if (!this.hooks.has(componentType)) {
+      this.hooks.set(componentType, new Set);
+    }
+    this.hooks.get(componentType).add(hook);
+    if (hook.on_init !== undefined) {
+      this.archetypesByComponent.get(componentType)?.forEach((archetype) => {
+        const entities = archetype.getEntityToIndexMap();
+        const componentData = archetype.getComponentData(componentType);
+        for (const [entity, index] of entities) {
+          const data = componentData[index];
+          const value = data === MISSING_COMPONENT ? undefined : data;
+          hook.on_init?.(entity, componentType, value);
+        }
+      });
     }
-    this.lifecycleHooks.get(componentType).add(hook);
   }
-  unregisterLifecycleHook(componentType, hook) {
-    const hooks = this.lifecycleHooks.get(componentType);
+  unhook(componentType, hook) {
+    const hooks = this.hooks.get(componentType);
     if (hooks) {
       hooks.delete(hook);
       if (hooks.size === 0) {
-        this.lifecycleHooks.delete(componentType);
+        this.hooks.delete(componentType);
       }
     }
   }
@@ -1130,9 +1145,13 @@ class World {
       }
     }
     const finalComponentTypes = changeset.getFinalComponentTypes(currentArchetype.componentTypes);
+    const removedCompoents = new Map;
     if (finalComponentTypes) {
       const newArchetype = this.ensureArchetype(finalComponentTypes);
       const currentComponents = currentArchetype.removeEntity(entityId);
+      for (const componentType of changeset.removes) {
+        removedCompoents.set(componentType, currentComponents.get(componentType));
+      }
       newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
       this.entityToArchetype.set(entityId, newArchetype);
     } else {
@@ -1158,7 +1177,7 @@ class World {
         this.trackEntityReference(entityId, componentType, componentType);
       }
     }
-    this.triggerLifecycleHooks(entityId, changeset.adds, changeset.removes);
+    this.triggerLifecycleHooks(entityId, changeset.adds, removedCompoents);
     return changeset;
   }
   ensureArchetype(componentTypes) {
@@ -1226,45 +1245,37 @@ class World {
   }
   triggerLifecycleHooks(entityId, addedComponents, removedComponents) {
     for (const [componentType, component2] of addedComponents) {
-      const directHooks = this.lifecycleHooks.get(componentType);
+      const directHooks = this.hooks.get(componentType);
       if (directHooks) {
         for (const lifecycleHook of directHooks) {
-          if (lifecycleHook.onAdded) {
-            lifecycleHook.onAdded(entityId, componentType, component2);
-          }
+          lifecycleHook.on_set?.(entityId, componentType, component2);
         }
       }
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
         const wildcardRelationId = relation(detailedType.componentId, "*");
-        const wildcardHooks = this.lifecycleHooks.get(wildcardRelationId);
+        const wildcardHooks = this.hooks.get(wildcardRelationId);
         if (wildcardHooks) {
           for (const lifecycleHook of wildcardHooks) {
-            if (lifecycleHook.onAdded) {
-              lifecycleHook.onAdded(entityId, componentType, component2);
-            }
+            lifecycleHook.on_set?.(entityId, componentType, component2);
           }
         }
       }
     }
-    for (const componentType of removedComponents) {
-      const directHooks = this.lifecycleHooks.get(componentType);
+    for (const [componentType, component2] of removedComponents) {
+      const directHooks = this.hooks.get(componentType);
       if (directHooks) {
         for (const lifecycleHook of directHooks) {
-          if (lifecycleHook.onRemoved) {
-            lifecycleHook.onRemoved(entityId, componentType);
-          }
+          lifecycleHook.on_remove?.(entityId, componentType, component2);
         }
       }
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation" || detailedType.type === "component-relation" || detailedType.type === "wildcard-relation") {
         const wildcardRelationId = relation(detailedType.componentId, "*");
-        const wildcardHooks = this.lifecycleHooks.get(wildcardRelationId);
+        const wildcardHooks = this.hooks.get(wildcardRelationId);
         if (wildcardHooks) {
           for (const hook of wildcardHooks) {
-            if (hook.onRemoved) {
-              hook.onRemoved(entityId, componentType);
-            }
+            hook.on_remove?.(entityId, componentType, component2);
           }
         }
       }

package/package.json

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

package/types.d.ts

@@ -6,11 +6,15 @@ export interface LifecycleHook<T = unknown> {
     /**
      * Called when a component is added to an entity
      */
-    onAdded?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+    on_init?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
     /**
-     * Called when a component is removed from an entity
+     * Called when a component is added to an entity
+     */
+    on_set?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+    /**
+     * Called when a component is deleted from an entity
      */
-    onRemoved?: (entityId: EntityId, componentType: EntityId<T>) => void;
+    on_remove?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
 }
 export type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
 export type OptionalEntityId<T> = {

package/world.d.ts

@@ -32,7 +32,7 @@ export declare class World<UpdateParams extends any[] = []> {
     /** Buffers structural changes for deferred execution */
     private commandBuffer;
     /** Stores lifecycle hooks for component and relation events */
-    private lifecycleHooks;
+    private hooks;
     /** Set of component IDs marked as exclusive relations */
     private exclusiveComponents;
     /**
@@ -67,11 +67,11 @@ export declare class World<UpdateParams extends any[] = []> {
     /**
      * Remove a component from an entity (deferred)
      */
-    delete<T>(entityId: EntityId, componentType: EntityId<T>): void;
+    remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
     /**
      * Destroy an entity and remove all its components (deferred)
      */
-    destroy(entityId: EntityId): void;
+    delete(entityId: EntityId): void;
     /**
      * Check if an entity has a specific component
      */
@@ -98,11 +98,11 @@ export declare class World<UpdateParams extends any[] = []> {
     /**
      * Register a lifecycle hook for component or wildcard relation events
      */
-    registerLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    hook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
      * Unregister a lifecycle hook for component or wildcard relation events
      */
-    unregisterLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    unhook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
      * Mark a component as exclusive relation
      * For exclusive relations, an entity can have at most one relation per base component