@codehz/ecs 0.6.9 → 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

@@ -64,10 +64,11 @@ declare function decodeRelationId(relationId: RelationId<any>): {
 };
 //#endregion
 //#region src/core/component-registry.d.ts
+type ComponentMerge<T = any> = (prev: T, next: T) => T;
 /**
  * Component options that define intrinsic properties
  */
-interface ComponentOptions {
+interface ComponentOptions<T = any> {
   /**
    * Optional name for the component (for serialization/debugging)
    */
@@ -93,6 +94,10 @@ interface ComponentOptions {
    * Inspired by Flecs' DontFragment trait.
    */
   dontFragment?: boolean;
+  /**
+   * Custom merge behavior for repeated set() of the same componentType in a single sync batch.
+   */
+  merge?: ComponentMerge<T>;
 }
 /**
  * Allocate a new component ID from the global allocator.
@@ -108,7 +113,7 @@ interface ComponentOptions {
  * // With name and options
  * const ChildOf = component({ name: "ChildOf", exclusive: true });
  */
-declare function component<T = void>(nameOrOptions?: string | ComponentOptions): ComponentId<T>;
+declare function component<T = void>(nameOrOptions?: string | ComponentOptions<T>): ComponentId<T>;
 /**
  * Get a component ID by its registered name
  * @param name The component name
@@ -229,6 +234,7 @@ interface LifecycleHookEntry {
   componentTypes: readonly ComponentType<any>[];
   requiredComponents: EntityId<any>[];
   optionalComponents: EntityId<any>[];
+  filter: QueryFilter;
   hook: LifecycleHook<any>;
 }
 //#endregion
@@ -286,6 +292,7 @@ declare class Archetype {
   addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
   private addDontFragmentRelations;
   getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+  getEntityDontFragmentRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   dump(): Array<{
     entity: EntityId;
     components: Map<EntityId<any>, any>;
@@ -457,9 +464,14 @@ declare class World {
   private relationEntityIdsByTarget;
   private queries;
   private queryCache;
-  private commandBuffer;
   private legacyHooks;
   private hooks;
+  private commandBuffer;
+  private readonly _changeset;
+  /** Cached command processor context to avoid per-entity object allocation */
+  private readonly _commandCtx;
+  /** Cached hooks context to avoid per-entity object allocation */
+  private readonly _hooksCtx;
   constructor(snapshot?: SerializedWorld);
   private deserializeSnapshot;
   private createArchetypeSignature;
@@ -495,6 +507,12 @@ declare class World {
    * }
    */
   exists(entityId: EntityId): boolean;
+  private assertEntityExists;
+  private assertComponentTypeValid;
+  private assertSetComponentTypeValid;
+  private resolveSetOperation;
+  private resolveRemoveOperation;
+  private getComponentEntityWildcardRelations;
   /**
    * Adds or updates a component on an entity (or marks void component as present).
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -645,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
@@ -668,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.9",
+  "version": "0.6.11",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },