@codehz/ecs 0.7.5 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "license": "MIT",
   "module": "src/index.ts",
   "type": "module",
@@ -27,8 +27,8 @@
     "README.en.md"
   ],
   "devDependencies": {
-    "@codehz/pipeline": "^0.3.0",
-    "@types/bun": "1.3.2",
+    "@codehz/pipeline": "^0.4.3",
+    "@types/bun": "1.3.13",
     "@typescript-eslint/eslint-plugin": "^8.48.1",
     "@typescript-eslint/parser": "^8.48.1",
     "eslint": "^9.39.1",
@@ -37,7 +37,7 @@
     "lint-staged": "^16.2.6",
     "prettier": "^3.6.2",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "tsdown": "^0.16.6"
+    "tsdown": "^0.22.0"
   },
   "repository": {
     "url": "https://github.com/codehz/ecs"

package/src/__tests__/world/wildcard-relation-hooks.test.ts

@@ -329,4 +329,45 @@ describe("Wildcard-Relation Hooks", () => {
     expect(world.exists(entity1)).toBe(true);
     expect(world.exists(entity2)).toBe(true);
   });
+
+  // Regression: wildcard remove (relation(Comp, "*")) should NOT produce target=0
+  // in on_remove. The wildcard marker (WILDCARD_TARGET_ID=0) leaks into
+  // removedComponents and gets decoded as target=0 by reconstructWildcardWithRemoved.
+  it("should NOT report target=0 in on_remove when using wildcard remove (relation(Comp, '*'))", () => {
+    const world = new World();
+
+    // Use dontFragment:true so that removeWildcardRelations adds the wildcard
+    // marker to removedComponents, triggering the bug path.
+    const RelData = component<{ value: string }>({ dontFragment: true });
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+    const concreteRel = relation(RelData, target);
+
+    const removeCalls: { relations: [EntityId, { value: string }][] }[] = [];
+
+    world.hook([wildcardRel], {
+      on_remove: (_entityId, relations) => {
+        removeCalls.push({ relations });
+      },
+    });
+
+    const entity = world.spawn().with(concreteRel, { value: "hello" }).build();
+    world.sync();
+
+    // Remove ALL relations via wildcard — this triggers the bug
+    world.remove(entity, wildcardRel);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    const reportedRelations = removeCalls[0]!.relations;
+
+    // The hook should report the removed relation(s) WITHOUT the wildcard
+    // marker leaking in as target=0.
+    for (const [reportedTarget] of reportedRelations) {
+      expect(reportedTarget).not.toBe(0);
+    }
+
+    // It should still correctly report the actual removed relation
+    expect(reportedRelations).toContainEqual([target, { value: "hello" }]);
+  });
 });

package/src/world/hooks.ts

@@ -263,6 +263,9 @@ function reconstructWildcardWithRemoved(
   // Re-inject matching relations that were just removed, so the hook callback
   // sees the complete snapshot as it existed before the removal.
   for (const [removedCompId, removedValue] of removedComponents.entries()) {
+    // Skip wildcard markers themselves — they encode WILDCARD_TARGET_ID=0 and
+    // would produce spurious [0, undefined] entries in the hook callback.
+    if (isWildcardRelationId(removedCompId)) continue;
     if (componentMatchesHookType(removedCompId, wildcardId)) {
       const targetId = getTargetIdFromRelationId(removedCompId);
       if (targetId !== undefined) {
@@ -346,6 +349,8 @@ function collectWildcardFromRemoved(
   const result: [EntityId, any][] = [];
 
   for (const [removedCompId, removedValue] of removedComponents.entries()) {
+    // Skip wildcard markers themselves — they encode WILDCARD_TARGET_ID=0.
+    if (isWildcardRelationId(removedCompId)) continue;
     if (componentMatchesHookType(removedCompId, wildcardId)) {
       const targetId = getTargetIdFromRelationId(removedCompId);
       if (targetId !== undefined) {

package/src/world/world.ts

@@ -698,25 +698,28 @@ export class World {
    * **Important:** Store the query reference and reuse it across frames for optimal performance.
    * Creating a new query each frame defeats the caching mechanism.
    *
-   * @param componentTypes - Array of component types to match
-   * @param filter - Optional filter for additional constraints (e.g., without specific components)
+   * **Note on optional components:** Only **required** (non-optional) component types should be
+   * passed to `createQuery`. Optional components (wrapped with `{ optional: ... }`) must be
+   * specified at **iteration time** via {@link Query.forEach}, {@link Query.getEntitiesWithComponents},
+   * or {@link Query.iterate} — NOT here. Including optional wrappers in `createQuery` will cause
+   * undefined behavior because the internal normalization relies on numeric sorting of component IDs.
+   *
+   * @param componentTypes - Array of **required** component types to match (do not include optional wrappers)
+   * @param filter - Optional filter for additional constraints (e.g., exclude entities with certain components)
    * @returns A Query instance that can be used to iterate matching entities
    *
    * @example
-   * // Create once, reuse many times
+   * // Create once, reuse many times (required components only)
    * const movementQuery = world.createQuery([Position, Velocity]);
    *
-   * // In game loop
-   * movementQuery.forEach((entity) => {
-   *   const pos = world.get(entity, Position);
-   *   const vel = world.get(entity, Velocity);
-   *   pos.x += vel.x;
-   *   pos.y += vel.y;
+   * // Optional components are passed at iteration time, not creation time:
+   * movementQuery.forEach([Position, { optional: Velocity }], (entity, pos, vel) => {
+   *   pos.x += vel?.value?.x ?? 0;
    * });
    *
    * // With filter
    * const activeQuery = world.createQuery([Position], {
-   *   without: [Disabled]
+   *   negativeComponentTypes: [Disabled]
    * });
    */
   createQuery(componentTypes: EntityId<any>[], filter: QueryFilter = {}): Query {