@codehz/ecs 0.8.2 → 0.10.0

package/examples/debug-observability.ts

@@ -0,0 +1,92 @@
+/**
+ * Example: Using the Debug Stats Collector for development & leak detection.
+ *
+ * Run with:
+ *   bun run examples/debug-observability.ts
+ */
+
+import { component, relation, World } from "../src";
+
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+
+// Components
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+
+const world = new World();
+
+// Create a debug stats collector
+const collector = world.createDebugStatsCollector((stats) => {
+  console.log("=== Debug Stats ===");
+  console.log(`Sync time: ${(stats.timestamps.syncEnd - stats.timestamps.syncStart).toFixed(3)}ms`);
+  console.log(`Command buffer iterations: ${stats.commandIterations}`);
+  console.log(`Entities: ${stats.entities.total} (freelist: ${stats.entities.freelistSize})`);
+  console.log(`Archetypes: ${stats.archetypes.total} (empty: ${stats.archetypes.empty})`);
+  console.log(`Queries (cached/registered): ${stats.queries.cached}/${stats.queries.registered}`);
+  console.log(`Hooks: ${stats.hooks.total}`);
+  console.log(`Indices:`, stats.indices);
+
+  const act = stats.activity;
+  console.log("Activity this sync:");
+  console.log(`  Migrations: ${act.migrations}`);
+  console.log(`  Hooks executed: ${act.hooksExecuted}`);
+  console.log(`  Archetypes created: ${act.archetypesCreated}`);
+  console.log(`  Archetypes removed: ${act.archetypesRemoved}`);
+  console.log("===================\n");
+});
+
+// Setup some entities
+const parent = world.new();
+world.set(parent, Position, { x: 0, y: 0 });
+
+const children: any[] = [];
+for (let i = 0; i < 5; i++) {
+  const child = world.new();
+  world.set(child, Position, { x: i * 10, y: 0 });
+  world.set(child, Velocity, { x: 1, y: 0.5 });
+  world.set(child, relation(ChildOf, parent));
+  children.push(child);
+}
+
+console.log("Initial sync (should create archetypes + relations)");
+world.sync();
+
+// Cause some migrations by adding/removing components
+console.log("Adding/removing components to trigger migrations...");
+for (const c of children) {
+  world.remove(c, Velocity);
+}
+world.sync();
+
+world.set(children[0], Velocity, { x: 2, y: 0 });
+world.sync();
+
+// Add a hook to observe hook execution counting
+world.hook([Position, Velocity], {
+  on_set: () => {},
+});
+
+console.log("Triggering hook + more structural changes");
+world.set(children[1], Velocity, { x: 3, y: 1 });
+world.sync();
+
+// Clean up some entities to potentially remove archetypes
+console.log("Deleting some children...");
+world.delete(children[2]);
+world.delete(children[3]);
+world.sync();
+
+// Dispose the collector when done
+collector[Symbol.dispose]();
+
+console.log("Collector disposed. Further syncs will not trigger callbacks.");
+world.set(parent, Position, { x: 100, y: 100 });
+world.sync();
+
+console.log("Done. This demonstrates typical usage for spotting:");
+console.log("- Unexpected archetype growth (fragmentation)");
+console.log("- High migration or hook execution counts");
+console.log("- Command buffer iteration spikes");
+console.log("- Leaking entities or relations (watch entity/freelist numbers over time)");

package/examples/inventory-system-relations.ts

@@ -9,7 +9,7 @@ const ItemName = component<ItemName>({ name: "ItemName" });
 const Stackable = component<Stackable>({ name: "Stackable" });
 const Gold = component<Gold>({ name: "Gold" });
 const EquipmentSlot = component<EquipmentSlot>({ name: "EquipmentSlot" });
-const InInventory = component<void>({ name: "InInventory", dontFragment: true });
+const InInventory = component<void>({ name: "InInventory", sparse: true });
 
 const world = new World();
 

package/examples/parent-child-hierarchy.ts

@@ -1,5 +1,5 @@
 import { pipeline } from "@codehz/pipeline";
-import { World, component, relation, type EntityId, type Query } from "../src";
+import { World, component, relation, type Query } from "../src";
 
 // Define component types
 type Transform = { x: number; y: number; rotation: number; scale: number };
@@ -13,7 +13,7 @@ const LocalTransform = component<Transform>({ name: "LocalTransform" });
 const WorldTransform = component<Transform>({ name: "WorldTransform" });
 const LinearVelocity = component<LinearVelocity>({ name: "LinearVelocity" });
 const AngularVelocity = component<AngularVelocity>({ name: "AngularVelocity" });
