@codehz/ecs 0.7.1 → 0.7.3

package/src/__tests__/world/query.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation } from "../../entity";
+import { World } from "../../world/world";
+
+describe("World - Query", () => {
+  type Position = { x: number; y: number };
+  type Velocity = { x: number; y: number };
+
+  const markComponent = component();
+  const positionComponent = component<Position>();
+  const velocityComponent = component<Velocity>();
+
+  it("should query entities with specific components", () => {
+    const world = new World();
+    const entity1 = world.new();
+    const entity2 = world.new();
+    const entity3 = world.new();
+
+    world.set(entity1, positionComponent, { x: 1, y: 2 });
+    world.set(entity1, velocityComponent, { x: 0.1, y: 0.2 });
+
+    world.set(entity2, positionComponent, { x: 3, y: 4 });
+
+    // entity3 has no components
+
+    world.sync(); // Execute deferred commands
+
+    const positionEntities = world.query([positionComponent]);
+    expect(positionEntities).toContain(entity1);
+    expect(positionEntities).toContain(entity2);
+    expect(positionEntities).not.toContain(entity3);
+
+    const velocityEntities = world.query([velocityComponent]);
+    expect(velocityEntities).toContain(entity1);
+    expect(velocityEntities).not.toContain(entity2);
+    expect(velocityEntities).not.toContain(entity3);
+
+    const bothEntities = world.query([positionComponent, velocityComponent]);
+    expect(bothEntities).toContain(entity1);
+    expect(bothEntities).not.toContain(entity2);
+    expect(bothEntities).not.toContain(entity3);
+  });
+
+  it("should return empty array for queries with no matches", () => {
+    const world = new World();
+    const entity = world.new();
+    world.set(entity, positionComponent, { x: 1, y: 2 });
+
+    const result = world.query([velocityComponent]);
+    expect(result).toEqual([]);
+  });
+
+  it("should query entities with included component data", () => {
+    const world = new World();
+    const entity1 = world.new();
+    const entity2 = world.new();
+
+    const pos1 = { x: 1, y: 2 };
+    const vel1 = { x: 0.1, y: 0.2 };
+    const pos2 = { x: 3, y: 4 };
+
+    world.set(entity1, positionComponent, pos1);
+    world.set(entity1, velocityComponent, vel1);
+    world.set(entity2, positionComponent, pos2);
+    world.sync();
+
+    const results = world.query([positionComponent], true);
+
+    expect(results).toHaveLength(2);
+
+    const result1 = results.find((result) => result.entity === entity1);
+    const result2 = results.find((result) => result.entity === entity2);
+
+    expect(result1?.components[0]).toEqual(pos1);
+    expect(result2?.components[0]).toEqual(pos2);
+  });
+
+  it("should query entities with wildcard relations", () => {
+    const world = new World();
+    const entity1 = world.new();
+    const entity2 = world.new();
+    const entity3 = world.new();
+
+    // Create a wildcard relation for position component
+    const wildcardPositionRelation = relation(markComponent, "*");
+
+    world.set(entity1, relation(markComponent, positionComponent), { x: 1, y: 2 });
+    world.set(entity1, relation(markComponent, velocityComponent), { x: 0.1, y: 0.2 });
+
+    world.set(entity2, relation(markComponent, positionComponent), { x: 3, y: 4 });
+
+    world.set(entity3, positionComponent, { x: 5, y: 6 });
+
+    // entity3 has no position component
+
+    world.sync(); // Execute deferred commands
+
+    // Query with wildcard relation should find all entities with position component
+    const wildcardEntities = world.query([wildcardPositionRelation]);
+    expect(wildcardEntities).toContain(entity1);
+    expect(wildcardEntities).toContain(entity2);
+    expect(wildcardEntities).not.toContain(entity3);
+  });
+
+  it("should query entities with mixed component and wildcard relation queries", () => {
+    const world = new World();
+    const entity1 = world.new();
+    const entity2 = world.new();
+    const entity3 = world.new();
+
+    // Create a wildcard relation for position component
+    const wildcardPositionRelation = relation(markComponent, "*");
+
+    world.set(entity1, relation(markComponent, positionComponent), { x: 1, y: 2 });
+    world.set(entity1, velocityComponent, { x: 0.1, y: 0.2 });
+
+    world.set(entity2, relation(markComponent, positionComponent), { x: 3, y: 4 });
+    // entity2 doesn't have velocity
+
+    world.set(entity3, velocityComponent, { x: 0.5, y: 0.6 });
+    // entity3 doesn't have position
+
+    world.sync(); // Execute deferred commands
+
+    // Query with both velocity component and wildcard position relation
+    // Should only match entity1 (has both position and velocity)
+    const mixedEntities = world.query([velocityComponent, wildcardPositionRelation]);
+    expect(mixedEntities).toContain(entity1);
+    expect(mixedEntities).not.toContain(entity2);
+    expect(mixedEntities).not.toContain(entity3);
+  });
+
+  it("should clean up relation components when target entity is destroyed", () => {
+    const world = new World();
+
+    // Create component IDs
+    const positionComponent = component<{ x: number; y: number }>();
+    const followsComponent = component<void>();
+
+    // Create entities
+    const entity1 = world.new(); // This will be followed
+    const entity2 = world.new(); // This will follow entity1
+    const entity3 = world.new(); // This will also follow entity1
+
+    // Add position to entity1
+    world.set(entity1, positionComponent, { x: 10, y: 20 });
+    world.sync();
+
+    // Create relation components (entity2 and entity3 follow entity1)
+    const followsEntity1 = relation(followsComponent, entity1);
+    world.set(entity2, followsEntity1);
+    world.set(entity3, followsEntity1);
+    world.sync();
+    // Add twice to test idempotency
+    world.set(entity2, followsEntity1);
+    world.set(entity3, followsEntity1);
+    world.sync();
+
+    // Verify relations exist
+    expect(world.has(entity2, followsEntity1)).toBe(true);
+    expect(world.has(entity3, followsEntity1)).toBe(true);
+
+    // Query entities that follow entity1
+    const followers = world.query([followsEntity1]);
+    expect(followers).toContain(entity2);
+    expect(followers).toContain(entity3);
+
+    // Destroy entity1
+    world.delete(entity1);
+    world.sync();
+
+    // Verify entity1 is destroyed
+    expect(world.exists(entity1)).toBe(false);
+
+    // Verify relation components are cleaned up
+    expect(world.has(entity2, followsEntity1)).toBe(false);
+    expect(world.has(entity3, followsEntity1)).toBe(false);
+
+    // Query should now return empty
+    const followersAfterDestroy = world.query([followsEntity1]);
+    expect(followersAfterDestroy).toHaveLength(0);
+
+    // entity2 and entity3 should still exist but without the relation components
+    expect(world.exists(entity2)).toBe(true);
+    expect(world.exists(entity3)).toBe(true);
+  });
+
+  it("should clean up components when entity is used directly as component type and destroyed", () => {
+    const world = new World();
+
+    // Create entities
+    const entity1 = world.new(); // This will be used as component type
+    const entity2 = world.new(); // This will have entity1 as component
+
+    // Add entity1 directly as a component type to entity2
+    world.set(entity2, entity1);
+    world.sync();
+
+    // Verify the component exists
+    expect(world.has(entity2, entity1)).toBe(true);
+
+    // Query entities that have entity1 as component
+    const entitiesWithComponent = world.query([entity1]);
+    expect(entitiesWithComponent).toContain(entity2);
+
+    // Destroy entity1
+    world.delete(entity1);
+    world.sync();
+
+    // Verify entity1 is destroyed
+    expect(world.exists(entity1)).toBe(false);
+
+    // Verify the component is cleaned up
+    expect(world.has(entity2, entity1)).toBe(false);
+
+    // Query should now return empty
+    const entitiesWithComponentAfterDestroy = world.query([entity1]);
+    expect(entitiesWithComponentAfterDestroy).toHaveLength(0);
+
+    // entity2 should still exist
+    expect(world.exists(entity2)).toBe(true);
+  });
+});

