@codehz/ecs 0.7.2 → 0.7.4

package/examples/advanced-scheduling.ts

@@ -0,0 +1,96 @@
+import { pipeline } from "@codehz/pipeline";
+import { World, component, type Query } from "../src";
+
+// Define component types
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+type Health = { value: number };
+
+// Define component IDs
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const Health = component<Health>();
+
+// Create the world
+const world = new World();
+
+// Cache queries
+const movementQuery: Query = world.createQuery([Position, Velocity]);
+const damageQuery: Query = world.createQuery([Position, Health]);
+const renderQuery: Query = world.createQuery([Position]);
+
+// Build game loop using pipeline
+// Pass execution order is determined by addition order; no need to manually manage dependencies
+const gameLoop = pipeline<{ deltaTime: number }>()
+  // Input pass - handle user input
+  .addPass(() => {
+    console.log(`[InputPass] Processing input at ${Date.now()}`);
+    // Keyboard/mouse input handling etc. goes here
+  })
+  // Movement pass - update positions
+  .addPass((env) => {
+    console.log(`[MovementPass] Updating positions`);
+    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)})`);
+    });
+  })
+  // Damage pass - calculate damage based on position
+  .addPass(() => {
+    console.log(`[DamagePass] Applying damage based on position`);
+    damageQuery.forEach([Position, Health], (entity, position, health) => {
+      // Calculate damage based on position (example logic)
+      const damage = Math.abs(position.x) * 0.1;
+      health.value -= damage;
+      console.log(`  Entity ${entity}: Health reduced by ${damage.toFixed(2)}, now ${health.value.toFixed(2)}`);
+    });
+  })
+  // Render pass - render entities
+  .addPass(() => {
+    console.log(`[RenderPass] Rendering entities`);
+    renderQuery.forEach([Position], (entity, position) => {
+      console.log(`  Rendering Entity ${entity} at (${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 Advanced Scheduling Demo - Pipeline-based Execution");
+  console.log("========================================================");
+
+  // Create some entities
+  const entity1 = world
+    .spawn()
+    .with(Position, { x: 0, y: 0 })
+    .with(Velocity, { x: 2, y: 1 })
+    .with(Health, { value: 100 })
+    .build();
+  void entity1;
+
+  const entity2 = world
+    .spawn()
+    .with(Position, { x: 5, y: 3 })
+    .with(Velocity, { x: -1, y: 0.5 })
+    .with(Health, { value: 80 })
+    .build();
+  void entity2;
+
+  // Execute initial sync
+  world.sync();
+
+  // Run a few frames
+  console.log("\n--- Frame 1 ---");
+  gameLoop({ deltaTime: 1.0 });
+
+  console.log("\n--- Frame 2 ---");
+  gameLoop({ deltaTime: 1.0 });
+
+  console.log("\nDemo completed!");
+}
+
+main();

package/examples/collision-detection.ts

@@ -0,0 +1,229 @@
+import { pipeline } from "@codehz/pipeline";
+import { World, component, type EntityId, type Query } from "../src";
+
+// =============================================================================
+// Component Types
+// =============================================================================
+
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+type Radius = number;
+type Health = { value: number };
+type CollisionEvent = { other: EntityId; overlap: number };
+
+// =============================================================================
+// Component IDs
+// =============================================================================
+
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const Radius = component<Radius>();
+const Health = component<Health>();
+const CollisionEvent = component<CollisionEvent>();
+
+// =============================================================================
+// World & Pre-cached Queries
+// =============================================================================
+
+const world = new World();
+
+const movementQuery: Query = world.createQuery([Position, Velocity]);
+const collidableQuery: Query = world.createQuery([Position, Radius]);
+const damagedQuery: Query = world.createQuery([Health]);
+const collisionEventQuery: Query = world.createQuery([CollisionEvent]);
+
+// =============================================================================
+// Game Loop (Pipeline Passes)
+// =============================================================================
+
+const gameLoop = pipeline<{ deltaTime: number }>()
+  // ---------------------------------------------------------------------------
+  // MovementPass: Move entities by velocity * deltaTime
+  // ---------------------------------------------------------------------------
+  .addPass((env) => {
+    console.log(`[MovementPass] deltaTime=${env.deltaTime}`);
+    movementQuery.forEach([Position, Velocity], (_entity, pos, vel) => {
+      pos.x += vel.x * env.deltaTime;
+      pos.y += vel.y * env.deltaTime;
+    });
+  })
+
+  // ---------------------------------------------------------------------------
+  // CollisionDetectionPass: O(n^2) pair check
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log(`[CollisionDetectionPass]`);
+    const collidables = collidableQuery.getEntitiesWithComponents([Position, Radius]);
+    let collisionCount = 0;
+
+    for (let i = 0; i < collidables.length; i++) {
+      const a = collidables[i]!;
+      for (let j = i + 1; j < collidables.length; j++) {
+        const b = collidables[j]!;
+        const dx = a.components[0].x - b.components[0].x;
+        const dy = a.components[0].y - b.components[0].y;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        const overlap = a.components[1] + b.components[1] - dist;
+
+        if (overlap > 0) {
+          console.log(`  Collision: Entity ${a.entity} <-> Entity ${b.entity} ` + `(overlap: ${overlap.toFixed(2)})`);
+          world.set(a.entity, CollisionEvent, { other: b.entity, overlap });
+          world.set(b.entity, CollisionEvent, { other: a.entity, overlap });
+          collisionCount++;
+        }
+      }
+    }
+
+    if (collisionCount === 0) {
+      console.log(`  No collisions detected`);
+    }
+
+    // Sync so CollisionEvents are visible to the response pass
+    world.sync();
+  })
+
+  // ---------------------------------------------------------------------------
+  // CollisionResponsePass: Apply damage & remove transient CollisionEvent
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log(`[CollisionResponsePass]`);
+    collisionEventQuery.forEach([CollisionEvent], (entity, event) => {
+      if (world.has(entity, Health)) {
+        const health = world.get(entity, Health);
+        health.value -= event.overlap;
+        console.log(
+          `  Entity ${entity}: took ${event.overlap.toFixed(2)} damage ` +
+            `from Entity ${event.other}, health now ${health.value.toFixed(2)}`,
+        );
+      } else {
+        console.log(
+          `  Entity ${entity}: collision with Entity ${event.other} ` + `(no Health component, skipping damage)`,
+        );
+      }
+      world.remove(entity, CollisionEvent);
+    });
+  })
+
+  // ---------------------------------------------------------------------------
+  // CleanupPass: Delete dead entities (health <= 0)
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log(`[CleanupPass]`);
+    const toDelete: EntityId[] = [];
+
+    damagedQuery.forEach([Health], (entity, health) => {
+      if (health.value <= 0) {
+        console.log(`  Entity ${entity}: destroyed (health: ${health.value.toFixed(2)})`);
+        toDelete.push(entity);
+      }
+    });
+
+    for (const entity of toDelete) {
+      world.delete(entity);
+    }
+
+    if (toDelete.length === 0) {
+      console.log(`  No entities to clean up`);
+    }
+  })
+
+  // ---------------------------------------------------------------------------
+  // RenderPass: Log positions and health of all living entities
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    console.log(`[RenderPass]`);
+    movementQuery.forEach([Position, Velocity], (entity, pos) => {
+      const healthOpt = world.getOptional(entity, Health);
+      const healthStr = healthOpt ? healthOpt.value.value.toFixed(2) : "N/A";
+      console.log(`  Entity ${entity}: pos=(${pos.x.toFixed(2)}, ${pos.y.toFixed(2)}) ` + `health=${healthStr}`);
+    });
+  })
+
+  // ---------------------------------------------------------------------------
+  // SyncPass: Apply all remaining buffered commands
+  // ---------------------------------------------------------------------------
+  .addPass(() => {
+    world.sync();
+  })
+  .build();
+
+// =============================================================================
+// Setup & Main
+// =============================================================================
+
+function main() {
+  console.log("ECS Collision Detection Demo");
+  console.log("============================\n");
+
+  // Spawn ~6 entities with diverse properties
+  console.log("Spawning entities...\n");
+
+  // Entity 1: Fast mover, small radius, moderate health
+  world
+    .spawn()
+    .with(Position, { x: 0, y: 0 })
+    .with(Velocity, { x: 3, y: 1 })
+    .with(Radius, 10)
+    .with(Health, { value: 50 })
+    .build();
+
+  // Entity 2: Slow mover, large radius, high health
+  world
+    .spawn()
+    .with(Position, { x: 30, y: 10 })
+    .with(Velocity, { x: -1.5, y: 2 })
+    .with(Radius, 18)
+    .with(Health, { value: 120 })
+    .build();
+
+  // Entity 3: Stationary, medium radius, low health
+  world
+    .spawn()
+    .with(Position, { x: 15, y: 20 })
+    .with(Velocity, { x: 0, y: 0 })
+    .with(Radius, 14)
+    .with(Health, { value: 25 })
+    .build();
+
+  // Entity 4: Diagonal mover, small radius, moderate health
+  world
+    .spawn()
+    .with(Position, { x: 40, y: 5 })
+    .with(Velocity, { x: -3, y: -2 })
+    .with(Radius, 8)
+    .with(Health, { value: 60 })
+    .build();
+
+  // Entity 5: Opposite diagonal, medium radius, high health
+  world
+    .spawn()
+    .with(Position, { x: 10, y: 35 })
+    .with(Velocity, { x: 2.5, y: -1.5 })
+    .with(Radius, 16)
+    .with(Health, { value: 100 })
+    .build();
+
+  // Entity 6: Slow vertical mover, large radius, moderate health
+  world
+    .spawn()
+    .with(Position, { x: 50, y: 25 })
+    .with(Velocity, { x: -0.5, y: 3 })
+    .with(Radius, 20)
+    .with(Health, { value: 80 })
+    .build();
+
+  // Apply initial spawns
+  world.sync();
+  console.log("All entities spawned and synced.\n");
+
+  // Run 5 frames
+  for (let frame = 1; frame <= 5; frame++) {
+    console.log(`--- Frame ${frame} ---`);
+    gameLoop({ deltaTime: 1.0 });
+    console.log();
+  }
+
+  console.log("Demo completed!");
+}
+
+main();

