murow 0.0.31 → 0.0.42

package/dist/ecs/component-store.d.ts

@@ -0,0 +1,79 @@
+import { Component } from "./component";
+/**
+ * Stores component data for entities using typed arrays.
+ * Provides efficient packed storage with O(1) access by entity ID.
+ *
+ * Key optimizations:
+ * - ArrayBuffer storage (exact byte size, no waste)
+ * - Single reusable DataView (no allocations)
+ * - Single reusable object for get() (zero allocations)
+ * - Pre-computed field offsets (no runtime calculations)
+ */
+export declare class ComponentStore<T extends object> {
+    private buffer;
+    private view;
+    private stride;
+    private component;
+    private maxEntities;
+    private reusableObject;
+    private fieldOffsets;
+    private fields;
+    private fieldKeys;
+    private fieldIndexMap;
+    constructor(component: Component<T>, maxEntities: number);
+    /**
+     * Get component data for an entity.
+     *
+     * ⚠️ IMPORTANT: Returns a REUSED object that is overwritten on the next get() call.
+     * Use immediately or copy the data. For safe access, use getMutable() or copyTo().
+     *
+     * @example
+     * // ✅ CORRECT: Use immediately
+     * const t = store.get(entity);
+     * console.log(t.x, t.y);
+     *
+     * // ❌ WRONG: Storing reference
+     * const t1 = store.get(entity1);
+     * const t2 = store.get(entity2); // t1 is now corrupted!
+     *
+     * // ✅ CORRECT: Copy if you need multiple
+     * const t1 = { ...store.get(entity1) };
+     * const t2 = { ...store.get(entity2) };
+     */
+    get(entityId: number): Readonly<T>;
+    /**
+     * Get a mutable copy of component data.
+     * Use this when you need to modify and keep the data.
+     *
+     * Note: This allocates a new object. Use sparingly in hot paths.
+     */
+    getMutable(entityId: number): T;
+    /**
+     * Copy component data into a provided object.
+     * Use this when you need to keep multiple components at once.
+     */
+    copyTo(entityId: number, target: T): void;
+    /**
+     * Set component data for an entity.
+     * Writes the data directly into the typed array.
+     */
+    set(entityId: number, data: T): void;
+    /**
+     * Update specific fields of a component without reading the whole component first.
+     * Optimized to only iterate over the fields being updated.
+     */
+    update(entityId: number, partial: Partial<T>): void;
+    /**
+     * Clear component data for an entity (set to default values)
+     */
+    clear(entityId: number): void;
+    /**
+     * Get direct access to the underlying buffer.
+     * Advanced use only - for SIMD operations, GPU uploads, zero-copy networking, etc.
+     */
+    getRawBuffer(): ArrayBuffer;
+    /**
+     * Get the stride in bytes.
+     */
+    getStride(): number;
+}

package/dist/ecs/component-store.js

