@codehz/ecs 0.5.5 → 0.6.1

package/README.md

@@ -55,42 +55,7 @@ query.forEach([PositionId, VelocityId], (entity, position, velocity) => {
 
 ### 组件生命周期钩子
 
-ECS 支持在组件添加或移除时执行回调函数。钩子回调函数的参数如下：
-
-- `entityId`: 实体的 ID (number)
-- `componentType`: 组件类型 ID (EntityId)
-- `component`: 组件数据值 (T)
-
-```typescript
-// 注册组件生命周期钩子
-world.hook(PositionId, {
-  on_init: (entityId, componentType, component) => {
-    // 当钩子注册时，为现有实体上的组件调用
-    console.log(`现有组件 ${componentType} 在实体 ${entityId}`);
-  },
-  on_set: (entityId, componentType, component) => {
-    console.log(`组件 ${componentType} 被添加到实体 ${entityId}`);
-  },
-  on_remove: (entityId, componentType, component) => {
-    console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
-  },
-});
-
-// 你也可以只注册其中一个钩子
-world.hook(VelocityId, {
-  on_remove: (entityId, componentType, component) => {
-    console.log(`组件 ${componentType} 被从实体 ${entityId} 移除`);
-  },
-});
-
-// 添加组件时会触发钩子
-world.set(entity, PositionId, { x: 0, y: 0 });
-world.sync(); // 钩子在这里被调用
-```
-
-### 多组件生命周期钩子
-
-ECS 还支持多组件生命周期钩子，可以监听多个组件同时存在于实体时的事件。只有当所有必需组件都存在时才会触发回调。
+ECS 支持监听组件的生命周期事件。可以监听单个组件或多个组件同时存在于实体时的事件。
 
 ```typescript
 // 定义组件类型
@@ -101,22 +66,20 @@ type Velocity = { x: number; y: number };
 const PositionId = component<Position>();
 const VelocityId = component<Velocity>();
 
-// 注册多组件生命周期钩子
-world.hook([PositionId, VelocityId], {
-  on_init: (entityId, componentTypes, components) => {
+// 注册生命周期钩子，返回卸载函数
+const unhook = world.hook([PositionId, VelocityId], {
+  on_init: (entityId, position, velocity) => {
     // 当钩子注册时，为已同时拥有 Position 和 Velocity 组件的实体调用
     console.log(`实体 ${entityId} 同时拥有 Position 和 Velocity 组件`);
   },
-  on_set: (entityId, componentTypes, components) => {
+  on_set: (entityId, position, velocity) => {
     // 当实体同时拥有 Position 和 Velocity 组件时调用
-    const [position, velocity] = components;
     console.log(
       `实体 ${entityId} 现在同时拥有 Position (${position.x}, ${position.y}) 和 Velocity (${velocity.x}, ${velocity.y})`,
     );
   },
-  on_remove: (entityId, componentTypes, components) => {
+  on_remove: (entityId, position, velocity) => {
     // 当实体失去 Position 或 Velocity 组件之一时调用（如果之前同时拥有两者）
-    const [position, velocity] = components; // 移除前的组件值快照
     console.log(`实体 ${entityId} 失去了 Position 或 Velocity 组件`);
   },
 });
@@ -125,17 +88,33 @@ world.hook([PositionId, VelocityId], {
 const entity = world.new();
 world.set(entity, PositionId, { x: 0, y: 0 });
 world.set(entity, VelocityId, { x: 1, y: 0.5 });
-world.sync(); // 多组件钩子在这里被调用
+world.sync(); // 钩子在这里被调用
+
+// 不再需要时，调用卸载函数移除钩子
+unhook();
+```
+
+`hook()` 也支持只监听单个组件：
+
+```typescript
+// 监听单个组件
+const unhook = world.hook([PositionId], {
+  on_set: (entityId, position) => {
+    console.log(`组件 Position 被添加到实体 ${entityId}`);
+  },
+  on_remove: (entityId, position) => {
+    console.log(`组件 Position 被从实体 ${entityId} 移除`);
+  },
+});
 ```
 
 还可以使用可选组件，这样即使某些组件不存在也会触发钩子：
 
 ```typescript
-// 注册包含可选组件的多组件生命周期钩子
-world.hook([PositionId, { optional: VelocityId }], {
-  on_set: (entityId, componentTypes, components) => {
+// 注册包含可选组件的生命周期钩子
+const unhook = world.hook([PositionId, { optional: VelocityId }], {
+  on_set: (entityId, position, velocity) => {
     // 当实体拥有 Position 组件时调用，Velocity 组件可选
-    const [position, velocity] = components;
     if (velocity !== undefined) {
       console.log(`实体 ${entityId} 拥有 Position 和 Velocity 组件`);
     } else {
@@ -145,9 +124,9 @@ world.hook([PositionId, { optional: VelocityId }], {
 });
 ```
 
-### 通配符关系生命周期钩子
+### 通配符关系钩子
 
-ECS 还支持通配符关系生命周期钩子，可以监听特定组件的所有关系变化：
+ECS 支持通配符关系钩子，可以监听特定组件的所有关系变化：
 
 ```typescript
 import { World, component, relation } from "@codehz/ecs";
@@ -167,13 +146,16 @@ const entity = world.new();
 // 创建通配符关系ID，用于监听所有 Position 相关的关系
 const wildcardPositionRelation = relation(PositionId, "*");
 
-// 注册通配符关系钩子
-world.hook(wildcardPositionRelation, {
-  on_set: (entityId, componentType, component) => {
-    console.log(`关系组件 ${componentType} 被添加到实体 ${entityId}`);
+// 注册通配符关系钩子，返回卸载函数
+const unhook = world.hook([wildcardPositionRelation], {
+  on_set: (entityId, relations) => {
+    console.log(`实体 ${entityId} 添加了 Position 关系`);
+    for (const [targetId, position] of relations) {
+      console.log(`  -> 目标实体 ${targetId}:`, position);
+    }
   },
-  on_remove: (entityId, componentType, component) => {
-    console.log(`关系组件 ${componentType} 被从实体 ${entityId} 移除`);
+  on_remove: (entityId, relations) => {
+    console.log(`实体 ${entityId} 移除了 Position 关系`);
   },
 });
 
@@ -182,6 +164,9 @@ const entity2 = world.new();
 const positionRelation = relation(PositionId, entity2);
 world.set(entity, positionRelation, { x: 10, y: 20 });
 world.sync(); // 通配符钩子会被触发
+
+// 不再需要时移除钩子
+unhook();
 ```
 
 ### Exclusive Relations
@@ -241,8 +226,7 @@ bun run examples/simple/demo.ts
 - `delete(entity)`: 销毁实体及其所有组件
 - `query(componentIds)`: 快速查询具有指定组件的实体
 - `createQuery(componentIds)`: 创建可重用的查询对象
-- `hook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
-- `unhook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
+- `hook(componentIds, hook)`: 注册生命周期钩子，返回卸载函数
 - `serialize()`: 序列化世界状态为快照对象
 - `sync()`: 执行所有延迟命令
 

package/builder.d.mts

@@ -175,7 +175,7 @@ interface Command {
 /**
  * Hook types for component lifecycle events
  */
-interface LifecycleHook<T = unknown> {
+interface LegacyLifecycleHook<T = unknown> {
   /**
    * Called when a component is added to an entity
    */
@@ -189,21 +189,21 @@ interface LifecycleHook<T = unknown> {
    */
   on_remove?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
 }
-interface MultiLifecycleHook<T extends readonly ComponentType<any>[]> {
-  on_init?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
-  on_set?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
-  on_remove?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
+interface LifecycleHook<T extends readonly ComponentType<any>[]> {
+  on_init?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  on_set?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  on_remove?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
 }
 /**
  * Convenience function type for single component lifecycle events
  * Combines on_init, on_set, and on_remove into a single callback
  */
-type LifecycleCallback<T = unknown> = (type: "init" | "set" | "remove", entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+type LegacyLifecycleCallback<T = unknown> = (type: "init" | "set" | "remove", entityId: EntityId, componentType: EntityId<T>, component: T) => void;
 /**
  * Convenience function type for multi-component lifecycle events
  * Combines on_init, on_set, and on_remove into a single callback
  */
-type MultiLifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
+type LifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, ...components: ComponentTuple<T>) => void;
 type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
 type OptionalEntityId<T> = {
   optional: EntityId<T>;
@@ -217,11 +217,11 @@ type ComponentTypeToData<T> = T extends {
  * Type helper for component tuples extracted from EntityId array
  */
 type ComponentTuple<T extends readonly ComponentType<any>[]> = { readonly [K in keyof T]: ComponentTypeToData<T[K]> };
-interface MultiHookEntry {
+interface LifecycleHookEntry {
   componentTypes: readonly ComponentType<any>[];
   requiredComponents: EntityId<any>[];
   optionalComponents: EntityId<any>[];
-  hook: MultiLifecycleHook<any>;
+  hook: LifecycleHook<any>;
 }
 //#endregion
 //#region src/core/archetype.d.ts
@@ -260,7 +260,7 @@ declare class Archetype {
   /**
    * Multi-hooks that match this archetype
    */
-  readonly matchingMultiHooks: Set<MultiHookEntry>;
+  readonly matchingMultiHooks: Set<LifecycleHookEntry>;
   /**
    * Cache for pre-computed component data sources to avoid repeated calculations
    */
@@ -429,8 +429,8 @@ declare class World {
   private queries;
   private queryCache;
   private commandBuffer;
+  private legacyHooks;
   private hooks;
-  private multiHooks;
   constructor(snapshot?: SerializedWorld);
   private deserializeSnapshot;
   private createArchetypeSignature;
@@ -447,10 +447,15 @@ declare class World {
   getOptional<T>(entityId: EntityId, componentType: EntityId<T>): {
     value: T;
   } | undefined;
-  hook<T>(componentType: EntityId<T>, hook: LifecycleHook<T> | LifecycleCallback<T>): void;
-  hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: MultiLifecycleHook<T> | MultiLifecycleCallback<T>): void;
-  unhook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
-  unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: MultiLifecycleHook<T>): void;
+  /**
+   * @deprecated use array overload with LifecycleCallback
+   */
+  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;
+  /** @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 */
+  unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T>): void;
   sync(): void;
   createQuery(componentTypes: EntityId<any>[], filter?: QueryFilter): Query;
   spawn(): EntityBuilder;
@@ -510,5 +515,5 @@ declare class EntityBuilder {
   build(): EntityId;
 }
 //#endregion
-export { isRelationId as A, ComponentRelationId as C, WildcardRelationId as D, RelationId as E, isComponentId as O, ComponentId as S, EntityRelationId as T, getComponentIdByName as _, SerializedEntity as a, isWildcardRelationId as b, Query as c, LifecycleCallback as d, LifecycleHook as f, component as g, ComponentOptions as h, SerializedComponent as i, isEntityId as k, ComponentTuple as l, MultiLifecycleHook as m, EntityBuilder as n, SerializedEntityId as o, MultiLifecycleCallback as p, World as r, SerializedWorld as s, ComponentDef as t, ComponentType as u, getComponentNameById as v, EntityId as w, relation as x, decodeRelationId as y };
+export { isRelationId as A, ComponentRelationId as C, WildcardRelationId as D, RelationId as E, isComponentId as O, ComponentId as S, EntityRelationId as T, getComponentIdByName as _, SerializedEntity as a, isWildcardRelationId as b, Query as c, LegacyLifecycleCallback as d, LegacyLifecycleHook as f, component as g, ComponentOptions as h, SerializedComponent as i, isEntityId as k, ComponentTuple as l, LifecycleHook as m, EntityBuilder as n, SerializedEntityId as o, LifecycleCallback as p, World as r, SerializedWorld as s, ComponentDef as t, ComponentType as u, getComponentNameById as v, EntityId as w, relation as x, decodeRelationId as y };
 //# sourceMappingURL=builder.d.mts.map

package/index.d.mts

@@ -1,2 +1,2 @@
-import { A as isRelationId, C as ComponentRelationId, D as WildcardRelationId, E as RelationId, O as isComponentId, S as ComponentId, T as EntityRelationId, _ as getComponentIdByName, a as SerializedEntity, b as isWildcardRelationId, c as Query, d as LifecycleCallback, f as LifecycleHook, g as component, h as ComponentOptions, i as SerializedComponent, k as isEntityId, l as ComponentTuple, m as MultiLifecycleHook, n as EntityBuilder, o as SerializedEntityId, p as MultiLifecycleCallback, r as World, s as SerializedWorld, t as ComponentDef, u as ComponentType, v as getComponentNameById, w as EntityId, x as relation, y as decodeRelationId } from "./builder.mjs";
-export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, EntityBuilder, type EntityId, type EntityRelationId, type LifecycleCallback, type LifecycleHook, type MultiLifecycleCallback, type MultiLifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
+import { A as isRelationId, C as ComponentRelationId, D as WildcardRelationId, E as RelationId, O as isComponentId, S as ComponentId, T as EntityRelationId, _ as getComponentIdByName, a as SerializedEntity, b as isWildcardRelationId, c as Query, d as LegacyLifecycleCallback, f as LegacyLifecycleHook, g as component, h as ComponentOptions, i as SerializedComponent, k as isEntityId, l as ComponentTuple, m as LifecycleHook, n as EntityBuilder, o as SerializedEntityId, p as LifecycleCallback, r as World, s as SerializedWorld, t as ComponentDef, u as ComponentType, v as getComponentNameById, w as EntityId, x as relation, y as decodeRelationId } from "./builder.mjs";
+export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, EntityBuilder, type EntityId, type EntityRelationId, type LegacyLifecycleCallback as LifecycleCallback, type LegacyLifecycleHook as LifecycleHook, type LifecycleCallback as MultiLifecycleCallback, type LifecycleHook as MultiLifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };

package/package.json

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

package/testing.d.mts

@@ -1,4 +1,4 @@
-import { D as WildcardRelationId, E as RelationId, S as ComponentId, c as Query, d as LifecycleCallback, f as LifecycleHook, g as component, m as MultiLifecycleHook, n as EntityBuilder, p as MultiLifecycleCallback, r as World, t as ComponentDef, w as EntityId, x as relation } from "./builder.mjs";
+import { D as WildcardRelationId, E as RelationId, S as ComponentId, c as Query, d as LegacyLifecycleCallback, f as LegacyLifecycleHook, g as component, m as LifecycleHook, n as EntityBuilder, p as LifecycleCallback, r as World, t as ComponentDef, w as EntityId, x as relation } from "./builder.mjs";
 
 //#region src/testing/index.d.ts
 
@@ -254,5 +254,5 @@ declare class AssertionError extends Error {
   constructor(message: string);
 }
 //#endregion
-export { AssertionError, Assertions, type ComponentDef, type ComponentId, EntityBuilder, type EntityId, EntitySnapshot, type LifecycleCallback, type LifecycleHook, type MultiLifecycleCallback, type MultiLifecycleHook, type Query, type RelationId, Snapshot, SnapshotDiff, type WildcardRelationId, World, WorldFixture, WorldSnapshot, component, relation };
+export { AssertionError, Assertions, type ComponentDef, type ComponentId, EntityBuilder, type EntityId, EntitySnapshot, type LegacyLifecycleCallback as LifecycleCallback, type LegacyLifecycleHook as LifecycleHook, type LifecycleCallback as MultiLifecycleCallback, type LifecycleHook as MultiLifecycleHook, type Query, type RelationId, Snapshot, SnapshotDiff, type WildcardRelationId, World, WorldFixture, WorldSnapshot, component, relation };
 //# sourceMappingURL=testing.d.mts.map

package/testing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"testing.mjs","names":["entitySnapshots: EntitySnapshot[]","addedEntities: EntityId[]","removedEntities: EntityId[]","componentChanges: SnapshotDiff[\"componentChanges\"]","result: Record<string, unknown>"],"sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * @module testing\n * Testing utilities for ECS-based game logic\n *\n * This module provides framework-agnostic testing helpers that work with\n * bun:test, vitest, jest, or any other testing framework.\n *\n * @example\n * ```typescript\n * import { describe, expect, it } from \"bun:test\";\n * import { component } from \"@codehz/ecs\";\n * import { WorldFixture, EntityBuilder, Assertions } from \"@codehz/ecs/testing\";\n *\n * const PositionId = component<{ x: number; y: number }>();\n * const VelocityId = component<{ x: number; y: number }>();\n *\n * describe(\"Movement System\", () => {\n *   it(\"should update position based on velocity\", () => {\n *     const fixture = new WorldFixture();\n *     const entity = fixture\n *       .spawn()\n *       .with(PositionId, { x: 0, y: 0 })\n *       .with(VelocityId, { x: 1, y: 2 })\n *       .build();\n *\n *     // Run your game logic here\n *     movementSystem(fixture.world, 1.0);\n *\n *     expect(Assertions.hasComponent(fixture.world, entity, PositionId)).toBe(true);\n *     expect(Assertions.getComponent(fixture.world, entity, PositionId)).toEqual({ x: 1, y: 2 });\n *   });\n * });\n * ```\n */\n\nimport type { ComponentId, EntityId, WildcardRelationId } from \"../core/entity\";\nimport { isWildcardRelationId, relation } from \"../core/entity\";\nimport { World } from \"../core/world\";\nimport type { Query } from \"../query/query\";\nexport { EntityBuilder } from \"../core/builder\";\nexport type { ComponentDef } from \"../core/builder\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * A component definition for entity building, supporting both regular components and relations\n */\nimport type { EntityBuilder } from \"../core/builder\";\n\n/**\n * Snapshot of a single entity's component state\n */\nexport interface EntitySnapshot {\n  entity: EntityId;\n  components: Map<EntityId<any>, unknown>;\n}\n\n/**\n * Snapshot of multiple entities' component state\n */\nexport interface WorldSnapshot {\n  entities: EntitySnapshot[];\n}\n\n/**\n * Result of comparing two snapshots\n */\nexport interface SnapshotDiff {\n  /** Entities that exist in 'after' but not in 'before' */\n  addedEntities: EntityId[];\n  /** Entities that exist in 'before' but not in 'after' */\n  removedEntities: EntityId[];\n  /** Changes to components on existing entities */\n  componentChanges: Array<{\n    entity: EntityId;\n    componentId: EntityId<any>;\n    before: unknown | undefined;\n    after: unknown | undefined;\n    changeType: \"added\" | \"removed\" | \"modified\";\n  }>;\n}\n\n// =============================================================================\n// WorldFixture - Test World Factory\n// =============================================================================\n\n/**\n * A test fixture that manages a World instance and provides convenient\n * methods for setting up test scenarios.\n *\n * @example\n * ```typescript\n * const fixture = new WorldFixture();\n *\n * // Spawn entities with fluent API\n * const player = fixture\n *   .spawn()\n *   .with(PositionId, { x: 0, y: 0 })\n *   .with(HealthId, { current: 100, max: 100 })\n *   .build();\n *\n * // Access the world for running systems\n * movementSystem(fixture.world);\n *\n * // Clean up (optional - creates a fresh world)\n * fixture.reset();\n * ```\n */\nexport class WorldFixture {\n  private _world: World;\n  private _queries: Query[] = [];\n\n  constructor() {\n    this._world = new World();\n  }\n\n  /**\n   * Get the underlying World instance\n   */\n  get world(): World {\n    return this._world;\n  }\n\n  /**\n   * Create a new EntityBuilder for spawning an entity with components\n   */\n  spawn(): EntityBuilder {\n    return this._world.spawn();\n  }\n\n  /**\n   * Spawn multiple entities with the same component configuration\n   * @param count Number of entities to spawn\n   * @param configure Function to configure each entity builder\n   * @returns Array of created entity IDs\n   */\n  spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[] {\n    return this._world.spawnMany(count, configure);\n  }\n\n  /**\n   * Create a query and track it for automatic cleanup\n   * @param componentTypes Component types to query for\n   * @returns Query instance\n   */\n  createQuery(componentTypes: EntityId<any>[]): Query {\n    const query = this._world.createQuery(componentTypes);\n    this._queries.push(query);\n    return query;\n  }\n\n  /**\n   * Execute pending commands (alias for world.sync())\n   */\n  sync(): void {\n    this._world.sync();\n  }\n\n  /**\n   * Reset the fixture with a fresh World instance\n   * Disposes all tracked queries\n   */\n  reset(): void {\n    for (const query of this._queries) {\n      query.dispose();\n    }\n    this._queries = [];\n    this._world = new World();\n  }\n\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param entities Entities to capture\n   * @param componentIds Components to include in the snapshot\n   */\n  captureSnapshot(entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    return Snapshot.capture(this._world, entities, componentIds);\n  }\n\n  /**\n   * Symbol.dispose implementation for automatic resource management\n   */\n  [Symbol.dispose](): void {\n    this.reset();\n  }\n}\n\n// =============================================================================\n// EntityBuilder - Fluent Entity Creation\n// =============================================================================\n\n/**\n * Fluent builder for creating entities with components.\n * Supports both regular components and entity relations.\n *\n * @example\n * ```typescript\n * // Basic usage\n * // Note: build() will enqueue component commands but will NOT call world.sync().\n * // You must call world.sync() or fixture.sync() manually to apply commands.\n * const entity = new EntityBuilder(world)\n *   .with(PositionId, { x: 10, y: 20 })\n *   .with(VelocityId, { x: 1, y: 0 })\n *   .build();\n *   // Apply pending changes\n *   world.sync();\n *\n * // With relations\n * const child = new EntityBuilder(world)\n *   .with(PositionId, { x: 0, y: 0 })\n *   .withRelation(ParentId, parentEntity, { offset: { x: 5, y: 5 } })\n *   .build();\n *   world.sync();\n *\n * // Tag component (void type)\n * const tagged = new EntityBuilder(world)\n *   .withTag(PlayerTagId)\n *   .build();\n * ```\n */\n// EntityBuilder is exported from world.ts; testing utilities will use world.spawn()\n\n// =============================================================================\n// Assertions - Test Assertion Helpers\n// =============================================================================\n\n/**\n * Test assertion utilities that return boolean values or throw descriptive errors.\n * These work with any testing framework's expect() function.\n *\n * @example\n * ```typescript\n * // With bun:test or vitest\n * expect(Assertions.hasComponent(world, entity, PositionId)).toBe(true);\n * expect(Assertions.getComponent(world, entity, PositionId)).toEqual({ x: 10, y: 20 });\n *\n * // Direct assertion (throws on failure)\n * Assertions.assertHasComponent(world, entity, PositionId);\n * Assertions.assertComponentEquals(world, entity, PositionId, { x: 10, y: 20 });\n * ```\n */\nexport const Assertions = {\n  /**\n   * Check if an entity has a specific component\n   */\n  hasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return world.exists(entity) && world.has(entity, componentId);\n  },\n\n  /**\n   * Check if an entity does not have a specific component\n   */\n  lacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return !world.exists(entity) || !world.has(entity, componentId);\n  },\n\n  /**\n   * Get a component value (returns undefined if entity doesn't exist or doesn't have the component)\n   */\n  getComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): T | undefined {\n    if (!world.exists(entity) || !world.has(entity, componentId)) {\n      return undefined;\n    }\n    return world.get(entity, componentId);\n  },\n\n  /**\n   * Get all relation instances for a wildcard relation\n   */\n  getRelations<T>(world: World, entity: EntityId, componentId: ComponentId<T>): [EntityId<unknown>, T][] | undefined {\n    if (!world.exists(entity)) {\n      return undefined;\n    }\n    const wildcardId = relation(componentId, \"*\");\n    try {\n      return world.get(entity, wildcardId);\n    } catch {\n      return [];\n    }\n  },\n\n  /**\n   * Check if an entity has a relation to a specific target\n   */\n  hasRelation<T>(world: World, entity: EntityId, componentId: ComponentId<T>, targetEntity: EntityId<any>): boolean {\n    if (!world.exists(entity)) {\n      return false;\n    }\n    const relationId = relation(componentId, targetEntity);\n    return world.has(entity, relationId);\n  },\n\n  /**\n   * Check if an entity exists in the world\n   */\n  entityExists(world: World, entity: EntityId): boolean {\n    return world.exists(entity);\n  },\n\n  /**\n   * Check if a query contains specific entities\n   */\n  queryContains(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Check if a query contains exactly the specified entities (no more, no less)\n   */\n  queryContainsExactly(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    if (queryEntities.length !== entities.length) {\n      return false;\n    }\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Get the count of entities in a query\n   */\n  queryCount(query: Query): number {\n    return query.getEntities().length;\n  },\n\n  // === Throwing assertions ===\n\n  /**\n   * Assert that an entity has a component (throws if not)\n   */\n  assertHasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n    if (!world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} does not have component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that an entity lacks a component (throws if it has the component)\n   */\n  assertLacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (world.exists(entity) && world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly has component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that a component equals an expected value (throws if not)\n   */\n  assertComponentEquals<T>(world: World, entity: EntityId, componentId: EntityId<T>, expected: T): void {\n    this.assertHasComponent(world, entity, componentId);\n    const actual = world.get(entity, componentId);\n    if (!deepEquals(actual, expected)) {\n      throw new AssertionError(\n        `Component ${componentId} on entity ${entity} does not match expected value.\\n` +\n          `Expected: ${JSON.stringify(expected)}\\n` +\n          `Actual: ${JSON.stringify(actual)}`,\n      );\n    }\n  },\n\n  /**\n   * Assert that an entity exists (throws if not)\n   */\n  assertEntityExists(world: World, entity: EntityId): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n  },\n\n  /**\n   * Assert that an entity does not exist (throws if it exists)\n   */\n  assertEntityNotExists(world: World, entity: EntityId): void {\n    if (world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly exists`);\n    }\n  },\n\n  /**\n   * Assert that a query contains specific entities (throws if not)\n   */\n  assertQueryContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (!queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query does not contain entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n\n  /**\n   * Assert that a query does not contain specific entities (throws if it does)\n   */\n  assertQueryNotContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query unexpectedly contains entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n};\n\n// =============================================================================\n// Snapshot - State Capture and Comparison\n// =============================================================================\n\n/**\n * Utilities for capturing and comparing world state snapshots.\n * Useful for testing that systems produce expected state changes.\n *\n * @example\n * ```typescript\n * const before = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n *\n * // Run game logic\n * movementSystem(world, deltaTime);\n * world.sync();\n *\n * const after = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n * const diff = Snapshot.compare(before, after);\n *\n * expect(diff.componentChanges).toHaveLength(1);\n * expect(diff.componentChanges[0].changeType).toBe(\"modified\");\n * ```\n */\nexport const Snapshot = {\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param world The world to capture from\n   * @param entities Entities to include in the snapshot\n   * @param componentIds Components to capture for each entity\n   */\n  capture(world: World, entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    const entitySnapshots: EntitySnapshot[] = [];\n\n    for (const entity of entities) {\n      if (!world.exists(entity)) {\n        continue;\n      }\n\n      const components = new Map<EntityId<any>, unknown>();\n\n      for (const componentId of componentIds) {\n        if (isWildcardRelationId(componentId)) {\n          // For wildcard relations, capture all relation instances\n          try {\n            const relations = world.get(entity, componentId as WildcardRelationId<any>);\n            if (relations && relations.length > 0) {\n              components.set(componentId, deepClone(relations));\n            }\n          } catch {\n            // Entity doesn't have this relation type\n          }\n        } else if (world.has(entity, componentId)) {\n          components.set(componentId, deepClone(world.get(entity, componentId)));\n        }\n      }\n\n      entitySnapshots.push({ entity, components });\n    }\n\n    return { entities: entitySnapshots };\n  },\n\n  /**\n   * Compare two snapshots and return the differences\n   * @param before The 'before' snapshot\n   * @param after The 'after' snapshot\n   */\n  compare(before: WorldSnapshot, after: WorldSnapshot): SnapshotDiff {\n    const beforeEntities = new Set(before.entities.map((e) => e.entity));\n    const afterEntities = new Set(after.entities.map((e) => e.entity));\n\n    const addedEntities: EntityId[] = [];\n    const removedEntities: EntityId[] = [];\n    const componentChanges: SnapshotDiff[\"componentChanges\"] = [];\n\n    // Find added entities\n    for (const entity of afterEntities) {\n      if (!beforeEntities.has(entity)) {\n        addedEntities.push(entity);\n      }\n    }\n\n    // Find removed entities\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) {\n        removedEntities.push(entity);\n      }\n    }\n\n    // Find component changes on existing entities\n    const beforeMap = new Map(before.entities.map((e) => [e.entity, e]));\n    const afterMap = new Map(after.entities.map((e) => [e.entity, e]));\n\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) continue; // Skip removed entities\n\n      const beforeEntity = beforeMap.get(entity)!;\n      const afterEntity = afterMap.get(entity)!;\n\n      // Check for component changes\n      const allComponentIds = new Set([...beforeEntity.components.keys(), ...afterEntity.components.keys()]);\n\n      for (const componentId of allComponentIds) {\n        const beforeValue = beforeEntity.components.get(componentId);\n        const afterValue = afterEntity.components.get(componentId);\n\n        if (beforeValue === undefined && afterValue !== undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: undefined,\n            after: afterValue,\n            changeType: \"added\",\n          });\n        } else if (beforeValue !== undefined && afterValue === undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: undefined,\n            changeType: \"removed\",\n          });\n        } else if (!deepEquals(beforeValue, afterValue)) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: afterValue,\n            changeType: \"modified\",\n          });\n        }\n      }\n    }\n\n    return { addedEntities, removedEntities, componentChanges };\n  },\n\n  /**\n   * Check if two snapshots are equal\n   */\n  equals(a: WorldSnapshot, b: WorldSnapshot): boolean {\n    const diff = this.compare(a, b);\n    return diff.addedEntities.length === 0 && diff.removedEntities.length === 0 && diff.componentChanges.length === 0;\n  },\n};\n\n// =============================================================================\n// Utilities\n// =============================================================================\n\n/**\n * Custom assertion error for testing utilities\n */\nexport class AssertionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AssertionError\";\n  }\n}\n\n/**\n * Deep equality check for comparing component values\n */\nfunction deepEquals(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  if (typeof a !== typeof b) return false;\n\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEquals(a[i], b[i])) return false;\n    }\n    return true;\n  }\n\n  if (typeof a === \"object\" && typeof b === \"object\") {\n    const aObj = a as Record<string, unknown>;\n    const bObj = b as Record<string, unknown>;\n    const aKeys = Object.keys(aObj);\n    const bKeys = Object.keys(bObj);\n\n    if (aKeys.length !== bKeys.length) return false;\n\n    for (const key of aKeys) {\n      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;\n      if (!deepEquals(aObj[key], bObj[key])) return false;\n    }\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Deep clone a value for snapshot isolation\n */\nfunction deepClone<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(deepClone) as T;\n  }\n\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    result[key] = deepClone((value as Record<string, unknown>)[key]);\n  }\n  return result as T;\n}\n\n// =============================================================================\n// Re-exports for convenience\n// =============================================================================\n\nexport { component, relation } from \"../core/entity\";\nexport type { ComponentId, EntityId, RelationId, WildcardRelationId } from \"../core/entity\";\nexport type { LifecycleCallback, LifecycleHook, MultiLifecycleCallback, MultiLifecycleHook } from \"../core/types\";\nexport { World } from \"../core/world\";\nexport type { Query } from \"../query/query\";\n"],"mappings":"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"}
+{"version":3,"file":"testing.mjs","names":["entitySnapshots: EntitySnapshot[]","addedEntities: EntityId[]","removedEntities: EntityId[]","componentChanges: SnapshotDiff[\"componentChanges\"]","result: Record<string, unknown>"],"sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * @module testing\n * Testing utilities for ECS-based game logic\n *\n * This module provides framework-agnostic testing helpers that work with\n * bun:test, vitest, jest, or any other testing framework.\n *\n * @example\n * ```typescript\n * import { describe, expect, it } from \"bun:test\";\n * import { component } from \"@codehz/ecs\";\n * import { WorldFixture, EntityBuilder, Assertions } from \"@codehz/ecs/testing\";\n *\n * const PositionId = component<{ x: number; y: number }>();\n * const VelocityId = component<{ x: number; y: number }>();\n *\n * describe(\"Movement System\", () => {\n *   it(\"should update position based on velocity\", () => {\n *     const fixture = new WorldFixture();\n *     const entity = fixture\n *       .spawn()\n *       .with(PositionId, { x: 0, y: 0 })\n *       .with(VelocityId, { x: 1, y: 2 })\n *       .build();\n *\n *     // Run your game logic here\n *     movementSystem(fixture.world, 1.0);\n *\n *     expect(Assertions.hasComponent(fixture.world, entity, PositionId)).toBe(true);\n *     expect(Assertions.getComponent(fixture.world, entity, PositionId)).toEqual({ x: 1, y: 2 });\n *   });\n * });\n * ```\n */\n\nimport type { ComponentId, EntityId, WildcardRelationId } from \"../core/entity\";\nimport { isWildcardRelationId, relation } from \"../core/entity\";\nimport { World } from \"../core/world\";\nimport type { Query } from \"../query/query\";\nexport { EntityBuilder } from \"../core/builder\";\nexport type { ComponentDef } from \"../core/builder\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * A component definition for entity building, supporting both regular components and relations\n */\nimport type { EntityBuilder } from \"../core/builder\";\n\n/**\n * Snapshot of a single entity's component state\n */\nexport interface EntitySnapshot {\n  entity: EntityId;\n  components: Map<EntityId<any>, unknown>;\n}\n\n/**\n * Snapshot of multiple entities' component state\n */\nexport interface WorldSnapshot {\n  entities: EntitySnapshot[];\n}\n\n/**\n * Result of comparing two snapshots\n */\nexport interface SnapshotDiff {\n  /** Entities that exist in 'after' but not in 'before' */\n  addedEntities: EntityId[];\n  /** Entities that exist in 'before' but not in 'after' */\n  removedEntities: EntityId[];\n  /** Changes to components on existing entities */\n  componentChanges: Array<{\n    entity: EntityId;\n    componentId: EntityId<any>;\n    before: unknown | undefined;\n    after: unknown | undefined;\n    changeType: \"added\" | \"removed\" | \"modified\";\n  }>;\n}\n\n// =============================================================================\n// WorldFixture - Test World Factory\n// =============================================================================\n\n/**\n * A test fixture that manages a World instance and provides convenient\n * methods for setting up test scenarios.\n *\n * @example\n * ```typescript\n * const fixture = new WorldFixture();\n *\n * // Spawn entities with fluent API\n * const player = fixture\n *   .spawn()\n *   .with(PositionId, { x: 0, y: 0 })\n *   .with(HealthId, { current: 100, max: 100 })\n *   .build();\n *\n * // Access the world for running systems\n * movementSystem(fixture.world);\n *\n * // Clean up (optional - creates a fresh world)\n * fixture.reset();\n * ```\n */\nexport class WorldFixture {\n  private _world: World;\n  private _queries: Query[] = [];\n\n  constructor() {\n    this._world = new World();\n  }\n\n  /**\n   * Get the underlying World instance\n   */\n  get world(): World {\n    return this._world;\n  }\n\n  /**\n   * Create a new EntityBuilder for spawning an entity with components\n   */\n  spawn(): EntityBuilder {\n    return this._world.spawn();\n  }\n\n  /**\n   * Spawn multiple entities with the same component configuration\n   * @param count Number of entities to spawn\n   * @param configure Function to configure each entity builder\n   * @returns Array of created entity IDs\n   */\n  spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[] {\n    return this._world.spawnMany(count, configure);\n  }\n\n  /**\n   * Create a query and track it for automatic cleanup\n   * @param componentTypes Component types to query for\n   * @returns Query instance\n   */\n  createQuery(componentTypes: EntityId<any>[]): Query {\n    const query = this._world.createQuery(componentTypes);\n    this._queries.push(query);\n    return query;\n  }\n\n  /**\n   * Execute pending commands (alias for world.sync())\n   */\n  sync(): void {\n    this._world.sync();\n  }\n\n  /**\n   * Reset the fixture with a fresh World instance\n   * Disposes all tracked queries\n   */\n  reset(): void {\n    for (const query of this._queries) {\n      query.dispose();\n    }\n    this._queries = [];\n    this._world = new World();\n  }\n\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param entities Entities to capture\n   * @param componentIds Components to include in the snapshot\n   */\n  captureSnapshot(entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    return Snapshot.capture(this._world, entities, componentIds);\n  }\n\n  /**\n   * Symbol.dispose implementation for automatic resource management\n   */\n  [Symbol.dispose](): void {\n    this.reset();\n  }\n}\n\n// =============================================================================\n// EntityBuilder - Fluent Entity Creation\n// =============================================================================\n\n/**\n * Fluent builder for creating entities with components.\n * Supports both regular components and entity relations.\n *\n * @example\n * ```typescript\n * // Basic usage\n * // Note: build() will enqueue component commands but will NOT call world.sync().\n * // You must call world.sync() or fixture.sync() manually to apply commands.\n * const entity = new EntityBuilder(world)\n *   .with(PositionId, { x: 10, y: 20 })\n *   .with(VelocityId, { x: 1, y: 0 })\n *   .build();\n *   // Apply pending changes\n *   world.sync();\n *\n * // With relations\n * const child = new EntityBuilder(world)\n *   .with(PositionId, { x: 0, y: 0 })\n *   .withRelation(ParentId, parentEntity, { offset: { x: 5, y: 5 } })\n *   .build();\n *   world.sync();\n *\n * // Tag component (void type)\n * const tagged = new EntityBuilder(world)\n *   .withTag(PlayerTagId)\n *   .build();\n * ```\n */\n// EntityBuilder is exported from world.ts; testing utilities will use world.spawn()\n\n// =============================================================================\n// Assertions - Test Assertion Helpers\n// =============================================================================\n\n/**\n * Test assertion utilities that return boolean values or throw descriptive errors.\n * These work with any testing framework's expect() function.\n *\n * @example\n * ```typescript\n * // With bun:test or vitest\n * expect(Assertions.hasComponent(world, entity, PositionId)).toBe(true);\n * expect(Assertions.getComponent(world, entity, PositionId)).toEqual({ x: 10, y: 20 });\n *\n * // Direct assertion (throws on failure)\n * Assertions.assertHasComponent(world, entity, PositionId);\n * Assertions.assertComponentEquals(world, entity, PositionId, { x: 10, y: 20 });\n * ```\n */\nexport const Assertions = {\n  /**\n   * Check if an entity has a specific component\n   */\n  hasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return world.exists(entity) && world.has(entity, componentId);\n  },\n\n  /**\n   * Check if an entity does not have a specific component\n   */\n  lacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return !world.exists(entity) || !world.has(entity, componentId);\n  },\n\n  /**\n   * Get a component value (returns undefined if entity doesn't exist or doesn't have the component)\n   */\n  getComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): T | undefined {\n    if (!world.exists(entity) || !world.has(entity, componentId)) {\n      return undefined;\n    }\n    return world.get(entity, componentId);\n  },\n\n  /**\n   * Get all relation instances for a wildcard relation\n   */\n  getRelations<T>(world: World, entity: EntityId, componentId: ComponentId<T>): [EntityId<unknown>, T][] | undefined {\n    if (!world.exists(entity)) {\n      return undefined;\n    }\n    const wildcardId = relation(componentId, \"*\");\n    try {\n      return world.get(entity, wildcardId);\n    } catch {\n      return [];\n    }\n  },\n\n  /**\n   * Check if an entity has a relation to a specific target\n   */\n  hasRelation<T>(world: World, entity: EntityId, componentId: ComponentId<T>, targetEntity: EntityId<any>): boolean {\n    if (!world.exists(entity)) {\n      return false;\n    }\n    const relationId = relation(componentId, targetEntity);\n    return world.has(entity, relationId);\n  },\n\n  /**\n   * Check if an entity exists in the world\n   */\n  entityExists(world: World, entity: EntityId): boolean {\n    return world.exists(entity);\n  },\n\n  /**\n   * Check if a query contains specific entities\n   */\n  queryContains(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Check if a query contains exactly the specified entities (no more, no less)\n   */\n  queryContainsExactly(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    if (queryEntities.length !== entities.length) {\n      return false;\n    }\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Get the count of entities in a query\n   */\n  queryCount(query: Query): number {\n    return query.getEntities().length;\n  },\n\n  // === Throwing assertions ===\n\n  /**\n   * Assert that an entity has a component (throws if not)\n   */\n  assertHasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n    if (!world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} does not have component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that an entity lacks a component (throws if it has the component)\n   */\n  assertLacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (world.exists(entity) && world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly has component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that a component equals an expected value (throws if not)\n   */\n  assertComponentEquals<T>(world: World, entity: EntityId, componentId: EntityId<T>, expected: T): void {\n    this.assertHasComponent(world, entity, componentId);\n    const actual = world.get(entity, componentId);\n    if (!deepEquals(actual, expected)) {\n      throw new AssertionError(\n        `Component ${componentId} on entity ${entity} does not match expected value.\\n` +\n          `Expected: ${JSON.stringify(expected)}\\n` +\n          `Actual: ${JSON.stringify(actual)}`,\n      );\n    }\n  },\n\n  /**\n   * Assert that an entity exists (throws if not)\n   */\n  assertEntityExists(world: World, entity: EntityId): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n  },\n\n  /**\n   * Assert that an entity does not exist (throws if it exists)\n   */\n  assertEntityNotExists(world: World, entity: EntityId): void {\n    if (world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly exists`);\n    }\n  },\n\n  /**\n   * Assert that a query contains specific entities (throws if not)\n   */\n  assertQueryContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (!queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query does not contain entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n\n  /**\n   * Assert that a query does not contain specific entities (throws if it does)\n   */\n  assertQueryNotContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query unexpectedly contains entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n};\n\n// =============================================================================\n// Snapshot - State Capture and Comparison\n// =============================================================================\n\n/**\n * Utilities for capturing and comparing world state snapshots.\n * Useful for testing that systems produce expected state changes.\n *\n * @example\n * ```typescript\n * const before = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n *\n * // Run game logic\n * movementSystem(world, deltaTime);\n * world.sync();\n *\n * const after = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n * const diff = Snapshot.compare(before, after);\n *\n * expect(diff.componentChanges).toHaveLength(1);\n * expect(diff.componentChanges[0].changeType).toBe(\"modified\");\n * ```\n */\nexport const Snapshot = {\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param world The world to capture from\n   * @param entities Entities to include in the snapshot\n   * @param componentIds Components to capture for each entity\n   */\n  capture(world: World, entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    const entitySnapshots: EntitySnapshot[] = [];\n\n    for (const entity of entities) {\n      if (!world.exists(entity)) {\n        continue;\n      }\n\n      const components = new Map<EntityId<any>, unknown>();\n\n      for (const componentId of componentIds) {\n        if (isWildcardRelationId(componentId)) {\n          // For wildcard relations, capture all relation instances\n          try {\n            const relations = world.get(entity, componentId as WildcardRelationId<any>);\n            if (relations && relations.length > 0) {\n              components.set(componentId, deepClone(relations));\n            }\n          } catch {\n            // Entity doesn't have this relation type\n          }\n        } else if (world.has(entity, componentId)) {\n          components.set(componentId, deepClone(world.get(entity, componentId)));\n        }\n      }\n\n      entitySnapshots.push({ entity, components });\n    }\n\n    return { entities: entitySnapshots };\n  },\n\n  /**\n   * Compare two snapshots and return the differences\n   * @param before The 'before' snapshot\n   * @param after The 'after' snapshot\n   */\n  compare(before: WorldSnapshot, after: WorldSnapshot): SnapshotDiff {\n    const beforeEntities = new Set(before.entities.map((e) => e.entity));\n    const afterEntities = new Set(after.entities.map((e) => e.entity));\n\n    const addedEntities: EntityId[] = [];\n    const removedEntities: EntityId[] = [];\n    const componentChanges: SnapshotDiff[\"componentChanges\"] = [];\n\n    // Find added entities\n    for (const entity of afterEntities) {\n      if (!beforeEntities.has(entity)) {\n        addedEntities.push(entity);\n      }\n    }\n\n    // Find removed entities\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) {\n        removedEntities.push(entity);\n      }\n    }\n\n    // Find component changes on existing entities\n    const beforeMap = new Map(before.entities.map((e) => [e.entity, e]));\n    const afterMap = new Map(after.entities.map((e) => [e.entity, e]));\n\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) continue; // Skip removed entities\n\n      const beforeEntity = beforeMap.get(entity)!;\n      const afterEntity = afterMap.get(entity)!;\n\n      // Check for component changes\n      const allComponentIds = new Set([...beforeEntity.components.keys(), ...afterEntity.components.keys()]);\n\n      for (const componentId of allComponentIds) {\n        const beforeValue = beforeEntity.components.get(componentId);\n        const afterValue = afterEntity.components.get(componentId);\n\n        if (beforeValue === undefined && afterValue !== undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: undefined,\n            after: afterValue,\n            changeType: \"added\",\n          });\n        } else if (beforeValue !== undefined && afterValue === undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: undefined,\n            changeType: \"removed\",\n          });\n        } else if (!deepEquals(beforeValue, afterValue)) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: afterValue,\n            changeType: \"modified\",\n          });\n        }\n      }\n    }\n\n    return { addedEntities, removedEntities, componentChanges };\n  },\n\n  /**\n   * Check if two snapshots are equal\n   */\n  equals(a: WorldSnapshot, b: WorldSnapshot): boolean {\n    const diff = this.compare(a, b);\n    return diff.addedEntities.length === 0 && diff.removedEntities.length === 0 && diff.componentChanges.length === 0;\n  },\n};\n\n// =============================================================================\n// Utilities\n// =============================================================================\n\n/**\n * Custom assertion error for testing utilities\n */\nexport class AssertionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AssertionError\";\n  }\n}\n\n/**\n * Deep equality check for comparing component values\n */\nfunction deepEquals(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  if (typeof a !== typeof b) return false;\n\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEquals(a[i], b[i])) return false;\n    }\n    return true;\n  }\n\n  if (typeof a === \"object\" && typeof b === \"object\") {\n    const aObj = a as Record<string, unknown>;\n    const bObj = b as Record<string, unknown>;\n    const aKeys = Object.keys(aObj);\n    const bKeys = Object.keys(bObj);\n\n    if (aKeys.length !== bKeys.length) return false;\n\n    for (const key of aKeys) {\n      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;\n      if (!deepEquals(aObj[key], bObj[key])) return false;\n    }\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Deep clone a value for snapshot isolation\n */\nfunction deepClone<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(deepClone) as T;\n  }\n\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    result[key] = deepClone((value as Record<string, unknown>)[key]);\n  }\n  return result as T;\n}\n\n// =============================================================================\n// Re-exports for convenience\n// =============================================================================\n\nexport { component, relation } from \"../core/entity\";\nexport type { ComponentId, EntityId, RelationId, WildcardRelationId } from \"../core/entity\";\nexport type {\n  LegacyLifecycleCallback as LifecycleCallback,\n  LegacyLifecycleHook as LifecycleHook,\n  LifecycleCallback as MultiLifecycleCallback,\n  LifecycleHook as MultiLifecycleHook,\n} from \"../core/types\";\nexport { World } from \"../core/world\";\nexport type { Query } from \"../query/query\";\n"],"mappings":"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"}

package/world.mjs

@@ -1530,12 +1530,12 @@ function triggerMultiComponentHooks(ctx, entityId, addedComponents, removedCompo
 		if (!hook.on_set) continue;
 		const anyRequiredAdded = requiredComponents.some((c) => anyComponentMatches(addedComponents, c));
 		const anyOptionalAdded = optionalComponents.some((c) => anyComponentMatches(addedComponents, c));
-		if ((anyRequiredAdded || anyOptionalAdded) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, componentTypes, collectMultiHookComponents(ctx, entityId, componentTypes));
+		if ((anyRequiredAdded || anyOptionalAdded) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
 	}
 	if (removedComponents.size > 0) 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)) hook.on_remove(entityId, componentTypes, collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
+		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));
 	}
 }
 function entityHasAllComponents(ctx, entityId, requiredComponents) {
@@ -1564,14 +1564,32 @@ function entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removed
 function collectMultiHookComponents(ctx, entityId, componentTypes) {
 	return componentTypes.map((ct) => isOptionalEntityId(ct) ? ctx.getOptional(entityId, ct.optional) : ctx.get(entityId, ct));
 }
+/**
+* Reconstructs wildcard relation data by merging current data with removed components.
+* Returns an array of [targetId, value] tuples for the wildcard relation.
+*/
+function reconstructWildcardWithRemoved(ctx, entityId, wildcardId, removedComponents) {
+	const currentData = ctx.get(entityId, wildcardId);
+	const result = Array.isArray(currentData) ? [...currentData] : [];
+	for (const [removedCompId, removedValue] of removedComponents.entries()) if (componentMatchesHookType(removedCompId, wildcardId)) {
+		const targetId = getTargetIdFromRelationId(removedCompId);
+		if (targetId !== void 0) result.push([targetId, removedValue]);
+	}
+	return result;
+}
 function collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents) {
 	return componentTypes.map((ct) => {
 		if (isOptionalEntityId(ct)) {
 			const optionalId = ct.optional;
+			if (isWildcardRelationId(optionalId)) {
+				const result = reconstructWildcardWithRemoved(ctx, entityId, optionalId, removedComponents);
+				return result.length > 0 ? { value: result } : void 0;
+			}
 			const match$1 = findMatchingComponent(removedComponents, optionalId);
 			return match$1 ? { value: match$1[1] } : ctx.getOptional(entityId, optionalId);
 		}
 		const compId = ct;
+		if (isWildcardRelationId(compId)) return reconstructWildcardWithRemoved(ctx, entityId, compId, removedComponents);
 		const match = findMatchingComponent(removedComponents, compId);
 		return match ? match[1] : ctx.get(entityId, compId);
 	});
@@ -1680,8 +1698,8 @@ var World = class {
 	queries = [];
 	queryCache = /* @__PURE__ */ new Map();
 	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
-	hooks = /* @__PURE__ */ new Map();
-	multiHooks = /* @__PURE__ */ new Set();
+	legacyHooks = /* @__PURE__ */ new Map();
+	hooks = /* @__PURE__ */ new Set();
 	constructor(snapshot) {
 		if (snapshot && typeof snapshot === "object") this.deserializeSnapshot(snapshot);
 	}
@@ -1791,9 +1809,9 @@ var World = class {
 		if (typeof hook === "function") if (Array.isArray(componentTypesOrSingle)) {
 			const callback = hook;
 			hook = {
-				on_init: (entityId, componentTypes, components) => callback("init", entityId, componentTypes, components),
-				on_set: (entityId, componentTypes, components) => callback("set", entityId, componentTypes, components),
-				on_remove: (entityId, componentTypes, components) => callback("remove", entityId, componentTypes, components)
+				on_init: (entityId, ...components) => callback("init", entityId, ...components),
+				on_set: (entityId, ...components) => callback("set", entityId, ...components),
+				on_remove: (entityId, ...components) => callback("remove", entityId, ...components)
 			};
 		} else {
 			const callback = hook;
@@ -1815,45 +1833,57 @@ var World = class {
 				optionalComponents,
 				hook
 			};
-			this.multiHooks.add(entry);
+			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()) {
 					const components = collectMultiHookComponents(this.createHooksContext(), entityId, componentTypes);
-					multiHook.on_init(entityId, componentTypes, components);
+					multiHook.on_init(entityId, ...components);
 				}
 			}
+			return () => {
+				this.hooks.delete(entry);
+				for (const archetype of this.archetypes) archetype.matchingMultiHooks.delete(entry);
+			};
 		} else {
 			const componentType = componentTypesOrSingle;
-			if (!this.hooks.has(componentType)) this.hooks.set(componentType, /* @__PURE__ */ new Set());
-			this.hooks.get(componentType).add(hook);
-			const singleHook = hook;
-			if (singleHook.on_init !== void 0) this.archetypesByComponent.get(componentType)?.forEach((archetype) => {
+			if (!this.legacyHooks.has(componentType)) this.legacyHooks.set(componentType, /* @__PURE__ */ new Set());
+			const legacyHook = hook;
+			this.legacyHooks.get(componentType).add(legacyHook);
+			if (legacyHook.on_init !== void 0) 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 ? void 0 : data;
-					singleHook.on_init?.(entity, componentType, value);
+					legacyHook.on_init?.(entity, componentType, value);
 				}
 			});
+			return () => {
+				const hooks = this.legacyHooks.get(componentType);
+				if (hooks) {
+					hooks.delete(legacyHook);
+					if (hooks.size === 0) this.legacyHooks.delete(componentType);
+				}
+			};
 		}
 	}