package/examples/inventory-system-relations.ts

@@ -0,0 +1,108 @@
+import { World, component, relation, type EntityId, type Query } from "../src";
+
+type ItemName = { name: string };
+type Stackable = { count: number; maxCount: number };
+type Gold = { amount: number };
+type EquipmentSlot = { slot: string };
+
+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 world = new World();
+
+const inventoryOwners: Query = world.createQuery([relation(InInventory, "*")]);
+
+function formatItem(item: EntityId): string {
+  const itemName = world.get(item, ItemName);
+  const stack = world.getOptional(item, Stackable)?.value;
+  const slot = world.getOptional(item, EquipmentSlot)?.value;
+
+  const details: string[] = [];
+  if (stack) {
+    details.push(`stack ${stack.count}/${stack.maxCount}`);
+  }
+  if (slot) {
+    details.push(`slot=${slot.slot}`);
+  }
+
+  return details.length > 0 ? `${itemName.name} (${details.join(", ")})` : itemName.name;
+}
+
+function printInventory(owner: EntityId, label: string): void {
+  if (!world.has(owner, relation(InInventory, "*"))) {
+    console.log(`${label}: empty inventory`);
+    return;
+  }
+
+  const entries = world.get(owner, relation(InInventory, "*"));
+  const itemLines = entries.map(([item]) => `  - Item ${item}: ${formatItem(item)}`);
+  console.log(`${label}:\n${itemLines.join("\n")}`);
+}
+
+function countInventoryItems(owner: EntityId): number {
+  return world.getOptional(owner, relation(InInventory, "*"))?.value.length ?? 0;
+}
+
+function printInventorySummary(): void {
+  console.log("\n[InventorySummary]");
+  inventoryOwners.forEach([relation(InInventory, "*")], (owner, items) => {
+    const gold = world.getOptional(owner, Gold)?.value;
+    console.log(`Owner ${owner}: ${items.length} item(s), gold=${gold?.amount ?? 0}`);
+  });
+}
+
+function main() {
+  console.log("ECS Inventory System Demo - Non-exclusive Relations");
+  console.log("===================================================");
+
+  const sword = world.spawn().with(ItemName, { name: "Iron Sword" }).with(EquipmentSlot, { slot: "weapon" }).build();
+  const armor = world.spawn().with(ItemName, { name: "Leather Armor" }).with(EquipmentSlot, { slot: "armor" }).build();
+  const potion = world
+    .spawn()
+    .with(ItemName, { name: "Health Potion" })
+    .with(Stackable, { count: 3, maxCount: 20 })
+    .build();
+  const arrows = world
+    .spawn()
+    .with(ItemName, { name: "Arrow Bundle" })
+    .with(Stackable, { count: 48, maxCount: 99 })
+    .build();
+
+  const player = world
+    .spawn()
+    .with(Gold, { amount: 125 })
+    .with(relation(InInventory, sword))
+    .with(relation(InInventory, armor))
+    .with(relation(InInventory, potion))
+    .with(relation(InInventory, arrows))
+    .build();
+  world.sync();
+
+  console.log(`\nPlayer ${player} starts with ${world.get(player, Gold).amount} gold.`);
+  printInventory(player, "Initial inventory");
+
+  const potionStack = world.get(potion, Stackable);
+  potionStack.count += 2;
+  console.log(`\nPicked up more potions. Potion stack is now ${potionStack.count}/${potionStack.maxCount}.`);
+
+  const swordSlot = world.get(sword, EquipmentSlot);
+  console.log(`Equipped ${world.get(sword, ItemName).name} to ${swordSlot.slot}.`);
+
+  world.remove(player, relation(InInventory, armor));
+  world.set(player, Gold, { amount: world.get(player, Gold).amount + 35 });
+  world.sync();
+
+  console.log(`\nSold ${world.get(armor, ItemName).name} for 35 gold.`);
+  console.log(`Player ${player} now has ${world.get(player, Gold).amount} gold.`);
+  printInventory(player, "Inventory after selling armor");
+
+  console.log(`\nInventory count via wildcard relation: ${countInventoryItems(player)}`);
+  printInventorySummary();
+
+  console.log("\nDemo completed!");
+}
+
+main();

