murow 0.0.70 → 0.0.71

package/src/ecs/entity-handle.ts

@@ -1,563 +0,0 @@
-import { Component } from "./component";
-import { Entity, World } from "./world";
-
-/**
- * Syntactic sugar wrapper for entity operations.
- *
- * **Optimized for performance** - Uses raw component store access with inline caching
- * to bypass validation overhead in the public World API.
- *
- * Performance optimizations:
- * - Inline caching: Component indices cached on first access (~29% faster)
- * - Direct store access: Skips validation checks (has-component, error throwing)
- * - Zero allocations: No intermediate objects created
- *
- * @example
- * ```typescript
- * // Fluent chaining API
- * const player = world.entity(world.spawn())
- *   .add(Transform, { x: 0, y: 0, rotation: 0 })
- *   .add(Health, { current: 100, max: 100 })
- *   .add(Velocity, { vx: 0, vy: 0 });
- *
- * // Use the handle - with inline cached store access
- * player.update(Transform, { x: 10 });
- * const health = player.get(Health);
- *
- * // Access raw entity ID
- * console.log(player.id); // number
- * ```
- *
- * @example
- * ```typescript
- * // EntityHandle with inline caching is faster:
- * // World API - validates every call:
- * world.update(entity, Transform, { x: 10 });  // Map.get() + hasComponentBit + validation
- * world.update(entity, Transform, { x: 20 });  // Map.get() + hasComponentBit + validation
- *
- * // EntityHandle - cached direct access:
- * handle.update(Transform, { x: 10 });  // Map.get() + cache + store.update
- * handle.update(Transform, { x: 20 });  // Cached! store.update only
- * ```
- */
-export class EntityHandle {
-  // Reusable update batch - parallel arrays for better cache locality
-  private static batchArrays: any[] = [];
-  private static batchIndices: number[] = [];
-  private static batchValues: any[] = [];
-  private static batchLength = 0;
-
-  // Track prepared components to clear cache
-  private static preparedComponents: Component<any>[] = [];
-  private static preparedCount = 0;
-
-  // Instance batching state
-  private isBatching = false;
-
-  /**
-   * Creates an entity handle wrapping a world and entity ID.
-   *
-   * **Note**: Prefer using `world.entity(id)` factory method for cleaner code.
-   *
-   * @param world - The world managing this entity
-   * @param id - The entity ID
-   *
-   * @example
-   * ```typescript
-   * // Direct construction (verbose)
-   * const handle = new EntityHandle(world, world.spawn());
-   *
-   * // Preferred factory method (cleaner)
-   * const handle = world.entity(world.spawn());
-   * ```
-   */
-  constructor(
-    private readonly world: World,
-    private _id: Entity
-  ) {}
-
-  /**
-   * Internal method to reset the entity ID for handle reuse.
-   * @internal
-   */
-  _reset(id: Entity): void {
-    this._id = id;
-  }
-
-  /**
-   * Get component index with inline caching on the Component object.
-   * First call does Map.get() and caches on component.__cachedIndex.
-   * Subsequent calls use the cached value (~29% faster).
-   *
-   * @internal
-   */
-  private getComponentIndex<T extends object>(component: Component<T>): number {
-    // Check if index is already cached on the component object
-    let index = (component as any).__cachedIndex;
-    if (index === undefined) {
-      // First access: lookup and cache
-      index = component.__worldIndex;
-      (component as any).__cachedIndex = index;
-    }
-    return index;
-  }
-
-  /**
-   * Get direct TypedArray access to a specific field.
-   * Cached on Component object for maximum performance.
-   *
-   * **Zero-cost abstraction** - Same speed as RAW API after first access.
-   *
-   * @param component - Component definition
-   * @param field - Field name
-   * @returns TypedArray with direct access to the field
-   *
-   * @example
-   * ```typescript
-   * const transformX = entity.field(Transform, 'x');
-   * const velocityVx = entity.field(Velocity, 'vx');
-   *
-   * // Direct array access - same as RAW API!
-   * transformX[entity.id] += velocityVx[entity.id] * dt;
-   * ```
-   */
-  field<T extends object, K extends keyof T>(
-    component: Component<T>,
-    field: K
-  ): Float32Array | Int32Array | Uint32Array | Uint16Array | Uint8Array {
-    // Cache key on component object
-    const cacheKey = `__fieldCache_${String(field)}`;
-    let array = (component as any)[cacheKey];
-
-    if (array === undefined) {
-      // First access: get store and cache array
-      const index = this.getComponentIndex(component);
-      array = this.world.componentStoresArray[index]!.getFieldArray(field);
-      (component as any)[cacheKey] = array;
-    }
-
-    return array;
-  }
-
-  /**
-   * Add a component to this entity with initial data.
-   * Returns `this` for method chaining.
-   *
-   * @param component - Component definition to add
-   * @param data - Initial component data
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * entity
-   *   .add(Transform, { x: 0, y: 0, rotation: 0 })
-   *   .add(Health, { current: 100, max: 100 });
-   * ```
-   */
-  add<T extends object>(component: Component<T>, data: T): this {
-    this.world.add(this._id, component, data);
-    return this;
-  }
-
-  /**
-   * Get component data for this entity.
-   * Returns a readonly reusable object (zero allocations).
-   *
-   * In batch mode, returns cached data if available (from prepare() call).
-   *
-   * @param component - Component to retrieve
-   * @returns Readonly component data
-   *
-   * @example
-   * ```typescript
-   * const transform = entity.get(Transform);
-   * console.log(transform.x, transform.y);
-   * ```
-   */
-  get<T extends object>(component: Component<T>): Readonly<T> {
-    // In batch mode, check inline cache first
-    if (this.isBatching) {
-      const cached = (component as any).__batchCache;
-      if (cached !== undefined) {
-        return cached;
-      }
-    }
-
-    const index = this.getComponentIndex(component);
-    return this.world.componentStoresArray[index]!.get(this._id);
-  }
-
-  /**
-   * Pre-fetch and cache component data for batch mode.
-   * Use this before get() calls in beginUpdate() blocks for better performance.
-   *
-   * Only has effect in batch mode - does nothing when called outside beginUpdate().
-   *
-   * @param components - Components to pre-fetch
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * entity.beginUpdate().prepare(Transform, Velocity);
-   *
-   * const transform = entity.get(Transform);  // Uses cached data
-   * const velocity = entity.get(Velocity);    // Uses cached data
-   *
-   * entity
-   *   .setField(Transform, 'x', transform.x + velocity.vx * dt)
-   *   .setField(Transform, 'y', transform.y + velocity.vy * dt)
-   *   .flush();
-   * ```
-   */
-  prepare(...components: Component<any>[]): this {
-    if (this.isBatching) {
-      const prepared = EntityHandle.preparedComponents;
-      let count = EntityHandle.preparedCount;
-
-      for (let i = 0; i < components.length; i++) {
-        const component = components[i]!;
-        const index = this.getComponentIndex(component);
-        const data = this.world.componentStoresArray[index]!.get(this._id);
-        (component as any).__batchCache = data;
-
-        // Track for cleanup
-        if (count < prepared.length) {
-          prepared[count] = component;
-        } else {
-          prepared.push(component);
-        }
-        count++;
-      }
-
-      EntityHandle.preparedCount = count;
-    }
-    return this;
-  }
-
-  /**
-   * Update specific fields of a component.
-   * Returns `this` for method chaining.
-   *
-   * More efficient than get + set for partial changes.
-   *
-   * @param component - Component to update
-   * @param data - Partial data to update
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * // Update single field
-   * entity.update(Transform, { x: 150 });
-   *
-   * // Chain multiple updates
-   * entity
-   *   .update(Transform, { x: 100, y: 200 })
-   *   .update(Health, { current: 50 });
-   * ```
-   */
-  update<T extends object>(component: Component<T>, data: Partial<T>): this {
-    const index = this.getComponentIndex(component);
-    this.world.componentStoresArray[index]!.update(this._id, data);
-    return this;
-  }
-
-  /**
-   * Update fields using an updater function that mutates the component data directly.
-   * Zero allocations - the function mutates the mutable data object in place.
-   *
-   * @param component - Component to update
-   * @param updater - Function that receives mutable data and mutates it directly
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * // Mutate fields directly
-   * entity.setFields(Transform, function (t) {
-   *   t.x += velocity.vx * dt;
-   *   t.y += velocity.vy * dt;
-   * });
-   *
-   * // Conditional mutation
-   * entity.setFields(Health, function (h) {
-   *   if (h.current < h.max) {
-   *     h.current += 5;
-   *   }
-   * });
-   * ```
-   */
-  setFields<T extends object>(
-    component: Component<T>,
-    updater: (current: T) => void
-  ): this {
-    const index = this.getComponentIndex(component);
-    const store = this.world.componentStoresArray[index]!;
-    const mutable = store.getMutable(this._id);
-    updater(mutable);
-    store.set(this._id, mutable);
-    return this;
-  }
-
-  /**
-   * Set a single field directly without allocating an object.
-   * Zero-cost operation - same speed as RAW API.
-   *
-   * When batching is enabled (via beginUpdate()), this queues the update
-   * instead of applying it immediately. Call flush() to apply batched updates.
-   *
-   * @param component - Component to update
-   * @param field - Field name
-   * @param value - New value
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * // Immediate update
-   * entity.setField(Transform, 'x', 150);
-   *
-   * // Batched updates (reduced allocations, better JIT)
-   * entity.beginUpdate()
-   *   .setField(Transform, 'x', 150)
-   *   .setField(Transform, 'y', 200)
-   *   .setField(Health, 'current', 50)
-   *   .flush();
-   * ```
-   */
-  setField<T extends object, K extends keyof T>(
-    component: Component<T>,
-    field: K,
-    value: T[K]
-  ): this {
-    const index = this.getComponentIndex(component);
-    const store = this.world.componentStoresArray[index]!;
-    const array = store.getFieldArray(field);
-
-    if (this.isBatching) {
-      // Queue update for batching using parallel arrays
-      const len = EntityHandle.batchLength;
-      EntityHandle.batchArrays[len] = array;
-      EntityHandle.batchIndices[len] = this._id;
-      EntityHandle.batchValues[len] = value;
-      EntityHandle.batchLength++;
-    } else {
-      // Apply immediately
-      array[this._id] = value as any;
-    }
-
-    return this;
-  }
-
-  /**
-   * Get a single field value directly.
-   * More efficient than get() when you only need one field.
-   *
-   * @param component - Component to read from
-   * @param field - Field name
-   * @returns Field value
-   *
-   * @example
-   * ```typescript
-   * const x = entity.getField(Transform, 'x');
-   * const health = entity.getField(Health, 'current');
-   * ```
-   */
-  getField<T extends object, K extends keyof T>(
-    component: Component<T>,
-    field: K
-  ): T[K] {
-    const index = this.getComponentIndex(component);
-    const store = this.world.componentStoresArray[index]!;
-    const array = store.getFieldArray(field);
-    return array[this._id] as T[K];
-  }
-
-  /**
-   * Set component data for this entity, overwriting all fields.
-   * Returns `this` for method chaining.
-   *
-   * @param component - Component to set
-   * @param data - Complete component data
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * entity.set(Transform, { x: 100, y: 200, rotation: 0 });
-   * ```
-   */
-  set<T extends object>(component: Component<T>, data: T): this {
-    const index = this.getComponentIndex(component);
-    this.world.componentStoresArray[index]!.set(this._id, data);
-    return this;
-  }
-
-  /**
-   * Check if this entity has a specific component.
-   *
-   * @param component - Component to check
-   * @returns True if entity has the component
-   *
-   * @example
-   * ```typescript
-   * if (entity.has(Health)) {
-   *   const health = entity.get(Health);
-   * }
-   * ```
-   */
-  has<T extends object>(component: Component<T>): boolean {
-    return this.world.has(this._id, component);
-  }
-
-  /**
-   * Remove a component from this entity.
-   * Returns `this` for method chaining.
-   *
-   * @param component - Component to remove
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * entity
-   *   .remove(Velocity)
-   *   .remove(Health);
-   * ```
-   */
-  remove<T extends object>(component: Component<T>): this {
-    this.world.remove(this._id, component);
-    return this;
-  }
-
-  /**
-   * Despawn this entity, removing all components.
-   * The entity ID will be reused.
-   *
-   * **Note**: This handle becomes invalid after despawning.
-   *
-   * @example
-   * ```typescript
-   * entity.despawn();
-   * // entity is now invalid - don't use it!
-   * ```
-   */
-  despawn(): void {
-    this.world.despawn(this._id);
-  }
-
-  /**
-   * Check if this entity is alive.
-   *
-   * @returns True if entity exists in the world
-   *
-   * @example
-   * ```typescript
-   * if (entity.isAlive()) {
-   *   entity.update(Health, { current: 0 });
-   * }
-   * ```
-   */
-  isAlive(): boolean {
-    return this.world.isAlive(this._id);
-  }
-
-  /**
-   * Get the raw entity ID.
-   *
-   * Use this when you need to pass the entity to raw World API methods
-   * or store the ID for later use.
-   *
-   * @example
-   * ```typescript
-   * const id = entity.id;
-   * world.add(id, Transform, { x: 0, y: 0, rotation: 0 });
-   * ```
-   */
-  get id(): Entity {
-    return this._id;
-  }
-
-  /**
-   * Get a mutable copy of component data.
-   *
-   * **Note**: This allocates a new object. Use sparingly in hot paths.
-   *
-   * @param component - Component to retrieve
-   * @returns Mutable copy of component data
-   *
-   * @example
-   * ```typescript
-   * const transform = entity.getMutable(Transform);
-   * transform.x = 100; // OK to mutate
-   * entity.set(Transform, transform);
-   * ```
-   */
-  getMutable<T extends object>(component: Component<T>): T {
-    const index = this.getComponentIndex(component);
-    return this.world.componentStoresArray[index]!.getMutable(this._id);
-  }
-
-  /**
-   * Begin batching updates for better performance.
-   * All setField() calls will be queued until flush() is called.
-   *
-   * **Benefits:**
-   * - Reduced allocations (reusable batch array)
-   * - Better JIT optimization (predictable pattern)
-   * - Reduced GC pressure
-   *
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * // Batch multiple field updates
-   * entity.beginUpdate()
-   *   .setField(Transform, 'x', 150)
-   *   .setField(Transform, 'y', 200)
-   *   .setField(Transform, 'rotation', 1.5)
-   *   .flush();
-   * ```
-   */
-  beginUpdate(): this {
-    this.isBatching = true;
-    EntityHandle.batchLength = 0;
-    return this;
-  }
-
-  /**
-   * Apply all batched updates.
-   * Resets batching mode - subsequent setField() calls apply immediately.
-   *
-   * @returns This handle for chaining
-   *
-   * @example
-   * ```typescript
-   * entity.beginUpdate()
-   *   .setField(Transform, 'x', 150)
-   *   .setField(Health, 'current', 50)
-   *   .flush(); // Applies both updates
-   * ```
-   */
-  flush(): this {
-    const arrays = EntityHandle.batchArrays;
-    const indices = EntityHandle.batchIndices;
-    const values = EntityHandle.batchValues;
-    const len = EntityHandle.batchLength;
-
-    // Apply all batched updates
-    for (let i = 0; i < len; i++) {
-      arrays[i][indices[i]] = values[i];
-    }
-
-    // Clear prepared component caches
-    const prepared = EntityHandle.preparedComponents;
-    const prepCount = EntityHandle.preparedCount;
-    for (let i = 0; i < prepCount; i++) {
-      const component = prepared[i]!;
-      (component as any).__batchCache = undefined;
-    }
-
-    // Reset batching state
-    this.isBatching = false;
-    EntityHandle.batchLength = 0;
-    EntityHandle.preparedCount = 0;
-
-    return this;
-  }
-}

