@codehz/ecs 0.7.2 → 0.7.3

package/examples/serialization.ts

@@ -0,0 +1,337 @@
+import type { EntityId, SerializedWorld } from "../src";
+import { World, component } from "../src";
+
+// Define component types
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+type Health = { value: number; maxValue: number };
+type Name = { value: string };
+
+// Define component IDs
+const Position = component<Position>("Position");
+const Velocity = component<Velocity>("Velocity");
+const Health = component<Health>("Health");
+const Name = component<Name>("Name");
+
+// Helper: print world state by iterating entities that have given components
+function printWorldState(world: World, label: string): void {
+  console.log(`\n=== ${label} ===`);
+
+  // Query all entities that have Position (our "base" component)
+  const results = world.query([Position], true);
+
+  if (results.length === 0) {
+    console.log("  (no entities found)");
+    return;
+  }
+
+  for (const {
+    entity,
+    components: [pos],
+  } of results) {
+    const parts: string[] = [`Entity ${entity}:`, `  Position: (${pos.x}, ${pos.y})`];
+
+    if (world.has(entity, Velocity)) {
+      const vel = world.get(entity, Velocity);
+      parts.push(`  Velocity: (${vel.x}, ${vel.y})`);
+    }
+
+    if (world.has(entity, Health)) {
+      const hp = world.get(entity, Health);
+      parts.push(`  Health: ${hp.value}/${hp.maxValue}`);
+    }
+
+    if (world.has(entity, Name)) {
+      const name = world.get(entity, Name);
+      parts.push(`  Name: "${name.value}"`);
+    }
+
+    console.log(parts.join("\n"));
+  }
+}
+
+// Helper: verify two worlds have equivalent state
+function verifyWorldsMatch(original: World, restored: World): boolean {
+  const origResults = original.query([Position], true);
+  const restResults = restored.query([Position], true);
+
+  if (origResults.length !== restResults.length) {
+    console.error(`  Entity count mismatch: ${origResults.length} vs ${restResults.length}`);
+    return false;
+  }
+
+  for (let i = 0; i < origResults.length; i++) {
+    const orig = origResults[i]!;
+    const rest = restResults[i]!;
+
+    if (orig.entity !== rest.entity) {
+      console.error(`  Entity ID mismatch at index ${i}: ${orig.entity} vs ${rest.entity}`);
+      return false;
+    }
+
+    const posMatch = orig.components[0].x === rest.components[0].x && orig.components[0].y === rest.components[0].y;
+    if (!posMatch) {
+      console.error(`  Position mismatch for entity ${orig.entity}`);
+      return false;
+    }
+
+    // Check optional components
+    const checkComp = (compId: EntityId<any>): boolean => {
+      const origHas = original.has(orig.entity, compId);
+      const restHas = restored.has(rest.entity, compId);
+      if (origHas !== restHas) {
+        console.error(`  Component presence mismatch for entity ${orig.entity}`);
+        return false;
+      }
+      if (origHas && restHas) {
+        const origVal = JSON.stringify(original.get(orig.entity, compId));
+        const restVal = JSON.stringify(restored.get(rest.entity, compId));
+        if (origVal !== restVal) {
+          console.error(`  Component value mismatch for entity ${orig.entity}: ${origVal} vs ${restVal}`);
+          return false;
+        }
+      }
+      return true;
+    };
+    if (!checkComp(Velocity) || !checkComp(Health) || !checkComp(Name)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+// Bonus: Custom encode/decode pattern
+// Instead of relying on JSON.stringify/parse, you can manually build
+// a serialized format. This is useful when you need to:
+// - Integrate with a binary format or custom protocol
+// - Add versioning/metadata beyond the snapshot structure
+// - Transform data during serialization (e.g., compress coordinates)
+interface CustomSaveFormat {
+  meta: {
+    version: number;
+    timestamp: number;
+    entityCount: number;
+  };
+  entities: Array<{
+    id: number;
+    position: { x: number; y: number };
+    velocity?: { x: number; y: number };
+    health?: { value: number; maxValue: number };
+    name?: string;
+  }>;
+}
+
+function customEncode(world: World): CustomSaveFormat {
+  const results = world.query([Position], true);
+  const entities: CustomSaveFormat["entities"] = [];
+
+  for (const {
+    entity,
+    components: [pos],
+  } of results) {
+    const entry: CustomSaveFormat["entities"][number] = {
+      id: entity as number,
+      position: { x: pos.x, y: pos.y },
+    };
+
+    if (world.has(entity, Velocity)) {
+      const vel = world.get(entity, Velocity);
+      entry.velocity = { x: vel.x, y: vel.y };
+    }
+
+    if (world.has(entity, Health)) {
+      const hp = world.get(entity, Health);
+      entry.health = { value: hp.value, maxValue: hp.maxValue };
+    }
+
+    if (world.has(entity, Name)) {
+      const name = world.get(entity, Name);
+      entry.name = name.value;
+    }
+
+    entities.push(entry);
+  }
+
+  return {
+    meta: {
+      version: 1,
+      timestamp: Date.now(),
+      entityCount: entities.length,
+    },
+    entities,
+  };
+}
+
+function customDecode(data: CustomSaveFormat): World {
+  const world = new World();
+
+  for (const entry of data.entities) {
+    const builder = world.spawn().with(Position, entry.position);
+
+    if (entry.velocity) {
+      builder.with(Velocity, entry.velocity);
+    }
+
+    if (entry.health) {
+      builder.with(Health, entry.health);
+    }
+
+    if (entry.name !== undefined) {
+      builder.with(Name, { value: entry.name });
+    }
+
+    builder.build();
+  }
+
+  world.sync();
+  return world;
+}
+
+function main() {
+  console.log("ECS Serialization Demo - Save/Load Roundtrip");
+  console.log("==============================================");
+
+  // =========================================================================
+  // Part 1: Build the original world
+  // =========================================================================
+  console.log("\n[1] Creating original world and spawning entities...");
+
+  const world = new World();
+
+  // Spawn a player entity
+  const player = world
+    .spawn()
+    .with(Position, { x: 0, y: 0 })
+    .with(Velocity, { x: 1, y: 0.5 })
+    .with(Health, { value: 100, maxValue: 100 })
+    .with(Name, { value: "Player" })
+    .build();
+  void player;
+
+  // Spawn an enemy entity
+  const enemy = world
+    .spawn()
+    .with(Position, { x: 50, y: 30 })
+    .with(Velocity, { x: -0.5, y: 0.2 })
+    .with(Health, { value: 50, maxValue: 50 })
+    .with(Name, { value: "Goblin" })
+    .build();
+  void enemy;
+
+  // Spawn a static prop (no velocity, no health)
+  const prop = world.spawn().with(Position, { x: 100, y: 200 }).with(Name, { value: "TreasureChest" }).build();
+  void prop;
+
+  // Apply all deferred commands
+  world.sync();
+
+  printWorldState(world, "Original World State");
+
+  // =========================================================================
+  // Part 2: Serialize to snapshot
+  // =========================================================================
+  console.log("\n[2] Serializing world to snapshot...");
+
+  const snapshot: SerializedWorld = world.serialize();
+
+  console.log("\n=== Snapshot Structure ===");
+  console.log(`  version: ${snapshot.version}`);
+  console.log(`  entityManager.nextId: ${snapshot.entityManager.nextId}`);
+  console.log(`  entities count: ${snapshot.entities.length}`);
+  console.log("  entity IDs:", snapshot.entities.map((e) => e.id).join(", "));
+  console.log(
+    "  components per entity:",
+    snapshot.entities.map((e) => `${e.id}: [${e.components.map((c) => c.type).join(", ")}]`).join(" | "),
+  );
+
+  // =========================================================================
+  // Part 3: JSON roundtrip
+  // =========================================================================
+  console.log("\n[3] JSON serialization roundtrip...");
+
+  const json = JSON.stringify(snapshot);
+  console.log(`  JSON size: ${json.length} bytes`);
+
+  // Print abbreviated JSON
+  if (json.length > 300) {
+    console.log(`  JSON (first 300 chars): ${json.slice(0, 300)}...`);
+  } else {
+    console.log(`  JSON: ${json}`);
+  }
+
+  const parsed = JSON.parse(json);
+  console.log("  Parsed back successfully.");
+
+  // =========================================================================
+  // Part 4: Restore from snapshot
+  // =========================================================================
+  console.log("\n[4] Restoring world from parsed snapshot...");
+
+  const restoredWorld = new World(parsed);
+
+  printWorldState(restoredWorld, "Restored World State");
+
+  // =========================================================================
+  // Part 5: Verify roundtrip integrity
+  // =========================================================================
+  console.log("\n[5] Verifying roundtrip integrity...");
+
+  const match = verifyWorldsMatch(world, restoredWorld);
+  if (match) {
+    console.log("  ✅ Original and restored worlds match exactly!");
+  } else {
+    console.log("  ❌ Mismatch detected between original and restored worlds!");
+  }
+
+  // =========================================================================
+  // Part 6: Bonus - Custom encode/decode pattern
+  // =========================================================================
+  console.log("\n[6] Bonus: Custom encode/decode pattern...");
+
+  // Demonstrate custom encoding (e.g., for a hand-rolled save format)
+  const customData = customEncode(world);
+  console.log("\n=== Custom Save Format ===");
+  console.log(`  Meta: v${customData.meta.version}, ${customData.meta.entityCount} entities`);
+  for (const entry of customData.entities) {
+    const extras: string[] = [];
+    if (entry.velocity) extras.push(`velocity`);
+    if (entry.health) extras.push(`health`);
+    if (entry.name) extras.push(`name`);
+    console.log(
+      `  Entity ${entry.id}: pos(${entry.position.x}, ${entry.position.y})` +
+        (extras.length > 0 ? ` [${extras.join(", ")}]` : ""),
+    );
+  }
+
+  // Restore from custom format
+  const customRestoredWorld = customDecode(customData);
+
+  printWorldState(customRestoredWorld, "Custom-Decoded World State");
+
+  // Verify custom roundtrip (self-consistency: re-encode and compare component data)
+  // Note: entity IDs may differ, so we compare only component content
+  const reEncoded = customEncode(customRestoredWorld);
+  const customMatch =
+    reEncoded.entities.length === customData.entities.length &&
+    reEncoded.entities.every((entry, i) => {
+      const orig = customData.entities[i]!;
+      return (
+        entry.position.x === orig.position.x &&
+        entry.position.y === orig.position.y &&
+        JSON.stringify(entry.velocity) === JSON.stringify(orig.velocity) &&
+        JSON.stringify(entry.health) === JSON.stringify(orig.health) &&
+        entry.name === orig.name
+      );
+    });
+  if (customMatch) {
+    console.log("  ✅ Custom encode/decode roundtrip preserves all component data!");
+  } else {
+    console.log("  ❌ Custom encode/decode mismatch detected!");
+  }
+
+  console.log("\n==============================================");
+  console.log("Serialization demo completed successfully!");
+}
+
+main();

package/examples/simple.ts

@@ -0,0 +1,96 @@
+import { pipeline } from "@codehz/pipeline";
+import { component, relation, World, type Query } from "../src";
+
+// Define component types
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+
+// Define component IDs
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const ChildOf = component({ exclusive: true }); // Exclusive relation component
+
+// Create the world
+const world = new World();
+
+// Pre-cache queries
+const movementQuery: Query = world.createQuery([Position, Velocity]);
+
+// Build game loop using pipeline
+const gameLoop = pipeline<{ deltaTime: number }>()
+  // Movement pass
+  .addPass((env) => {
+    movementQuery.forEach([Position, Velocity], (entity, position, velocity) => {
+      position.x += velocity.x * env.deltaTime;
+      position.y += velocity.y * env.deltaTime;
+      console.log(`Entity ${entity}: Position (${position.x.toFixed(2)}, ${position.y.toFixed(2)})`);
+    });
+  })
+  // Sync pass - must be called as the last pass to execute all deferred commands
+  .addPass(() => {
+    world.sync();
+  })
+  .build();
+
+function main() {
+  console.log("ECS Simple Demo");
+
+  // Create entity 1
+  const entity1 = world.spawn().with(Position, { x: 0, y: 0 }).with(Velocity, { x: 1, y: 0.5 }).build();
+
+  // Create entity 2
+  const entity2 = world.spawn().with(Position, { x: 10, y: 10 }).with(Velocity, { x: -0.5, y: 1 }).build();
+  void entity2;
+
+  // Demonstrate Exclusive Relations
+  console.log("\nExclusive Relations Demo:");
+  const parent1 = world.spawn().build();
+  const parent2 = world.spawn().build();
+  const child = world.spawn().with(relation(ChildOf, parent1)).build();
+
+  // ChildOf is already marked as exclusive in component definition
+
+  world.sync();
+  console.log(`Child has ChildOf(parent1): ${world.has(child, relation(ChildOf, parent1))}`);
+  console.log(`Child has ChildOf(parent2): ${world.has(child, relation(ChildOf, parent2))}`);
+
+  // Add second parent relation - should replace the first
+  world.set(child, relation(ChildOf, parent2));
+  world.sync();
+  console.log(`After adding ChildOf(parent2):`);
+  console.log(`Child has ChildOf(parent1): ${world.has(child, relation(ChildOf, parent1))}`);
+  console.log(`Child has ChildOf(parent2): ${world.has(child, relation(ChildOf, parent2))}`);
+
+  // Register component hooks
+  world.hook([Position], {
+    on_set: (entityId, component) => {
+      console.log(`Component set hook triggered: Entity ${entityId} Position is (${component.x}, ${component.y})`);
+    },
+  });
+
+  world.hook([Velocity], {
+    on_remove: (entityId) => {
+      console.log(`Component remove hook triggered: Entity ${entityId} removed Velocity component`);
+    },
+  });
+
+  // Execute commands to apply component additions
+  world.sync();
+
+  // Run a few update cycles
+  const deltaTime = 1.0; // 1 second
+  for (let i = 0; i < 5; i++) {
+    console.log(`\nUpdate ${i + 1}:`);
+    gameLoop({ deltaTime });
+  }
+
+  // Demonstrate component removal hooks
+  console.log("\nComponent Removal Demo:");
+  world.remove(entity1, Velocity);
+  world.sync();
+
+  console.log("\nDemo completed!");
+}
+
+// Run demo
+main();

package/examples/spatial-grid.ts

@@ -0,0 +1,276 @@
+import { pipeline } from "@codehz/pipeline";
+import { World, component, type EntityId, type Query } from "../src";
+
+// =============================================================================
+// Component Type Definitions
+// =============================================================================
+
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+type GridCell = { cellX: number; cellY: number };
+type SpatialGrid = { cells: Map<string, EntityId[]>; cellSize: number };
+
+// =============================================================================
+// Component ID Definitions
+// =============================================================================
+
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const GridCell = component<GridCell>();
+const Enemy = component(); // void tag
+const Player = component(); // void tag
+const Projectile = component(); // void tag
+const Dead = component(); // void tag (negative filter to exclude dead entities)
+const SpatialGrid = component<SpatialGrid>(); // singleton component
+
+// =============================================================================
+// World & Queries
+// =============================================================================
+
+const world = new World();
+
+// Pre-cache all queries (long-term reuse)
+const movementQuery: Query = world.createQuery([Position, Velocity], {
+  negativeComponentTypes: [Dead],
+});
+const enemyQuery: Query = world.createQuery([Position, Enemy], {
+  negativeComponentTypes: [Dead],
+});
+const playerQuery: Query = world.createQuery([Position, Player], {
+  negativeComponentTypes: [Dead],
+});
+const projectileQuery: Query = world.createQuery([Position, Projectile, Velocity], {
+  negativeComponentTypes: [Dead],
+});
+const gridCellQuery: Query = world.createQuery([Position, GridCell], {
+  negativeComponentTypes: [Dead],
+});
+
+// =============================================================================
+// Per-frame dead-entity tracking (Dead component is buffered; sync happens at
+// the end of the frame, so we use a local set for same-frame cleanup).
+// =============================================================================
+
+const newlyDead = new Set<EntityId>();
+
+// =============================================================================
+// Pipeline Passes
+// =============================================================================
+
+const gameLoop = pipeline<{ deltaTime: number }>()
+  // ---------------------------------------------------------------------------
+  // MovementPass — move all entities by velocity * deltaTime
+  // ---------------------------------------------------------------------------
+  .addPass((env) => {
+    console.log("[MovementPass] Updating positions...");
+    let count = 0;
+    movementQuery.forEach([Position, Velocity], (_entity, position, velocity) => {
+      position.x += velocity.x * env.deltaTime;
+      position.y += velocity.y * env.deltaTime;
+      count++;
+    });
+    console.log(`  Moved ${count} entities`);
+  })
+
+  // ---------------------------------------------------------------------------
+  // GridUpdatePass — rebuild spatial grid
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log("[GridUpdatePass] Rebuilding spatial grid...");
+    const grid = world.get(SpatialGrid);
+    const { cellSize } = grid;
+    grid.cells.clear();
+
+    let count = 0;
+    gridCellQuery.forEach([Position, GridCell], (_entity, position, gridCell) => {
+      const cx = Math.floor(position.x / cellSize);
+      const cy = Math.floor(position.y / cellSize);
+      gridCell.cellX = cx;
+      gridCell.cellY = cy;
+
+      const key = `${cx},${cy}`;
+      const bucket = grid.cells.get(key);
+      if (bucket) {
+        bucket.push(_entity);
+      } else {
+        grid.cells.set(key, [_entity]);
+      }
+      count++;
+    });
+    console.log(`  Grid rebuilt: ${grid.cells.size} cell(s), ${count} entity/ies`);
+  })
+
+  // ---------------------------------------------------------------------------
+  // ProximityCheckPass — check if any enemy is near the player (grid-based)
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log("[ProximityCheckPass] Checking enemy-player proximity...");
+    const playerEntities = playerQuery.getEntities();
+    if (playerEntities.length === 0) {
+      console.log("  No player found — skipping");
+      return;
+    }
+
+    const playerEntity = playerEntities[0]!;
+    const playerPos = world.get(playerEntity, Position);
+    const grid = world.get(SpatialGrid);
+    const { cellSize } = grid;
+    const pcx = Math.floor(playerPos.x / cellSize);
+    const pcy = Math.floor(playerPos.y / cellSize);
+
+    let alerts = 0;
+    enemyQuery.forEach([Position, Enemy], (enemyEntity, enemyPos, _enemy) => {
+      const ecx = Math.floor(enemyPos.x / cellSize);
+      const ecy = Math.floor(enemyPos.y / cellSize);
+
+      // Same or adjacent cell (3x3 neighborhood)
+      if (Math.abs(ecx - pcx) <= 1 && Math.abs(ecy - pcy) <= 1) {
+        console.log(
+          `  ⚠ Player detected! Enemy ${enemyEntity} is nearby ` +
+            `(player cell: ${pcx},${pcy} | enemy cell: ${ecx},${ecy})`,
+        );
+        alerts++;
+      }
+    });
+    console.log(`  Proximity check done: ${alerts} alert(s)`);
+  })
+
+  // ---------------------------------------------------------------------------
+  // ProjectileCheckPass — projectiles hit enemies in the same grid cell
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log("[ProjectileCheckPass] Checking projectile-enemy collisions...");
+    const grid = world.get(SpatialGrid);
+    let hits = 0;
+
+    projectileQuery.forEach([Position, Projectile, Velocity], (projectileEntity, _pos, _proj, _vel) => {
+      const cx = Math.floor(_pos.x / grid.cellSize);
+      const cy = Math.floor(_pos.y / grid.cellSize);
+      const key = `${cx},${cy}`;
+      const bucket = grid.cells.get(key);
+
+      if (!bucket || bucket.length === 0) return;
+
+      // Find an enemy in the same cell
+      for (const otherEntity of bucket) {
+        if (!world.has(otherEntity, Enemy)) continue;
+        if (newlyDead.has(otherEntity as EntityId)) continue; // already dead this frame
+
+        // Hit! Mark both projectile and enemy as Dead
+        world.set(projectileEntity, Dead);
+        world.set(otherEntity, Dead);
+        newlyDead.add(projectileEntity as EntityId);
+        newlyDead.add(otherEntity as EntityId);
+        console.log(
+          `  💥 Hit! Projectile ${projectileEntity} destroyed Enemy ${otherEntity} ` + `in cell (${cx},${cy})`,
+        );
+        hits++;
+        break; // one projectile hits at most one enemy per frame
+      }
+    });
+    console.log(`  Projectile check done: ${hits} hit(s)`);
+  })
+
+  // ---------------------------------------------------------------------------
+  // CleanupPass — delete all entities marked as Dead this frame
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log("[CleanupPass] Removing dead entities...");
+    for (const entity of newlyDead) {
+      world.delete(entity);
+    }
+    const count = newlyDead.size;
+    if (count > 0) {
+      console.log(`  Cleaned up ${count} dead entity/ies`);
+    } else {
+      console.log("  No dead entities to clean up");
+    }
+    newlyDead.clear();
+  })
+
+  // ---------------------------------------------------------------------------
+  // RenderPass — log counts of each entity type
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log("[RenderPass] Entity counts:");
+    const enemies = enemyQuery.getEntities().length;
+    const players = playerQuery.getEntities().length;
+    const projectiles = projectileQuery.getEntities().length;
+    console.log(`  Enemies: ${enemies} | Players: ${players} | Projectiles: ${projectiles}`);
+  })
+
+  // ---------------------------------------------------------------------------
+  // SyncPass — execute all buffered structural changes
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    world.sync();
+  })
+  .build();
+
+// =============================================================================
+// Setup & Main
+// =============================================================================
+
+function main() {
+  console.log("ECS Spatial Grid Demo — Grid-based Proximity & Collision");
+  console.log("=========================================================\n");
+
+  // Create singleton SpatialGrid
+  world.set(SpatialGrid, { cells: new Map(), cellSize: 64 });
+  console.log("SpatialGrid singleton created (cellSize=64)");
+
+  // Create 1 player near the center
+  world.spawn().with(Position, { x: 128, y: 128 }).with(GridCell, { cellX: 0, cellY: 0 }).with(Player).build();
+  console.log("Player spawned at (128, 128)");
+
+  // Create ~5 enemies scattered across grid cells
+  const enemyPositions: [number, number][] = [
+    [64, 64],
+    [200, 60],
+    [50, 180],
+    [192, 192],
+    [256, 100],
+  ];
+  for (const [x, y] of enemyPositions) {
+    world
+      .spawn()
+      .with(Position, { x, y })
+      .with(GridCell, { cellX: 0, cellY: 0 })
+      .with(Velocity, { x: Math.random() * 20 - 10, y: Math.random() * 20 - 10 })
+      .with(Enemy)
+      .build();
+    console.log(`Enemy spawned at (${x}, ${y})`);
+  }
+
+  // Create ~3 projectiles with velocity
+  const projectileData: [number, number, number, number][] = [
+    [64, 70, 30, 0],
+    [128, 128, -40, 0],
+    [30, 180, 50, 10],
+  ];
+  for (const [x, y, vx, vy] of projectileData) {
+    world
+      .spawn()
+      .with(Position, { x, y })
+      .with(GridCell, { cellX: 0, cellY: 0 })
+      .with(Velocity, { x: vx, y: vy })
+      .with(Projectile)
+      .build();
+    console.log(`Projectile spawned at (${x}, ${y}) with velocity (${vx}, ${vy})`);
+  }
+
+  // Execute initial sync to materialize all entities
+  world.sync();
+  console.log("\nInitial sync complete. Starting simulation...\n");
+
+  // Run 4 frames
+  for (let frame = 1; frame <= 4; frame++) {
+    console.log(`--- Frame ${frame} ---`);
+    gameLoop({ deltaTime: 1.0 });
+    console.log();
+  }
+
+  console.log("Demo completed!");
+}
+
+main();