@@ -0,0 +1,191 @@
+/**
+ * Stores component data for entities using typed arrays.
+ * Provides efficient packed storage with O(1) access by entity ID.
+ *
+ * Key optimizations:
+ * - ArrayBuffer storage (exact byte size, no waste)
+ * - Single reusable DataView (no allocations)
+ * - Single reusable object for get() (zero allocations)
+ * - Pre-computed field offsets (no runtime calculations)
+ */
+export class ComponentStore {
+    constructor(component, maxEntities) {
+        this.component = component;
+        this.maxEntities = maxEntities;
+        // Use exact byte size (no waste like Float32Array)
+        this.stride = component.size;
+        // Allocate exact memory needed
+        this.buffer = new ArrayBuffer(maxEntities * this.stride);
+        this.view = new DataView(this.buffer);
+        // Pre-compute field metadata once
+        this.fieldKeys = component.fieldNames;
+        this.fieldOffsets = [];
+        this.fields = [];
+        this.fieldIndexMap = new Map();
+        let offset = 0;
+        for (let i = 0; i < this.fieldKeys.length; i++) {
+            const key = this.fieldKeys[i];
+            const field = component.schema[key];
+            this.fieldOffsets.push(offset);
+            this.fields.push(field);
+            this.fieldIndexMap.set(key, i);
+            offset += field.size;
+        }
+        // Create single reusable object
+        this.reusableObject = {};
+        for (let i = 0; i < this.fieldKeys.length; i++) {
+            this.reusableObject[this.fieldKeys[i]] = this.fields[i].toNil();
+        }
+    }
+    /**
+     * Get component data for an entity.
+     *
+     * ⚠️ IMPORTANT: Returns a REUSED object that is overwritten on the next get() call.
+     * Use immediately or copy the data. For safe access, use getMutable() or copyTo().
+     *
+     * @example
+     * // ✅ CORRECT: Use immediately
+     * const t = store.get(entity);
+     * console.log(t.x, t.y);
+     *
+     * // ❌ WRONG: Storing reference
+     * const t1 = store.get(entity1);
+     * const t2 = store.get(entity2); // t1 is now corrupted!
+     *
+     * // ✅ CORRECT: Copy if you need multiple
+     * const t1 = { ...store.get(entity1) };
+     * const t2 = { ...store.get(entity2) };
+     */
+    get(entityId) {
+        const baseOffset = entityId * this.stride;
+        const length = this.fields.length;
+        // Unrolled loop for common cases
+        if (length === 2) {
+            this.reusableObject[this.fieldKeys[0]] = this.fields[0].read(this.view, baseOffset + this.fieldOffsets[0]);
+            this.reusableObject[this.fieldKeys[1]] = this.fields[1].read(this.view, baseOffset + this.fieldOffsets[1]);
+        }
+        else if (length === 3) {
+            this.reusableObject[this.fieldKeys[0]] = this.fields[0].read(this.view, baseOffset + this.fieldOffsets[0]);
+            this.reusableObject[this.fieldKeys[1]] = this.fields[1].read(this.view, baseOffset + this.fieldOffsets[1]);
+            this.reusableObject[this.fieldKeys[2]] = this.fields[2].read(this.view, baseOffset + this.fieldOffsets[2]);
+        }
+        else if (length === 4) {
+            this.reusableObject[this.fieldKeys[0]] = this.fields[0].read(this.view, baseOffset + this.fieldOffsets[0]);
+            this.reusableObject[this.fieldKeys[1]] = this.fields[1].read(this.view, baseOffset + this.fieldOffsets[1]);
+            this.reusableObject[this.fieldKeys[2]] = this.fields[2].read(this.view, baseOffset + this.fieldOffsets[2]);
+            this.reusableObject[this.fieldKeys[3]] = this.fields[3].read(this.view, baseOffset + this.fieldOffsets[3]);
+        }
+        else {
+            // Generic loop for other sizes
+            for (let i = 0; i < length; i++) {
+                this.reusableObject[this.fieldKeys[i]] = this.fields[i].read(this.view, baseOffset + this.fieldOffsets[i]);
+            }
+        }
+        return this.reusableObject;
+    }
+    /**
+     * Get a mutable copy of component data.
+     * Use this when you need to modify and keep the data.
+     *
+     * Note: This allocates a new object. Use sparingly in hot paths.
+     */
+    getMutable(entityId) {
+        const copy = {};
+        this.copyTo(entityId, copy);
+        return copy;
+    }
+    /**
+     * Copy component data into a provided object.
+     * Use this when you need to keep multiple components at once.
+     */
+    copyTo(entityId, target) {
+        const baseOffset = entityId * this.stride;
+        for (let i = 0; i < this.fields.length; i++) {
+            target[this.fieldKeys[i]] = this.fields[i].read(this.view, baseOffset + this.fieldOffsets[i]);
+        }
+    }
+    /**
+     * Set component data for an entity.
+     * Writes the data directly into the typed array.
+     */
+    set(entityId, data) {
+        const baseOffset = entityId * this.stride;
+        const length = this.fields.length;
+        // Unrolled loop for common cases
+        if (length === 2) {
+            this.fields[0].write(this.view, baseOffset + this.fieldOffsets[0], data[this.fieldKeys[0]]);
+            this.fields[1].write(this.view, baseOffset + this.fieldOffsets[1], data[this.fieldKeys[1]]);
+        }
+        else if (length === 3) {
+            this.fields[0].write(this.view, baseOffset + this.fieldOffsets[0], data[this.fieldKeys[0]]);
+            this.fields[1].write(this.view, baseOffset + this.fieldOffsets[1], data[this.fieldKeys[1]]);
+            this.fields[2].write(this.view, baseOffset + this.fieldOffsets[2], data[this.fieldKeys[2]]);
+        }
+        else if (length === 4) {
+            this.fields[0].write(this.view, baseOffset + this.fieldOffsets[0], data[this.fieldKeys[0]]);
+            this.fields[1].write(this.view, baseOffset + this.fieldOffsets[1], data[this.fieldKeys[1]]);
+            this.fields[2].write(this.view, baseOffset + this.fieldOffsets[2], data[this.fieldKeys[2]]);
+            this.fields[3].write(this.view, baseOffset + this.fieldOffsets[3], data[this.fieldKeys[3]]);
+        }
+        else {
+            // Generic loop for other sizes
+            for (let i = 0; i < length; i++) {
+                this.fields[i].write(this.view, baseOffset + this.fieldOffsets[i], data[this.fieldKeys[i]]);
+            }
+        }
+    }
+    /**
+     * Update specific fields of a component without reading the whole component first.
+     * Optimized to only iterate over the fields being updated.
+     */
+    update(entityId, partial) {
+        const baseOffset = entityId * this.stride;
+        // Fast path for single field update (90% of cases) - avoids Object.keys allocation
+        const keys = Object.keys(partial);
+        const keyCount = keys.length;
+        if (keyCount === 1) {
+            const key = keys[0];
+            const i = this.fieldIndexMap.get(key);
+            this.fields[i].write(this.view, baseOffset + this.fieldOffsets[i], partial[key]);
+            return;
+        }
+        // Fast path for two field update (common for 2D positions)
+        if (keyCount === 2) {
+            const key0 = keys[0];
+            const key1 = keys[1];
+            const i0 = this.fieldIndexMap.get(key0);
+            const i1 = this.fieldIndexMap.get(key1);
+            this.fields[i0].write(this.view, baseOffset + this.fieldOffsets[i0], partial[key0]);
+            this.fields[i1].write(this.view, baseOffset + this.fieldOffsets[i1], partial[key1]);
+            return;
+        }
+        // Generic path for multiple fields
+        for (let j = 0; j < keyCount; j++) {
+            const key = keys[j];
+            const i = this.fieldIndexMap.get(key);
+            this.fields[i].write(this.view, baseOffset + this.fieldOffsets[i], partial[key]);
+        }
+    }
+    /**
+     * Clear component data for an entity (set to default values)
+     */
+    clear(entityId) {
+        const baseOffset = entityId * this.stride;
+        for (let i = 0; i < this.fields.length; i++) {
+            this.fields[i].write(this.view, baseOffset + this.fieldOffsets[i], this.fields[i].toNil());
+        }
+    }
+    /**
+     * Get direct access to the underlying buffer.
+     * Advanced use only - for SIMD operations, GPU uploads, zero-copy networking, etc.
+     */
+    getRawBuffer() {
+        return this.buffer;
+    }
+    /**
+     * Get the stride in bytes.
+     */
+    getStride() {
+        return this.stride;
+    }
+}

