murow 0.0.31 → 0.0.41

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,161 @@
+/**
+ * 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 {
+            // 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 {
+            // 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;
+        // Use Object.keys for faster iteration than for...in
+        const keys = Object.keys(partial);
+        for (let j = 0; j < keys.length; 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";

package/dist/ecs/world.d.ts

@@ -0,0 +1,208 @@
+import { Component } from "./component";
+/**
+ * Configuration for creating a World
+ */
+export interface WorldConfig {
+    /** Maximum number of entities that can exist simultaneously */
+    maxEntities?: number;
+    /** Component types to register */
+    components: Component<any>[];
+}
+/**
+ * Entity ID type (just a number, indexing into component arrays)
+ */
+export type Entity = number;
+/**
+ * World manages entities and their components.
+ * Provides efficient ECS storage using typed arrays.
+ *
+ * Performance optimizations:
+ * - Array iteration instead of Set for 2-5x faster queries
+ * - Query bitmask caching for repeated queries
+ * - Array-indexed component stores for O(1) access
+ * - Pre-allocated ring buffer for entity ID reuse
+ *
+ * @example
+ * ```typescript
+ * const world = new World({
+ *   maxEntities: 10000,
+ *   components: [Transform, Health, Velocity]
+ * });
+ *
+ * const entity = world.spawn();
+ * world.add(entity, Transform, { x: 100, y: 200, rotation: 0 });
+ * world.add(entity, Health, { current: 100, max: 100 });
+ *
+ * // Query entities
+ * for (const entity of world.query(Transform, Velocity)) {
+ *   const transform = world.get(entity, Transform);
+ *   const velocity = world.get(entity, Velocity);
+ *   // transform is readonly, use update() to modify
+ *   world.update(entity, Transform, {
+ *     x: transform.x + velocity.vx,
+ *     y: transform.y + velocity.vy
+ *   });
+ * }
+ * ```
+ */
+export declare class World {
+    private maxEntities;
+    private nextEntityId;
+    private freeEntityIds;
+    private freeEntityHead;
+    private freeEntityTail;
+    private freeEntityCount;
+    private freeEntityMask;
+    private aliveEntitiesArray;
+    private aliveEntitiesIndices;
+    private aliveEntityFlags;
+    private componentStoresArray;
+    private componentMasks;
+    private componentMap;
+    private components;
+    private queryResultBuffers;
+    private worldId;
+    constructor(config: WorldConfig);
+    /**
+     * Get component index (with caching via Map)
+     */
+    private getComponentIndex;
+    /**
+     * Get or compute query bitmask (optimized - computes mask without caching)
+     */
+    private getQueryMask;
+    /**
+     * Spawn a new entity.
+     * Returns the entity ID.
+     */
+    spawn(): Entity;
+    /**
+     * Despawn an entity, removing all its components.
+     * The entity ID will be reused.
+     */
+    despawn(entity: Entity): void;
+    /**
+     * Check if an entity is alive
+     */
+    isAlive(entity: Entity): boolean;
+    /**
+     * Add a component to an entity with initial data.
+     */
+    add<T extends object>(entity: Entity, component: Component<T>, data: T): void;
+    /**
+     * Remove a component from an entity.
+     */
+    remove<T extends object>(entity: Entity, component: Component<T>): void;
+    /**
+     * Check if an entity has a component.
+     */
+    has<T extends object>(entity: Entity, component: Component<T>): boolean;
+    /**
+     * Get a component's data for an entity.
+     * Returns a READONLY reusable object (zero allocations).
+     *
+     * ⚠️ IMPORTANT: The returned object is reused and will be overwritten on the next get().
+     * To modify, use set() or update() instead.
+     * To keep multiple components, use getMutable() or spread operator.
+     *
+     * @example
+     * // ✅ CORRECT: Use immediately
+     * const t = world.get(entity, Transform);
+     * console.log(t.x, t.y);
+     *
+     * // ❌ WRONG: Storing reference
+     * const t1 = world.get(entity1, Transform);
+     * const t2 = world.get(entity2, Transform); // t1 is now corrupted!
+     *
+     * // ✅ CORRECT: Copy if you need to keep
+     * const t1 = { ...world.get(entity1, Transform) };
+     * const t2 = { ...world.get(entity2, Transform) };
+     */
+    get<T extends object>(entity: Entity, component: Component<T>): 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<T extends object>(entity: Entity, component: Component<T>): T;
+    /**
+     * Set a component's data for an entity.
+     * Overwrites all fields.
+     */
+    set<T extends object>(entity: Entity, component: Component<T>, data: T): void;
+    /**
+     * Update specific fields of a component.
+     * More efficient than get + modify + set.
+     *
+     * @example
+     * // ✅ GOOD: Partial update
+     * world.update(entity, Transform, { x: 150 });
+     *
+     * // ❌ BAD: Full get/set for single field
+     * const t = world.getMutable(entity, Transform);
+     * t.x = 150;
+     * world.set(entity, Transform, t);
+     */
+    update<T extends object>(entity: Entity, component: Component<T>, partial: Partial<T>): void;
+    /**
+     * Query entities that have all specified components.
+     * Returns a readonly array for zero-allocation iteration.
+     *
+     * Uses reusable buffers and direct bitmask checks for maximum performance.
+     * The returned array is reused on subsequent queries with the same mask.
+     *
+     * @example
+     * ```typescript
+     * for (const entity of world.query(Transform, Velocity)) {
+     *   const t = world.get(entity, Transform);
+     *   const v = world.get(entity, Velocity);
+     *   world.update(entity, Transform, {
+     *     x: t.x + v.vx * dt,
+     *     y: t.y + v.vy * dt
+     *   });
+     * }
+     * ```
+     */
+    query(...components: Component<any>[]): readonly Entity[];
+    /**
+     * Get all alive entity IDs.
+     *
+     * ⚠️ WARNING: The returned array is a direct reference and should not be modified.
+     * For a safe copy, use [...world.getEntities()].
+     */
+    getEntities(): readonly Entity[];
+    /**
+     * Get the number of alive entities.
+     */
+    getEntityCount(): number;
+    /**
+     * Get the maximum number of entities.
+     */
+    getMaxEntities(): number;
+    /**
+     * Get all registered components.
+     */
+    getComponents(): readonly Component<any>[];
+    /**
+     * Get component names for an entity (for debugging)
+     */
+    private getEntityComponentNames;
+    /**
+     * Serialize entities with specific components to binary.
+     * Uses PooledCodec internally for efficient encoding.
+     *
+     * @param components Components to include in the snapshot
+     * @param entities Optional list of entities to serialize (defaults to all)
+     * @returns Binary buffer with serialized data
+     */
+    serialize(components: Component<any>[], entities?: Entity[]): Uint8Array;
+    /**
+     * Deserialize binary data into entities.
+     * Uses PooledCodec internally for efficient decoding.
+     *
+     * Note: This is a basic implementation. For production use,
+     * you'd want a more sophisticated format with component IDs, etc.
+     */
+    deserialize(components: Component<any>[], buffer: Uint8Array): void;
+}