feat(core): add filter support to multi-component hooks

codehz · codehz · commit c7b334f45777 · 2026-03-02T04:34:45.000+08:00
- Added optional filter parameter to hook API
- Implemented negative component filtering
- Updated hook triggering logic for set/remove
- Enhanced archetype matching with filter support
- Added comprehensive tests for filter behavior
diff --git a/README.md b/README.md
@@ -124,6 +124,29 @@ const unhook = world.hook([PositionId, { optional: VelocityId }], {
 });
 ```
 
+多组件 `hook()` 还支持第三个可选参数 `filter`（与 `createQuery()` 的过滤语义一致），可用于排除带有某些负面组件的实体：
+
+```typescript
+const DisabledId = component<void>();
+
+const unhook = world.hook(
+  [PositionId, VelocityId],
+  {
+    on_set: (entityId, position, velocity) => {
+      // 实体进入匹配集合时触发（包括移除 Disabled 后重新进入）
+      console.log("active", entityId, position, velocity);
+    },
+    on_remove: (entityId, position, velocity) => {
+      // 实体退出匹配集合时触发（包括新增 Disabled 后退出）
+      console.log("inactive", entityId, position, velocity);
+    },
+  },
+  {
+    negativeComponentTypes: [DisabledId],
+  },
+);
+```
+
 ### 通配符关系钩子
 
 ECS 支持通配符关系钩子，可以监听特定组件的所有关系变化：
@@ -226,7 +249,7 @@ bun run examples/simple/demo.ts
 - `delete(entity)`: 销毁实体及其所有组件
 - `query(componentIds)`: 快速查询具有指定组件的实体
 - `createQuery(componentIds)`: 创建可重用的查询对象
-- `hook(componentIds, hook)`: 注册生命周期钩子，返回卸载函数
+- `hook(componentIds, hook, filter?)`: 注册生命周期钩子，返回卸载函数（数组形式支持可选 filter）
 - `serialize()`: 序列化世界状态为快照对象
 - `sync()`: 执行所有延迟命令
 
diff --git a/src/__tests__/world-multi-component-hooks.test.ts b/src/__tests__/world-multi-component-hooks.test.ts
@@ -353,6 +353,124 @@ describe("World - Multi-Component Hooks", () => {
     expect(initCalls[0]!.components).toEqual([42, "hello"]);
   });
 
+  it("should apply negative filter for on_init replay", () => {
+    const world = new World();
+    const A = component<number>();
+    const Disabled = component<void>();
+
+    const activeEntity = world.spawn().with(A, 1).build();
+    const filteredEntity = world.spawn().with(A, 2).with(Disabled).build();
+    world.sync();
+
+    const initCalls: EntityId[] = [];
+    world.hook(
+      [A],
+      {
+        on_init: (entityId) => {
+          initCalls.push(entityId);
+        },
+      },
+      { negativeComponentTypes: [Disabled] },
+    );
+
+    expect(initCalls).toContain(activeEntity);
+    expect(initCalls).not.toContain(filteredEntity);
+    expect(initCalls.length).toBe(1);
+  });
+
+  it("should trigger on_remove when entering negative filter state", () => {
+    const world = new World();
+    const A = component<number>();
+    const Disabled = component<void>();
+    const removeCalls: { entityId: EntityId; value: number }[] = [];
+
+    world.hook(
+      [A],
+      {
+        on_remove: (entityId, value) => {
+          removeCalls.push({ entityId, value });
+        },
+      },
+      { negativeComponentTypes: [Disabled] },
+    );
+
+    const entity = world.spawn().with(A, 42).build();
+    world.sync();
+    expect(removeCalls.length).toBe(0);
+
+    world.set(entity, Disabled);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    expect(removeCalls[0]!.value).toBe(42);
+  });
+
+  it("should trigger on_set when leaving negative filter state", () => {
+    const world = new World();
+    const A = component<number>();
+    const Disabled = component<void>();
+    const setCalls: { entityId: EntityId; value: number }[] = [];
+
+    world.hook(
+      [A],
+      {
+        on_set: (entityId, value) => {
+          setCalls.push({ entityId, value });
+        },
+      },
+      { negativeComponentTypes: [Disabled] },
+    );
+
+    const entity = world.spawn().with(A, 7).with(Disabled).build();
+    world.sync();
+    expect(setCalls.length).toBe(0);
+
+    world.remove(entity, Disabled);
+    world.sync();
+
+    expect(setCalls.length).toBe(1);
+    expect(setCalls[0]!.entityId).toBe(entity);
+    expect(setCalls[0]!.value).toBe(7);
+  });
+
+  it("should suppress normal set events while filtered until re-entering", () => {
+    const world = new World();
+    const A = component<number>();
+    const B = component<string>();
+    const Disabled = component<void>();
+    const setCalls: { entityId: EntityId; components: readonly [number, { value: string } | undefined] }[] = [];
+
+    world.hook(
+      [A, { optional: B }],
+      {
+        on_set: (entityId, ...components) => {
+          setCalls.push({ entityId, components });
+        },
+      },
+      { negativeComponentTypes: [Disabled] },
+    );
+
+    const entity = world.spawn().with(A, 1).with(Disabled).build();
+    world.sync();
+    expect(setCalls.length).toBe(0);
+
+    world.set(entity, B, "blocked");
+    world.sync();
+    expect(setCalls.length).toBe(0);
+
+    world.set(entity, A, 2);
+    world.sync();
+    expect(setCalls.length).toBe(0);
+
+    world.remove(entity, Disabled);
+    world.sync();
+
+    expect(setCalls.length).toBe(1);
+    expect(setCalls[0]!.entityId).toBe(entity);
+    expect(setCalls[0]!.components).toEqual([2, { value: "blocked" }]);
+  });
+
   it("should stop triggering after unhook for multi-component hooks", () => {
     const world = new World();
     const A = component<number>();
diff --git a/src/core/types.ts b/src/core/types.ts
@@ -1,3 +1,4 @@
+import type { QueryFilter } from "../query/filter";
 import type { EntityId, WildcardRelationId } from "./entity";
 
 /**
@@ -84,5 +85,6 @@ export interface LifecycleHookEntry {
   componentTypes: readonly ComponentType<any>[];
   requiredComponents: EntityId<any>[];
   optionalComponents: EntityId<any>[];
+  filter: QueryFilter;
   hook: LifecycleHook<any>;
 }
diff --git a/src/core/world-hooks.ts b/src/core/world-hooks.ts
@@ -153,45 +153,46 @@ function triggerMultiComponentHooks(
   oldArchetype: Archetype,
   newArchetype: Archetype,
 ): void {
-  // Handle on_set: triggers if any required or optional component was added/removed and entity still matches
+  // Handle on_set:
+  // 1. Required/optional components changed while entity still matches
+  // 2. Entity entered the matching set (e.g. removed a negative filter component)
   for (const entry of newArchetype.matchingMultiHooks) {
     const { hook, requiredComponents, optionalComponents, componentTypes } = entry;
     if (!hook.on_set) continue;
 
     const anyRequiredAdded = requiredComponents.some((c) => anyComponentMatches(addedComponents, c));
     const anyOptionalAdded = optionalComponents.some((c) => anyComponentMatches(addedComponents, c));
     const anyOptionalRemoved = optionalComponents.some((c) => anyComponentMatches(removedComponents, c));
+    const enteredMatchingSet = !oldArchetype.matchingMultiHooks.has(entry);
+    const hasRelevantComponentChange = anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved;
+    const shouldTriggerSet =
+      enteredMatchingSet || (hasRelevantComponentChange && entityHasAllComponents(ctx, entityId, requiredComponents));
 
-    if (
-      (anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved) &&
-      entityHasAllComponents(ctx, entityId, requiredComponents)
-    ) {
+    if (shouldTriggerSet) {
       hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
     }
   }
 
-  // Handle on_remove: triggers if any required component was removed and entity no longer matches
-  if (removedComponents.size > 0) {
-    for (const entry of oldArchetype.matchingMultiHooks) {
-      const { hook, requiredComponents, componentTypes } = entry;
-      if (!hook.on_remove) continue;
-
-      const anyRequiredRemoved = requiredComponents.some((c) => anyComponentMatches(removedComponents, c));
-
-      // Only trigger if:
-      // 1. A required component was removed
-      // 2. Entity matched before (had all required components)
-      // 3. Entity no longer matches after removal
-      if (
-        anyRequiredRemoved &&
-        entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) &&
-        !entityHasAllComponents(ctx, entityId, requiredComponents)
-      ) {
-        hook.on_remove(
-          entityId,
-          ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents),
-        );
-      }
+  // Handle on_remove:
+  // 1. Required component removal made the entity stop matching
+  // 2. Entity exited the matching set (e.g. added a negative filter component)
+  for (const entry of oldArchetype.matchingMultiHooks) {
+    const { hook, requiredComponents, componentTypes } = entry;
+    if (!hook.on_remove) continue;
+
+    const anyRequiredRemoved = requiredComponents.some((c) => anyComponentMatches(removedComponents, c));
+    const lostRequiredMatch =
+      anyRequiredRemoved &&
+      entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) &&
+      !entityHasAllComponents(ctx, entityId, requiredComponents);
+    const exitedMatchingSet = !newArchetype.matchingMultiHooks.has(entry);
+    const shouldTriggerRemove = lostRequiredMatch || exitedMatchingSet;
+
+    if (shouldTriggerRemove) {
+      hook.on_remove(
+        entityId,
+        ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents),
+      );
     }
   }
 }
diff --git a/src/core/world.ts b/src/core/world.ts
@@ -1,6 +1,6 @@
 import { ComponentChangeset } from "../commands/changeset";
 import { CommandBuffer, type Command } from "../commands/command-buffer";
-import { serializeQueryFilter, type QueryFilter } from "../query/filter";
+import { matchesFilter, serializeQueryFilter, type QueryFilter } from "../query/filter";
 import { Query } from "../query/query";
 import { getOrCompute } from "../utils/utils";
 import { Archetype, MISSING_COMPONENT } from "./archetype";
@@ -663,12 +663,14 @@ export class World {
    * @overload hook<const T extends readonly ComponentType<any>[]>(
    *   componentTypes: T,
    *   hook: LifecycleHook<T> | LifecycleCallback<T>,
+   *   filter?: QueryFilter,
    * ): () => void
    * Registers a hook for multiple component types.
-   * The hook is triggered when all required components change together.
+   * The hook is triggered when entities enter/exit the matching set.
    *
    * @param componentTypesOrSingle - A single component type or an array of component types
    * @param hook - Either a hook object with on_init/on_set/on_remove handlers, or a callback function
+   * @param filter - Optional filter, only applied to array overload
    * @returns A function that unsubscribes the hook when called
    *
    * @throws {Error} If no required components are specified in array overload
@@ -686,15 +688,26 @@ export class World {
    * const unsubscribe = world.hook([Position], (event, entityId, position) => {
    *   if (event === "init") console.log("Initialized");
    * });
+   *
+   * // With filter
+   * const unsubscribe2 = world.hook(
+   *   [Position, Velocity],
+   *   {
+   *     on_set: (entityId, position, velocity) => console.log(entityId, position, velocity),
+   *   },
+   *   { negativeComponentTypes: [Disabled] },
+   * );
    */
   hook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T> | LegacyLifecycleCallback<T>): () => void;
   hook<const T extends readonly ComponentType<any>[]>(
     componentTypes: T,
     hook: LifecycleHook<T> | LifecycleCallback<T>,
+    filter?: QueryFilter,
   ): () => void;
   hook(
     componentTypesOrSingle: EntityId<any> | readonly ComponentType<any>[],
     hook: LegacyLifecycleHook<any> | LifecycleHook<any> | LegacyLifecycleCallback<any> | LifecycleCallback<any>,
+    filter?: QueryFilter,
   ): () => void {
     // Normalize callback functions to hook objects
     if (typeof hook === "function") {
@@ -735,6 +748,7 @@ export class World {
         componentTypes,
         requiredComponents,
         optionalComponents,
+        filter: filter || {},
         hook: hook as LifecycleHook<any>,
       };
       this.hooks.add(entry);
@@ -748,8 +762,8 @@ export class World {
 
       const multiHook = hook as LifecycleHook<any>;
       if (multiHook.on_init !== undefined) {
-        const matchingArchetypes = this.getMatchingArchetypes(requiredComponents);
-        for (const archetype of matchingArchetypes) {
+        for (const archetype of this.archetypes) {
+          if (!this.archetypeMatchesHook(archetype, entry)) continue;
           for (const entityId of archetype.getEntities()) {
             const components = collectMultiHookComponents(this.createHooksContext(), entityId, componentTypes);
             multiHook.on_init(entityId, ...components);
@@ -1296,14 +1310,16 @@ export class World {
   }
 
   private archetypeMatchesHook(archetype: Archetype, entry: LifecycleHookEntry): boolean {
-    return entry.requiredComponents.every((c: EntityId<any>) => {
-      if (isWildcardRelationId(c)) {
-        if (isDontFragmentWildcard(c)) return true;
-        const componentId = getComponentIdFromRelationId(c);
-        return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
-      }
-      return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
-    });
+    return (
+      entry.requiredComponents.every((c: EntityId<any>) => {
+        if (isWildcardRelationId(c)) {
+          if (isDontFragmentWildcard(c)) return true;
+          const componentId = getComponentIdFromRelationId(c);
+          return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
+        }
+        return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
+      }) && matchesFilter(archetype, entry.filter)
+    );
   }
 
   private archetypeReferencesEntity(archetype: Archetype, entityId: EntityId): boolean {
