murow 0.0.70 → 0.0.71

package/dist/ecs/entity-handle.js

@@ -1,515 +0,0 @@
-/**
- * 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 {
-    /**
-     * 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(world, _id) {
-        this.world = world;
-        this._id = _id;
-        // Instance batching state
-        this.isBatching = false;
-    }
-    /**
-     * Internal method to reset the entity ID for handle reuse.
-     * @internal
-     */
-    _reset(id) {
-        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
-     */
-    getComponentIndex(component) {
-        // Check if index is already cached on the component object
-        let index = component.__cachedIndex;
-        if (index === undefined) {
-            // First access: lookup and cache
-            index = component.__worldIndex;
-            component.__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(component, field) {
-        // Cache key on component object
-        const cacheKey = `__fieldCache_${String(field)}`;
-        let array = component[cacheKey];
-        if (array === undefined) {
-            // First access: get store and cache array
-            const index = this.getComponentIndex(component);
-            array = this.world.componentStoresArray[index].getFieldArray(field);
-            component[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(component, data) {
-        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(component) {
-        // In batch mode, check inline cache first
-        if (this.isBatching) {
-            const cached = component.__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) {
-        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.__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(component, data) {
-        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(component, updater) {
-        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(component, field, value) {
-        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;
-        }
-        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(component, field) {
-        const index = this.getComponentIndex(component);
-        const store = this.world.componentStoresArray[index];
-        const array = store.getFieldArray(field);
-        return array[this._id];
-    }
-    /**
-     * 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(component, data) {
-        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(component) {
-        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(component) {
-        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() {
-        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() {
-        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() {
-        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(component) {
-        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.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() {
-        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.__batchCache = undefined;
-        }
-        // Reset batching state
-        this.isBatching = false;
-        EntityHandle.batchLength = 0;
-        EntityHandle.preparedCount = 0;
-        return this;
-    }
-}
-// Reusable update batch - parallel arrays for better cache locality
-EntityHandle.batchArrays = [];
-EntityHandle.batchIndices = [];
-EntityHandle.batchValues = [];
-EntityHandle.batchLength = 0;
-// Track prepared components to clear cache
-EntityHandle.preparedComponents = [];
-EntityHandle.preparedCount = 0;

package/dist/ecs/example.js

@@ -1,125 +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, deltaTime) {
-        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) {
-        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) {
-        // 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/dist/ecs/index.js

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