package/src/ecs/example.ts

@@ -1,152 +0,0 @@
-/**
- * ECS Usage Example
- *
- * This example demonstrates how to use the ECS for a simple game.
- */
-
-import { defineComponent, World } from "./index";
-import { BinaryCodec } from "../core/binary-codec";
-
-// 1. Define components using BinaryCodec schemas
-const Transform = defineComponent("Transform", {
-  x: BinaryCodec.f32,
-  y: BinaryCodec.f32,
-  rotation: BinaryCodec.f32,
-});
-
-const Velocity = defineComponent("Velocity", {
-  vx: BinaryCodec.f32,
-  vy: BinaryCodec.f32,
-});
-
-const Health = defineComponent("Health", {
-  current: BinaryCodec.u16,
-  max: BinaryCodec.u16,
-});
-
-const Damage = defineComponent("Damage", {
-  amount: BinaryCodec.u16,
-});
-
-// 2. Create systems
-class MovementSystem {
-  update(world: World, deltaTime: number) {
-    for (const entity of world.query(Transform, Velocity)) {
-      const transform = world.get(entity, Transform); // Readonly!
-      const velocity = world.get(entity, Velocity); // Readonly!
-
-      // Update position using update() (efficient partial update)
-      world.update(entity, Transform, {
-        x: transform.x + velocity.vx * deltaTime,
-        y: transform.y + velocity.vy * deltaTime,
-      });
-    }
-  }
-}
-
-class HealthSystem {
-  update(world: World) {
-    for (const entity of world.query(Health)) {
-      const health = world.get(entity, Health);
-
-      // Despawn dead entities
-      if (health.current <= 0) {
-        console.log(`Entity ${entity} died`);
-        world.despawn(entity);
-      }
-    }
-  }
-}
-
-class CombatSystem {
-  update(world: World) {
-    // Simple collision-based damage (in real game, use spatial partitioning)
-    const combatants = Array.from(world.query(Transform, Health, Damage));
-
-    for (let i = 0; i < combatants.length; i++) {
-      for (let j = i + 1; j < combatants.length; j++) {
-        const e1 = combatants[i];
-        const e2 = combatants[j];
-
-        const t1 = world.get(e1, Transform);
-        const t2 = world.get(e2, Transform);
-
-        // Check collision (simple distance check)
-        const dx = t1.x - t2.x;
-        const dy = t1.y - t2.y;
-        const dist = Math.sqrt(dx * dx + dy * dy);
-
-        if (dist < 10) {
-          // Apply damage
-          const d1 = world.get(e1, Damage);
-          const d2 = world.get(e2, Damage);
-
-          world.update(e1, Health, { current: world.get(e1, Health).current - d2.amount });
-          world.update(e2, Health, { current: world.get(e2, Health).current - d1.amount });
-
-          console.log(`Entities ${e1} and ${e2} collided! Applying damage.`);
-        }
-      }
-    }
-  }
-}
-
-// 3. Create world and spawn entities
-function runExample() {
-  const world = new World({
-    maxEntities: 1000,
-    components: [Transform, Velocity, Health, Damage],
-  });
-
-  // Spawn player
-  const player = world.spawn();
-  world.add(player, Transform, { x: 0, y: 0, rotation: 0 });
-  world.add(player, Velocity, { vx: 100, vy: 0 });
-  world.add(player, Health, { current: 100, max: 100 });
-  world.add(player, Damage, { amount: 10 });
-
-  // Spawn enemies
-  for (let i = 0; i < 5; i++) {
-    const enemy = world.spawn();
-    world.add(enemy, Transform, { x: 200 + i * 50, y: 0, rotation: 0 });
-    world.add(enemy, Velocity, { vx: -50, vy: 0 });
-    world.add(enemy, Health, { current: 50, max: 50 });
-    world.add(enemy, Damage, { amount: 5 });
-  }
-
-  console.log(`Spawned ${world.getEntityCount()} entities`);
-
-  // 4. Create systems
-  const movementSystem = new MovementSystem();
-  const combatSystem = new CombatSystem();
-  const healthSystem = new HealthSystem();
-
-  // 5. Game loop
-  const deltaTime = 0.016; // 60 FPS
-  let tick = 0;
-
-  const interval = setInterval(() => {
-    tick++;
-
-    // Update systems
-    movementSystem.update(world, deltaTime);
-    combatSystem.update(world);
-    healthSystem.update(world);
-
-    // Log stats every 10 ticks
-    if (tick % 10 === 0) {
-      console.log(`Tick ${tick}: ${world.getEntityCount()} entities alive`);
-    }
-
-    // Stop after 100 ticks or when all entities are dead
-    if (tick >= 100 || world.getEntityCount() === 0) {
-      clearInterval(interval);
-      console.log("Simulation ended");
-    }
-  }, deltaTime * 1000);
-}
-
-// Run the example
-if (import.meta.main) {
-  runExample();
-}

package/src/ecs/index.ts

@@ -1,4 +0,0 @@
-export { defineComponent, type Component, type InferComponentType, type ComponentMeta } from "./component";
-export { ComponentStore } from "./component-store";
-export { World, type Entity, type WorldConfig } from "./world";
-export { EntityHandle } from "./entity-handle";