feat(world): add wildcard relation lifecycle hooks support

- Introduced WildcardRelationLifecycleHook interface for handling lifecycle events of components matching wildcard relations.
- Implemented methods to register and unregister these hooks in the World class.
- Updated component addition and removal logic to trigger the appropriate hooks when components are added or removed.
- Added tests to verify the correct triggering of hooks for matching and non-matching components.

Author: codehz

src/world.test.ts

@@ -494,4 +494,70 @@ describe("World", () => {
       expect(removedCalled).toBe(true);
     });
   });
+
+  describe("Wildcard Relation Hooks", () => {
+    it("should trigger wildcard relation hooks for matching relation components", () => {
+      const world = new World();
+      const positionComponent = createComponentId<{ x: number; y: number }>(1);
+      const entity1 = world.createEntity();
+      const entity2 = world.createEntity();
+
+      // Create a relation component (positionComponent -> entity2)
+      const relationId = createRelationId(positionComponent, entity2);
+
+      let addedCalled = false;
+      let removedCalled = false;
+      let addedComponentType: EntityId<{ x: number; y: number }> | undefined;
+      let removedComponentType: EntityId<{ x: number; y: number }> | undefined;
+
+      // Register a wildcard relation hook for positionComponent
+      world.registerWildcardRelationLifecycleHook(positionComponent, {
+        onAdded: (entityId, componentType, component) => {
+          addedCalled = true;
+          addedComponentType = componentType;
+        },
+        onRemoved: (entityId, componentType) => {
+          removedCalled = true;
+          removedComponentType = componentType;
+        },
+      });
+
+      // Add the relation component
+      world.addComponent(entity1, relationId, { x: 10, y: 20 });
+      world.flushCommands();
+
+      expect(addedCalled).toBe(true);
+      expect(addedComponentType).toBe(relationId);
+
+      // Remove the relation component
+      world.removeComponent(entity1, relationId);
+      world.flushCommands();
+
+      expect(removedCalled).toBe(true);
+      expect(removedComponentType).toBe(relationId);
+    });
+
+    it("should not trigger wildcard relation hooks for non-matching components", () => {
+      const world = new World();
+      const positionComponent = createComponentId<{ x: number; y: number }>(1);
+      const velocityComponent = createComponentId<{ vx: number; vy: number }>(2);
+      const entity1 = world.createEntity();
+      const entity2 = world.createEntity();
+
+      let hookCalled = false;
+
+      // Register a wildcard relation hook for positionComponent
+      world.registerWildcardRelationLifecycleHook(positionComponent, {
+        onAdded: () => {
+          hookCalled = true;
+        },
+      });
+
+      // Add a velocity component (not a position relation)
+      world.addComponent(entity1, velocityComponent, { vx: 1, vy: 2 });
+      world.flushCommands();
+
+      expect(hookCalled).toBe(false);
+    });
+  });
 });

src/world.ts

@@ -22,6 +22,21 @@ export interface ComponentLifecycleHook<T> {
   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;
+}
+
 /**
  * World class for ECS architecture
  * Manages entities, components, and systems
@@ -41,6 +56,12 @@ export class World<ExtraParams extends any[] = [deltaTime: number]> {
    */
   private componentLifecycleHooks = new Map<EntityId<any>, Set<ComponentLifecycleHook<any>>>();
 
+  /**
+   * Hook storage for wildcard relation lifecycle events
+   * Maps base component type to set of wildcard relation hooks
+   */
+  private wildcardRelationLifecycleHooks = new Map<EntityId<any>, Set<WildcardRelationLifecycleHook>>();
+
   /**
    * 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
@@ -219,6 +240,30 @@ export class World<ExtraParams extends any[] = [deltaTime: number]> {
     }
   }
 
+  /**
+   * 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: WildcardRelationLifecycleHook<T>): void {
+    if (!this.wildcardRelationLifecycleHooks.has(baseComponentType)) {
+      this.wildcardRelationLifecycleHooks.set(baseComponentType, new Set());
+    }
+    this.wildcardRelationLifecycleHooks.get(baseComponentType)!.add(hook as WildcardRelationLifecycleHook<any>);
+  }
+
+  /**
+   * Unregister a lifecycle hook for wildcard relation events
+   */
+  unregisterWildcardRelationLifecycleHook<T>(baseComponentType: EntityId<T>, hook: WildcardRelationLifecycleHook<T>): void {
+    const hooks = this.wildcardRelationLifecycleHooks.get(baseComponentType);
+    if (hooks) {
+      hooks.delete(hook as WildcardRelationLifecycleHook<any>);
+      if (hooks.size === 0) {
+        this.wildcardRelationLifecycleHooks.delete(baseComponentType);
+      }
+    }
+  }
+
   /**
    * Update the world (run all systems)
    */
@@ -616,6 +661,19 @@ export class World<ExtraParams extends any[] = [deltaTime: number]> {
           }
         }
       }
+
+      // Trigger wildcard relation hooks for added components
+      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 as any).onAdded(entityId, componentType, component);
+            }
+          }
+        }
+      }
     }
 
     // Trigger component removed hooks
@@ -628,6 +686,19 @@ export class World<ExtraParams extends any[] = [deltaTime: number]> {
           }
         }
       }
+
+      // Trigger wildcard relation hooks for removed components
+      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 as any).onRemoved(entityId, componentType);
+            }
+          }
+        }
+      }
     }
   }
 }