@codehz/ecs 0.6.10 → 0.6.11

package/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()`: 执行所有延迟命令
 

package/builder.d.mts

@@ -234,6 +234,7 @@ interface LifecycleHookEntry {
   componentTypes: readonly ComponentType<any>[];
   requiredComponents: EntityId<any>[];
   optionalComponents: EntityId<any>[];
+  filter: QueryFilter;
   hook: LifecycleHook<any>;
 }
 //#endregion
@@ -662,12 +663,14 @@ declare 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
@@ -685,9 +688,18 @@ declare 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>): () => void;
+  hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T> | LifecycleCallback<T>, filter?: QueryFilter): () => void;
   /** @deprecated use the unsubscribe function returned by hook() instead */
   unhook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T>): void;
   /** @deprecated use the unsubscribe function returned by hook() instead */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },

package/world.mjs

@@ -1686,12 +1686,14 @@ function triggerMultiComponentHooks(ctx, entityId, addedComponents, removedCompo
 		const anyRequiredAdded = requiredComponents.some((c) => anyComponentMatches(addedComponents, c));
 		const anyOptionalAdded = optionalComponents.some((c) => anyComponentMatches(addedComponents, c));
 		const anyOptionalRemoved = optionalComponents.some((c) => anyComponentMatches(removedComponents, c));
-		if ((anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
+		if (!oldArchetype.matchingMultiHooks.has(entry) || (anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
 	}
-	if (removedComponents.size > 0) for (const entry of oldArchetype.matchingMultiHooks) {
+	for (const entry of oldArchetype.matchingMultiHooks) {
 		const { hook, requiredComponents, componentTypes } = entry;
 		if (!hook.on_remove) continue;
-		if (requiredComponents.some((c) => anyComponentMatches(removedComponents, c)) && entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) && !entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_remove(entityId, ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
+		const lostRequiredMatch = requiredComponents.some((c) => anyComponentMatches(removedComponents, c)) && entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) && !entityHasAllComponents(ctx, entityId, requiredComponents);
+		const exitedMatchingSet = !newArchetype.matchingMultiHooks.has(entry);
+		if (lostRequiredMatch || exitedMatchingSet) hook.on_remove(entityId, ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
 	}
 }
 function entityHasAllComponents(ctx, entityId, requiredComponents) {
@@ -2190,7 +2192,7 @@ var World = class {
 		}
 		return archetype.getOptional(entityId, componentType);
 	}
-	hook(componentTypesOrSingle, hook) {
+	hook(componentTypesOrSingle, hook, filter) {
 		if (typeof hook === "function") if (Array.isArray(componentTypesOrSingle)) {
 			const callback = hook;
 			hook = {
@@ -2217,14 +2219,15 @@ var World = class {
 				componentTypes,
 				requiredComponents,
 				optionalComponents,
+				filter: filter || {},
 				hook
 			};
 			this.hooks.add(entry);
 			for (const archetype of this.archetypes) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
 			const multiHook = hook;
-			if (multiHook.on_init !== void 0) {
-				const matchingArchetypes = this.getMatchingArchetypes(requiredComponents);
-				for (const archetype of matchingArchetypes) for (const entityId of archetype.getEntities()) {
+			if (multiHook.on_init !== void 0) 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);
 				}
@@ -2567,7 +2570,7 @@ var World = class {
 				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
 			}
 			return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
-		});
+		}) && matchesFilter(archetype, entry.filter);
 	}
 	archetypeReferencesEntity(archetype, entityId) {
 		return archetype.componentTypes.some((ct) => ct === entityId || isEntityRelation(ct) && getTargetIdFromRelationId(ct) === entityId);