+	/** @deprecated use the unsubscribe function returned by hook() instead */
 	unhook(componentTypesOrSingle, hook) {
 		if (Array.isArray(componentTypesOrSingle)) {
-			for (const entry of this.multiHooks) if (entry.hook === hook) {
-				this.multiHooks.delete(entry);
+			for (const entry of this.hooks) if (entry.hook === hook) {
+				this.hooks.delete(entry);
 				for (const archetype of this.archetypes) archetype.matchingMultiHooks.delete(entry);
 				break;
 			}
 		} else {
 			const componentType = componentTypesOrSingle;
-			const hooks = this.hooks.get(componentType);
+			const hooks = this.legacyHooks.get(componentType);
 			if (hooks) {
 				hooks.delete(hook);
-				if (hooks.size === 0) this.hooks.delete(componentType);
+				if (hooks.size === 0) this.legacyHooks.delete(componentType);
 			}
 		}
 	}
@@ -1962,8 +1992,8 @@ var World = class {
 	}
 	createHooksContext() {
 		return {
-			hooks: this.hooks,
-			multiHooks: this.multiHooks,
+			hooks: this.legacyHooks,
+			multiHooks: this.hooks,
 			has: (eid, ct) => this.has(eid, ct),
 			get: (eid, ct) => this.get(eid, ct),
 			getOptional: (eid, ct) => this.getOptional(eid, ct)
@@ -2011,7 +2041,7 @@ var World = class {
 		return newArchetype;
 	}
 	updateArchetypeHookMatches(archetype) {
-		for (const entry of this.multiHooks) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
+		for (const entry of this.hooks) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
 	}
 	archetypeMatchesHook(archetype, entry) {
 		return entry.requiredComponents.every((c) => {