-const ChildOf = component<void>({ exclusive: true, dontFragment: true, name: "ChildOf" });
+const ChildOf = component<void>({ exclusive: true, sparse: true, name: "ChildOf" });
 
 // Create the world
 const world = new World();
@@ -22,7 +22,6 @@ const world = new World();
 const movementQuery: Query = world.createQuery([LocalTransform, LinearVelocity]);
 const rotationQuery: Query = world.createQuery([LocalTransform, AngularVelocity]);
 const transformQuery: Query = world.createQuery([Name, LocalTransform, WorldTransform]);
-const childQuery: Query = world.createQuery([relation(ChildOf, "*")]);
 const renderQuery: Query = world.createQuery([Name, WorldTransform]);
 
 function toRadians(degrees: number): number {
@@ -59,38 +58,9 @@ function formatTransform(transform: Transform): string {
   return `pos=(${transform.x.toFixed(2)}, ${transform.y.toFixed(2)}) rot=${transform.rotation.toFixed(1)}deg scale=${transform.scale.toFixed(2)}`;
 }
 
-function buildChildrenByParent(): Map<EntityId, EntityId[]> {
-  const childrenByParent = new Map<EntityId, EntityId[]>();
-
-  childQuery.forEach([relation(ChildOf, "*")], (child, parents) => {
-    const parent = parents[0]?.[0];
-    if (parent === undefined) return;
-
-    const children = childrenByParent.get(parent) ?? [];
-    children.push(child);
-    childrenByParent.set(parent, children);
-  });
-
-  return childrenByParent;
-}
-
-function propagateChildren(
-  parent: EntityId,
-  parentWorld: Transform,
-  childrenByParent: Map<EntityId, EntityId[]>,
-): void {
-  const children = childrenByParent.get(parent);
-  if (!children) return;
-
-  for (const child of children) {
-    const name = world.get(child, Name);
-    const local = world.get(child, LocalTransform);
-    const worldTransform = world.get(child, WorldTransform);
-    copyTransform(worldTransform, composeTransform(local, parentWorld));
-    console.log(`  Child ${name.value}: ${formatTransform(worldTransform)}`);
-    propagateChildren(child, worldTransform, childrenByParent);
-  }
-}
+// NOTE: Before the relation/hierarchy companion tools, this required manually
+// building a children map every frame + writing recursive propagation.
+// Now we can use the built-in efficient helpers (getChildren + traverseDescendants).
 
 // Build game loop using pipeline
 // Pass execution order is determined by addition order; no need to manually manage dependencies
@@ -115,16 +85,26 @@ const gameLoop = pipeline<{ deltaTime: number }>()
     });
   })
   // Hierarchy pass - propagate parent transforms into world transforms
+  // (modernized with the new relation/hierarchy companion tools)
   .addPass(() => {
     console.log(`[HierarchyPass] Propagating world transforms`);
-    const childrenByParent = buildChildrenByParent();
 
     transformQuery.forEach([Name, LocalTransform, WorldTransform], (entity, name, localTransform, worldTransform) => {
-      if (world.has(entity, relation(ChildOf, "*"))) return;
+      if (world.has(entity, relation(ChildOf, "*"))) return; // skip non-roots
 
       copyTransform(worldTransform, composeTransform(localTransform));
       console.log(`  Root ${name.value}: ${formatTransform(worldTransform)}`);
-      propagateChildren(entity, worldTransform, childrenByParent);
+
+      // Use the efficient built-in traverser (replaces manual Map + recursion)
+      world.traverseDescendants(entity, ChildOf, (child, _depth, parent) => {
+        if (!parent) return;
+        const childName = world.get(child, Name);
+        const local = world.get(child, LocalTransform);
+        const childWorld = world.get(child, WorldTransform);
+        const parentWorldT = world.get(parent, WorldTransform);
+        copyTransform(childWorld, composeTransform(local, parentWorldT));
+        console.log(`  Child ${childName.value}: ${formatTransform(childWorld)}`);
+      });
     });
   })
   // Render pass - render propagated world transforms

package/examples/spatial-grid.ts