package/src/__tests__/world/serialize.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation, type EntityId } from "../../entity";
+import { World } from "../../world/world";
+
+describe("World serialization", () => {
+  it("should serialize and deserialize a world with components and relations", () => {
+    type Position = { x: number; y: number };
+
+    const PositionComp = component<Position>("position");
+    const HealthComp = component<number>("health");
+
+    const world = new World();
+
+    // Create entities
+    const e1 = world.new();
+    const e2 = world.new();
+    const e3 = world.new();
+
+    // Add components
+    const p1: Position = { x: 1, y: 2 };
+    const p2: Position = { x: 3, y: 4 };
+
+    world.set(e1, PositionComp, p1);
+    world.set(e2, PositionComp, p2);
+    world.set(e2, HealthComp, 99);
+
+    // Add relation component on e3 pointing to e1 and e2
+    const relToE1 = relation(PositionComp, e1);
+    const relToE2 = relation(PositionComp, e2);
+    world.set(e3, relToE1, { x: 10, y: 20 });
+    world.set(e3, relToE2, { x: 30, y: 40 });
+
+    world.sync();
+
+    // Serialize (returns an in-memory snapshot, not a JSON string)
+    const snapshot = world.serialize();
+
+    // Restore by constructing World with snapshot
+    const restored = new World(snapshot);
+
+    // Basic existence
+    expect(restored.exists(e1)).toBe(true);
+    expect(restored.exists(e2)).toBe(true);
+    expect(restored.exists(e3)).toBe(true);
+
+    // Components restored
+    expect(restored.get(e1, PositionComp)).toEqual(p1);
+    expect(restored.get(e2, PositionComp)).toEqual(p2);
+    expect(restored.get(e2, HealthComp)).toEqual(99);
+
+    // Relations restored
+    expect(restored.has(e3, relToE1)).toBe(true);
+    expect(restored.has(e3, relToE2)).toBe(true);
+
+    // Wildcard query returns both relations; check contents irrespective of order
+    const wildcard = relation(PositionComp, "*") as EntityId<any>;
+    const relations = restored.get(e3, wildcard) as [EntityId, any][];
+    const targets = relations.map((r) => r[0]);
+    expect(targets).toContain(e1);
+    expect(targets).toContain(e2);
+
+    const pair1 = relations.find((r) => r[0] === e1);
+    const pair2 = relations.find((r) => r[0] === e2);
+    expect(pair1).toBeDefined();
+    expect(pair2).toBeDefined();
+    expect(pair1![1]).toEqual({ x: 10, y: 20 });
+    expect(pair2![1]).toEqual({ x: 30, y: 40 });
+  });
+
+  it("should preserve entity id allocator state across serialization", () => {
+    const world = new World();
+    world.new();
+    const b = world.new();
+    world.sync();
+
+    const snapshot = world.serialize();
+    const restored = new World(snapshot);
+
+    // Next allocated id after restore should be >= the max existing id + 1
+    const c = restored.new();
+    expect(c).toBeGreaterThanOrEqual(b + 1);
+  });
+});

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