package/examples/parent-child-hierarchy.ts

@@ -0,0 +1,206 @@
+import { pipeline } from "@codehz/pipeline";
+import { World, component, relation, type EntityId, type Query } from "../src";
+
+// Define component types
+type Transform = { x: number; y: number; rotation: number; scale: number };
+type LinearVelocity = { x: number; y: number };
+type AngularVelocity = { degreesPerSecond: number };
+type Name = { value: string };
+
+// Define component IDs
+const Name = component<Name>({ name: "Name" });
+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" });
+
+// Create the world
+const world = new World();
+
+// Cache queries
+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 {
+  return (degrees * Math.PI) / 180;
+}
+
+function copyTransform(target: Transform, source: Transform): void {
+  target.x = source.x;
+  target.y = source.y;
+  target.rotation = source.rotation;
+  target.scale = source.scale;
+}
+
+function composeTransform(local: Transform, parent?: Transform): Transform {
+  if (!parent) {
+    return { ...local };
+  }
+
+  const angle = toRadians(parent.rotation);
+  const scaledX = local.x * parent.scale;
+  const scaledY = local.y * parent.scale;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+
+  return {
+    x: parent.x + scaledX * cos - scaledY * sin,
+    y: parent.y + scaledX * sin + scaledY * cos,
+    rotation: parent.rotation + local.rotation,
+    scale: parent.scale * local.scale,
+  };
+}
+
+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);
+  }
+}
+
+// Build game loop using pipeline
+// Pass execution order is determined by addition order; no need to manually manage dependencies
+const gameLoop = pipeline<{ deltaTime: number }>()
+  // Local movement pass - update local positions
+  .addPass((env) => {
+    console.log(`[LocalMovementPass] Updating local positions`);
+    movementQuery.forEach([LocalTransform, LinearVelocity], (entity, localTransform, velocity) => {
+      localTransform.x += velocity.x * env.deltaTime;
+      localTransform.y += velocity.y * env.deltaTime;
+      const name = world.get(entity, Name);
+      console.log(`  ${name.value}: local pos=(${localTransform.x.toFixed(2)}, ${localTransform.y.toFixed(2)})`);
+    });
+  })
+  // Local rotation pass - update local rotation
+  .addPass((env) => {
+    console.log(`[LocalRotationPass] Updating local rotations`);
+    rotationQuery.forEach([LocalTransform, AngularVelocity], (entity, localTransform, angularVelocity) => {
+      localTransform.rotation += angularVelocity.degreesPerSecond * env.deltaTime;
+      const name = world.get(entity, Name);
+      console.log(`  ${name.value}: local rot=${localTransform.rotation.toFixed(1)}deg`);
+    });
+  })
+  // Hierarchy pass - propagate parent transforms into world transforms
+  .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;
+
+      copyTransform(worldTransform, composeTransform(localTransform));
+      console.log(`  Root ${name.value}: ${formatTransform(worldTransform)}`);
+      propagateChildren(entity, worldTransform, childrenByParent);
+    });
+  })
+  // Render pass - render propagated world transforms
+  .addPass(() => {
+    console.log(`[RenderPass] Rendering world transforms`);
+    renderQuery.forEach([Name, WorldTransform], (_entity, name, worldTransform) => {
+      console.log(`  ${name.value}: ${formatTransform(worldTransform)}`);
+    });
+  })
+  // Sync pass - must be called as the last pass to execute all deferred commands
+  .addPass(() => {
+    world.sync();
+  })
+  .build();
+
+function main() {
+  console.log("ECS Parent-Child Hierarchy Demo - Transform Propagation");
+  console.log("=======================================================");
+
+  // Create a moving root entity
+  const ship = world
+    .spawn()
+    .with(Name, { value: "Ship" })
+    .with(LocalTransform, { x: 0, y: 0, rotation: 0, scale: 1 })
+    .with(WorldTransform, { x: 0, y: 0, rotation: 0, scale: 1 })
+    .with(LinearVelocity, { x: 1, y: 0.25 })
+    .build();
+
+  // Create a rotating child attached to the ship
+  const turret = world
+    .spawn()
+    .with(Name, { value: "Turret" })
+    .with(LocalTransform, { x: 2, y: 0, rotation: 0, scale: 1 })
+    .with(WorldTransform, { x: 0, y: 0, rotation: 0, scale: 1 })
+    .with(AngularVelocity, { degreesPerSecond: 45 })
+    .with(relation(ChildOf, ship))
+    .build();
+
+  // Create a grandchild so propagation traverses multiple levels
+  const muzzle = world
+    .spawn()
+    .with(Name, { value: "Muzzle" })
+    .with(LocalTransform, { x: 1.5, y: 0.5, rotation: 0, scale: 1 })
+    .with(WorldTransform, { x: 0, y: 0, rotation: 0, scale: 1 })
+    .with(relation(ChildOf, turret))
+    .build();
+  void muzzle;
+
+  // Create a second root entity to show independent hierarchies
+  const drone = world
+    .spawn()
+    .with(Name, { value: "Drone" })
+    .with(LocalTransform, { x: -4, y: 3, rotation: 15, scale: 0.75 })
+    .with(WorldTransform, { x: -4, y: 3, rotation: 15, scale: 0.75 })
+    .with(LinearVelocity, { x: 0.5, y: -0.25 })
+    .build();
+  void drone;
+
+  // Execute initial sync
+  world.sync();
+
+  // Run an initial propagation frame so children receive their world transforms
+  console.log("\n--- Initial Hierarchy ---");
+  gameLoop({ deltaTime: 0.0 });
+
+  // Run a few frames
+  console.log("\n--- Frame 1 ---");
+  gameLoop({ deltaTime: 1.0 });
+
+  console.log("\n--- Frame 2 ---");
+  gameLoop({ deltaTime: 1.0 });
+
+  console.log("\n--- Frame 3 ---");
+  gameLoop({ deltaTime: 1.0 });
+
+  console.log("\nDemo completed!");
+}
+
+main();