package/dist/ecs/component.d.ts

@@ -0,0 +1,48 @@
+import { Schema } from "../core/binary-codec";
+import { ArrayField } from "../core/pooled-codec";
+/**
+ * Metadata for a component definition
+ */
+export interface ComponentMeta<T extends object> {
+    /** Schema defining the component's binary layout */
+    schema: Schema<T>;
+    /** Unique name for this component type */
+    name: string;
+    /** Size of the component in bytes */
+    size: number;
+    /** Number of fields in the schema */
+    fieldCount: number;
+    /** Field names in order */
+    fieldNames: (keyof T)[];
+    /** Codec for array serialization */
+    arrayCodec: ArrayField<T>;
+}
+/**
+ * Component type returned by defineComponent
+ */
+export type Component<T extends object = any> = ComponentMeta<T> & {
+    /** Type marker for TypeScript inference */
+    __type?: T;
+};
+/**
+ * Infer the data type from a Component
+ */
+export type InferComponentType<C> = C extends Component<infer T> ? T : never;
+/**
+ * Define a component type with its binary schema.
+ *
+ * @example
+ * ```typescript
+ * const Transform = defineComponent('Transform', {
+ *   x: BinaryCodec.f32,
+ *   y: BinaryCodec.f32,
+ *   rotation: BinaryCodec.f32,
+ * });
+ *
+ * const Health = defineComponent('Health', {
+ *   current: BinaryCodec.u16,
+ *   max: BinaryCodec.u16,
+ * });
+ * ```
+ */
+export declare function defineComponent<T extends object>(name: string, schema: Schema<T>): Component<T>;

package/dist/ecs/component.js

@@ -0,0 +1,43 @@
+import { PooledCodec } from "../core/pooled-codec";
+/**
+ * Calculate the byte size of a schema
+ */
+function calculateSchemaSize(schema) {
+    let size = 0;
+    for (const key of Object.keys(schema)) {
+        size += schema[key].size;
+    }
+    return size;
+}
+/**
+ * Define a component type with its binary schema.
+ *
+ * @example
+ * ```typescript
+ * const Transform = defineComponent('Transform', {
+ *   x: BinaryCodec.f32,
+ *   y: BinaryCodec.f32,
+ *   rotation: BinaryCodec.f32,
+ * });
+ *
+ * const Health = defineComponent('Health', {
+ *   current: BinaryCodec.u16,
+ *   max: BinaryCodec.u16,
+ * });
+ * ```
+ */
+export function defineComponent(name, schema) {
+    const size = calculateSchemaSize(schema);
+    const fieldNames = Object.keys(schema);
+    const fieldCount = fieldNames.length;
+    // Create PooledCodec for array serialization
+    const arrayCodec = PooledCodec.array(schema);
+    return {
+        name,
+        schema,
+        size,
+        fieldCount,
+        fieldNames,
+        arrayCodec,
+    };
+}

package/dist/ecs/example.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ECS Usage Example
+ *
+ * This example demonstrates how to use the ECS for a simple game.
+ */
+export {};

package/dist/ecs/example.js

@@ -0,0 +1,125 @@
+/**
+ * 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.d.ts

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

package/dist/ecs/index.js

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