@@ -0,0 +1,332 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation, type EntityId } from "../../entity";
+import { World } from "../../world/world";
+
+describe("Wildcard-Relation Hooks", () => {
+  it("should trigger on_set when wildcard relation matches added relation component", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+    const concreteRel = relation(RelData, target);
+
+    const calls: { entityId: EntityId; components: readonly [number, [EntityId, { value: string }][]] }[] = [];
+
+    world.hook([A, wildcardRel], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    // Create entity with both A and a concrete relation
+    const entity = world.spawn().with(A, 42).with(concreteRel, { value: "hello" }).build();
+    world.sync();
+
+    expect(calls.length).toBe(1);
+    expect(calls[0]!.entityId).toBe(entity);
+    expect(calls[0]!.components[0]).toBe(42);
+    expect(calls[0]!.components[1]).toEqual([[target, { value: "hello" }]]);
+  });
+
+  it("should trigger on_set when adding a new relation that matches wildcard", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target1 = world.new();
+    const target2 = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const calls: { entityId: EntityId; components: readonly [number, [EntityId, { value: string }][]] }[] = [];
+
+    world.hook([A, wildcardRel], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    // First, create entity with A and one relation
+    const entity = world.spawn().with(A, 42).with(relation(RelData, target1), { value: "first" }).build();
+    world.sync();
+
+    expect(calls.length).toBe(1);
+
+    // Add another relation - should trigger again
+    world.set(entity, relation(RelData, target2), { value: "second" });
+    world.sync();
+
+    expect(calls.length).toBe(2);
+    // Check that both relations are present (order may vary)
+    const relations = calls[1]!.components[1] as [EntityId, { value: string }][];
+    expect(relations.length).toBe(2);
+    expect(relations).toContainEqual([target1, { value: "first" }]);
+    expect(relations).toContainEqual([target2, { value: "second" }]);
+  });
+
+  it("should not trigger on_set when wildcard relation requirement not met", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const wildcardRel = relation(RelData, "*");
+
+    const calls: any[] = [];
+
+    world.hook([A, wildcardRel], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    // Create entity with only A, no relation
+    const entity = world.spawn().with(A, 42).build();
+    world.sync();
+
+    expect(calls.length).toBe(0);
+    expect(world.has(entity, A)).toBe(true);
+  });
+
+  it("should trigger on_remove when wildcard relation matches removed relation component", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+    const concreteRel = relation(RelData, target);
+
+    const removeCalls: { entityId: EntityId; components: any }[] = [];
+
+    world.hook([A, wildcardRel], {
+      on_remove: (entityId, ...components) => {
+        removeCalls.push({ entityId, components });
+      },
+    });
+
+    const entity = world.spawn().with(A, 42).with(concreteRel, { value: "hello" }).build();
+    world.sync();
+
+    // Remove the relation
+    world.remove(entity, concreteRel);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+  });
+
+  it("should support optional wildcard relation in multi-hook", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+    const concreteRel = relation(RelData, target);
+
+    const calls: { entityId: EntityId; components: any }[] = [];
+
+    world.hook([A, { optional: wildcardRel }], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    // Create entity with only A
+    const entity = world.spawn().with(A, 42).build();
+    world.sync();
+
+    expect(calls.length).toBe(1);
+    expect(calls[0]!.components).toEqual([42, undefined]);
+
+    // Add a relation
+    world.set(entity, concreteRel, { value: "hello" });
+    world.sync();
+
+    expect(calls.length).toBe(2);
+    expect(calls[1]!.components[0]).toBe(42);
+    expect(calls[1]!.components[1]).toEqual({ value: [[target, { value: "hello" }]] });
+  });
+
+  it("should trigger on_set with multiple wildcard relations", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData1 = component<{ x: number }>();
+    const RelData2 = component<{ y: number }>();
+    const target1 = world.new();
+    const target2 = world.new();
+    const wildcardRel1 = relation(RelData1, "*");
+    const wildcardRel2 = relation(RelData2, "*");
+
+    const calls: { entityId: EntityId; components: any }[] = [];
+
+    world.hook([A, wildcardRel1, wildcardRel2], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    const entity = world
+      .spawn()
+      .with(A, 42)
+      .with(relation(RelData1, target1), { x: 10 })
+      .with(relation(RelData2, target2), { y: 20 })
+      .build();
+    world.sync();
+
+    expect(calls.length).toBe(1);
+    expect(calls[0]!.entityId).toBe(entity);
+    expect(calls[0]!.components[0]).toBe(42);
+    expect(calls[0]!.components[1]).toEqual([[target1, { x: 10 }]]);
+    expect(calls[0]!.components[2]).toEqual([[target2, { y: 20 }]]);
+  });
+
+  it("should not match unrelated relation components with wildcard", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData1 = component<{ x: number }>();
+    const RelData2 = component<{ y: number }>();
+    const target = world.new();
+    const wildcardRel1 = relation(RelData1, "*");
+
+    const calls: any[] = [];
+
+    world.hook([A, wildcardRel1], {
+      on_set: (entityId, ...components) => {
+        calls.push({ entityId, components });
+      },
+    });
+
+    // Create entity with A and a different relation type
+    const entity = world.spawn().with(A, 42).with(relation(RelData2, target), { y: 20 }).build();
+    world.sync();
+
+    // Should not trigger because RelData2 doesn't match RelData1's wildcard
+    expect(calls.length).toBe(0);
+    expect(world.has(entity, A)).toBe(true);
+  });
+
+  it("should trigger on_set when only wildcard relation specified as single required component", () => {
+    const world = new World();
+    const RelData = component<{ value: string }>();
+    const target1 = world.new();
+    const target2 = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const setCalls: { entityId: EntityId; relations: [EntityId, { value: string }][] }[] = [];
+
+    world.hook([wildcardRel], {
+      on_set: (entityId, relations) => {
+        setCalls.push({ entityId, relations });
+      },
+    });
+
+    // Create entity with a matching relation
+    const entity = world.spawn().with(relation(RelData, target1), { value: "first" }).build();
+    world.sync();
+
+    expect(setCalls.length).toBe(1);
+    expect(setCalls[0]!.entityId).toBe(entity);
+    expect(setCalls[0]!.relations).toEqual([[target1, { value: "first" }]]);
+
+    // Add another matching relation - should trigger again
+    world.set(entity, relation(RelData, target2), { value: "second" });
+    world.sync();
+
+    expect(setCalls.length).toBe(2);
+    expect(setCalls[1]!.entityId).toBe(entity);
+    const relations = setCalls[1]!.relations;
+    expect(relations.length).toBe(2);
+    expect(relations).toContainEqual([target1, { value: "first" }]);
+    expect(relations).toContainEqual([target2, { value: "second" }]);
+  });
+
+  it("should trigger on_remove when only wildcard relation specified and last relation removed", () => {
+    const world = new World();
+    const RelData = component<{ value: string }>();
+    const target1 = world.new();
+    const target2 = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const removeCalls: { entityId: EntityId; relations: [EntityId, { value: string }][] }[] = [];
+
+    world.hook([wildcardRel], {
+      on_remove: (entityId, relations) => {
+        removeCalls.push({ entityId, relations });
+      },
+    });
+
+    // Create entity with two matching relations
+    const entity = world
+      .spawn()
+      .with(relation(RelData, target1), { value: "first" })
+      .with(relation(RelData, target2), { value: "second" })
+      .build();
+    world.sync();
+
+    // Remove one relation - should NOT trigger on_remove (still has other matching relations)
+    world.remove(entity, relation(RelData, target1));
+    world.sync();
+
+    expect(removeCalls.length).toBe(0);
+    expect(world.has(entity, relation(RelData, target2))).toBe(true);
+
+    // Remove the last matching relation - should trigger on_remove now
+    world.remove(entity, relation(RelData, target2));
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    // The callback receives array format with the removed relation
+    expect(removeCalls[0]!.relations).toEqual([[target2, { value: "second" }]]);
+  });
+
+  it("should trigger on_init when only wildcard relation specified for existing matching entities", () => {
+    const world = new World();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    // Create entity with a matching relation before hook
+    const entity = world.spawn().with(relation(RelData, target), { value: "existing" }).build();
+    world.sync();
+
+    const initCalls: { entityId: EntityId; relations: [EntityId, { value: string }][] }[] = [];
+
+    // Register hook - should trigger on_init for existing entity
+    world.hook([wildcardRel], {
+      on_init: (entityId, relations) => {
+        initCalls.push({ entityId, relations });
+      },
+    });
+
+    expect(initCalls.length).toBe(1);
+    expect(initCalls[0]!.entityId).toBe(entity);
+    expect(initCalls[0]!.relations).toEqual([[target, { value: "existing" }]]);
+  });
+
+  it("should not trigger when only wildcard relation specified and entity has no matching relations", () => {
+    const world = new World();
+    const RelData = component<{ value: string }>();
+    const OtherData = component<{ other: number }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const setCalls: any[] = [];
+
+    world.hook([wildcardRel], {
+      on_set: (entityId, relations) => {
+        setCalls.push({ entityId, relations });
+      },
+    });
+
+    // Create entity with no relations
+    const entity1 = world.spawn().build();
+    world.sync();
+
+    // Create entity with a different relation type
+    const entity2 = world.spawn().with(relation(OtherData, target), { other: 42 }).build();
+    world.sync();
+
+    // Neither should trigger the hook
+    expect(setCalls.length).toBe(0);
+    expect(world.exists(entity1)).toBe(true);
+    expect(world.exists(entity2)).toBe(true);
+  });
+});