@@ -216,7 +216,7 @@ function main() {
   console.log("=========================================================\n");
 
   // Create singleton SpatialGrid
-  world.set(SpatialGrid, { cells: new Map(), cellSize: 64 });
+  world.singleton(SpatialGrid).set({ cells: new Map(), cellSize: 64 });
   console.log("SpatialGrid singleton created (cellSize=64)");
 
   // Create 1 player near the center

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "license": "MIT",
   "module": "src/index.ts",
   "type": "module",

package/skills/ecs/SKILL.md

@@ -34,7 +34,7 @@ The library uses **archetype storage + deferred command buffering**. All structu
 7. **NEVER** call `sync()` inside `forEach`, hooks, or while iterating query results.
 8. **NEVER** confuse `remove(entity, Component)` with `delete(entity)`.
 9. **MUST** use relation components (`relation(Comp, target)`) instead of storing `EntityId` in data when you need to reference other entities.
-10. **MUST** understand the three relation flags (`exclusive`, `cascadeDelete`, `dontFragment`) before using relations.
+10. **MUST** understand the three relation flags (`exclusive`, `cascadeDelete`, `sparse` / legacy `dontFragment`) before using relations.
 
 ---
 
@@ -205,7 +205,7 @@ Use `relation(Component, target)` to create entity-to-entity references.
 - When the target entity is deleted, **the entire referencing entity is deleted**.
 - This is transitive and powerful. Use deliberately.
 
-**`dontFragment: true`**
+**`sparse: true`** (preferred; legacy key `dontFragment` is fully equivalent and supported)
 
 - Prevents archetype fragmentation when many different targets exist.
 - **Required** for relations with high cardinality or frequent target changes (e.g. `ChildOf` with thousands of children, AI targeting, inventory).
@@ -214,8 +214,8 @@ Use `relation(Component, target)` to create entity-to-entity references.
 
 ```ts
 const ChildOf = component({ exclusive: true, cascadeDelete: true });
-const Targeting = component({ exclusive: true, dontFragment: true });
-const InventorySlot = component({ dontFragment: true });
+const Targeting = component({ exclusive: true, sparse: true });
+const InventorySlot = component({ sparse: true });
 ```
 
 ### 8. Referencing Other Entities — Never Store Raw EntityId

package/src/__tests__/component/singleton.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { component } from "../../entity";
+import { ComponentEntityStore } from "../../component/entity-store";
+import { component, createEntityId, relation, type EntityId } from "../../entity";
 import { World } from "../../world/world";
 
 describe("World - Singleton Component", () => {
@@ -9,29 +10,82 @@ describe("World - Singleton Component", () => {
   const GlobalConfigId = component<GlobalConfig>();
   const GameStateId = component<GameState>();
 
-  it("should set singleton component using shorthand syntax", () => {
+  it("should set singleton component through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    // Use singleton syntax: set(componentId, data)
-    world.set(GlobalConfigId, config);
+    singleton.set(config);
     world.sync();
 
-    // Verify it was set on the component entity itself
     expect(world.has(GlobalConfigId)).toBe(true);
     expect(world.get(GlobalConfigId)).toEqual(config);
   });
 
-  it("should update singleton component using shorthand syntax", () => {
+  it("should interpret 2-argument set on a component entity as a void component set", () => {
+    const world = new World();
+    const singleton = world.singleton(GlobalConfigId);
+    const Marker = component<void>();
+
+    world.set(GlobalConfigId, Marker);
+    world.sync();
+
+    expect(world.has(GlobalConfigId, Marker)).toBe(true);
+    expect(singleton.has()).toBe(false);
+  });
+
+  it("should reject the removed singleton data shorthand at runtime", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    expect(() => {
+      world.set(GlobalConfigId as any, config as any);
+    }).toThrow("Invalid component type");
+  });
+
+  it("should manage singleton data through an explicit handle", () => {
+    const world = new World();
+    const config = world.singleton(GlobalConfigId);
+
+    expect(config.getOptional()).toBeUndefined();
+    expect(config.has()).toBe(false);
+
+    config.set({ debug: true, version: "1.0.0" });
+    world.sync();
+
+    expect(config.has()).toBe(true);
+    expect(config.get()).toEqual({ debug: true, version: "1.0.0" });
+
+    config.remove();
+    world.sync();
+
+    expect(config.has()).toBe(false);
+    expect(config.getOptional()).toBeUndefined();
+  });
+
+  it("should support void singleton components through an explicit handle", () => {
+    const world = new World();
+    const Tag = component<void>();
+    const tag = world.singleton(Tag);
+
+    tag.set();
+    world.sync();
+
+    expect(tag.has()).toBe(true);
+    expect(world.has(Tag)).toBe(true);
+  });
+
+  it("should update singleton component through the explicit handle", () => {
     const world = new World();
     const config1: GlobalConfig = { debug: true, version: "1.0.0" };
     const config2: GlobalConfig = { debug: false, version: "2.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    world.set(GlobalConfigId, config1);
+    singleton.set(config1);
     world.sync();
     expect(world.get(GlobalConfigId)).toEqual(config1);
 
-    world.set(GlobalConfigId, config2);
+    singleton.set(config2);
     world.sync();
     expect(world.get(GlobalConfigId)).toEqual(config2);
   });
@@ -41,15 +95,12 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Singleton syntax
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(config);
     world1.sync();
 
-    // Traditional syntax
     world2.set(GlobalConfigId, GlobalConfigId, config);
     world2.sync();
 
-    // Both should have the same result
     expect(world1.get(GlobalConfigId)).toEqual(world2.get(GlobalConfigId));
   });
 
@@ -58,8 +109,8 @@ describe("World - Singleton Component", () => {
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
     const state: GameState = { score: 100, level: 5 };
 
-    world.set(GlobalConfigId, config);
-    world.set(GameStateId, state);
+    world.singleton(GlobalConfigId).set(config);
+    world.singleton(GameStateId).set(state);
     world.sync();
 
     expect(world.get(GlobalConfigId)).toEqual(config);
@@ -77,19 +128,17 @@ describe("World - Singleton Component", () => {
     }).toThrow("does not exist");
   });
 
-  it("should check singleton component existence using shorthand syntax", () => {
+  it("should check singleton component existence through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    // Before setting, should return false
-    expect(world.has(GlobalConfigId)).toBe(false);
+    expect(singleton.has()).toBe(false);
 
-    // Set singleton component
-    world.set(GlobalConfigId, config);
+    singleton.set(config);
     world.sync();
 
-    // After setting, should return true
-    expect(world.has(GlobalConfigId)).toBe(true);
+    expect(singleton.has()).toBe(true);
   });
 
   it("should be equivalent to has(comp, comp)", () => {
@@ -97,29 +146,26 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Singleton syntax
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(config);
     world1.sync();
 
-    // Traditional syntax
     world2.set(GlobalConfigId, GlobalConfigId, config);
     world2.sync();
 
-    // Both should have the same result
     expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
     expect(world1.has(GlobalConfigId)).toBe(true);
   });
 
-  it("should remove singleton component using shorthand syntax", () => {
+  it("should remove singleton component through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    world.set(GlobalConfigId, config);
+    singleton.set(config);
     world.sync();
     expect(world.has(GlobalConfigId)).toBe(true);
 
-    // Remove using singleton syntax
-    world.remove(GlobalConfigId);
+    singleton.remove();
     world.sync();
     expect(world.has(GlobalConfigId)).toBe(false);
   });
@@ -129,20 +175,55 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Set on both worlds
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(config);
     world1.sync();
     world2.set(GlobalConfigId, GlobalConfigId, config);
     world2.sync();
 
-    // Remove using different syntax
-    world1.remove(GlobalConfigId); // Singleton syntax
-    world2.remove(GlobalConfigId, GlobalConfigId); // Traditional syntax
+    world1.singleton(GlobalConfigId).remove();
+    world2.remove(GlobalConfigId, GlobalConfigId);
     world1.sync();
     world2.sync();
 
-    // Both should have the same result
     expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
     expect(world1.has(GlobalConfigId)).toBe(false);
   });
+
+  it("should cover ComponentEntityStore hasWildcard, getWildcard, wildcard delete paths", () => {
+    const store = new ComponentEntityStore();
+    const compE = GlobalConfigId as EntityId; // reuse as component entity id (valid in range)
+    const target1 = createEntityId(1024);
+    const target2 = createEntityId(1025);
+    const relComp = relation(GlobalConfigId, target1); // entity-relation on the comp entity
+    const relComp2 = relation(GlobalConfigId, target2);
+    const wildcard = relation(GlobalConfigId, "*");
+
+    // Setup via internal? Use executeCommands to populate (simulates)
+    store.executeCommands(compE, [
+      { type: "set", componentType: relComp, component: { dist: 1 } } as any,
+      { type: "set", componentType: relComp2, component: { dist: 2 } } as any,
+    ]);
+
+    // hasWildcard
+    expect(store.hasWildcard(compE, GlobalConfigId as any)).toBe(true);
+    expect(store.hasWildcard(compE, GameStateId as any)).toBe(false);
+    expect(store.hasWildcard(createEntityId(9999), GlobalConfigId as any)).toBe(false); // no data
+
+    // getWildcard
+    const w1 = store.getWildcard(compE, wildcard as any);
+    expect(w1.length).toBe(2);
+
+    // wildcard delete via executeCommands
+    store.executeCommands(compE, [{ type: "delete", componentType: wildcard } as any]);
+    const afterDel = store.getWildcard(compE, wildcard as any);
+    expect(afterDel.length).toBe(0);
+
+    // also test get on non exist throws
+    expect(() => store.get(compE, createEntityId(5000) as any)).toThrow();
+    expect(store.getOptional(compE, createEntityId(5000) as any)).toBeUndefined();
+
+    // clear
+    store.clear(compE);
+    expect(store.has(compE, relComp)).toBe(false);
+  });
 });