murow 0.0.60 → 0.0.71

package/dist/ecs/system-builder.js

@@ -1,180 +0,0 @@
-/**
- * Builder for creating ergonomic systems with automatic field array caching.
- *
- * Fully chainable API with type safety:
- * - System automatically caches TypedArrays and creates proxies
- * - Two access patterns: ergonomic (getter/setter) or hybrid (direct array)
- * - Full type safety with IntelliSense support for both patterns
- *
- * **Ergonomic pattern (convenient but slower):**
- * ```typescript
- * world.addSystem()
- *   .query(Transform2D, Velocity)
- *   .fields([{ transform: ['x', 'y'] }, { velocity: ['vx', 'vy'] }])
- *   .run((entity, deltaTime) => {
- *     // Fully typed property access (uses getters/setters)
- *     entity.transform_x += entity.velocity_vx * deltaTime;
- *   });
- * ```
- *
- * **Hybrid pattern (fast and still ergonomic):**
- * ```typescript
- * world.addSystem()
- *   .query(Transform2D, Velocity)
- *   .fields([{ transform: ['x', 'y'] }, { velocity: ['vx', 'vy'] }])
- *   .run((entity, deltaTime) => {
- *     // Fully typed direct array access (no getters/setters)
- *     const {eid, transform_x_array: tx, velocity_vx_array: vx} = entity;
- *     tx[eid] += vx[eid] * deltaTime;
- *   });
- * ```
- *
- * **Note:** The hybrid pattern is recommended for performance-critical systems.
- * Both patterns provide full TypeScript autocomplete and type checking.
- */
-export class SystemBuilder {
-    constructor(world, components, fieldMappings, userCallback) {
-        this.world = world;
-        this.components = components;
-        this.fieldMappings = fieldMappings;
-        this.userCallback = userCallback;
-    }
-    /**
-     * Specify which components this system should query for.
-     */
-    query(...components) {
-        return new SystemBuilder(this.world, components, this.fieldMappings, this.userCallback);
-    }
-    /**
-     * Specify which component fields should be accessible via proxy.
-     */
-    fields(fieldMappings) {
-        return new SystemBuilder(this.world, this.components, fieldMappings, this.userCallback);
-    }
-    /**
-     * Set the system callback. If components and fields are set, builds the system.
-     */
-    run(callback) {
-        const builder = new SystemBuilder(this.world, this.components, this.fieldMappings, callback);
-        return builder.buildAndRegister();
-    }
-    /**
-     * Build and register the system.
-     * @internal
-     */
-    buildAndRegister() {
-        if (!this.userCallback) {
-            throw new Error('System callback must be set');
-        }
-        if (!this.fieldMappings) {
-            throw new Error('Field mappings must be set');
-        }
-        const world = this.world;
-        const components = this.components;
-        const fieldMappings = this.fieldMappings;
-        const userCallback = this.userCallback;
-        // Cache field arrays once at system creation
-        const fieldArrayCache = {};
-        const componentByAlias = {};
-        const aliases = [];
-        // Iterate over components and their field mappings
-        for (let i = 0; i < components.length; i++) {
-            const component = components[i];
-            const mapping = fieldMappings[i];
-            if (!mapping)
-                continue;
-            // Extract alias and fields from { alias: ['fields'] } object
-            const alias = Object.keys(mapping)[0];
-            const fields = mapping[alias];
-            aliases.push(alias);
-            componentByAlias[alias] = component;
-            fieldArrayCache[alias] = {};
-            // Cache all field arrays for this component
-            for (const fieldName of fields) {
-                const array = world.getFieldArray(component, fieldName);
-                fieldArrayCache[alias][fieldName] = array;
-            }
-        }
-        // Precompute query mask and mask key for fast queries
-        // This avoids rebuilding the cache key string every frame
-        world.query(...components); // Initializes the cache
-        const queryMaskKey = world._getQueryMaskKey(components);
-        const queryMask = world.getQueryMask(components);
-        // Create the executable system
-        const system = new ExecutableSystem(world, components, userCallback, fieldArrayCache, componentByAlias, aliases, queryMaskKey, queryMask);
-        // Register with world
-        world._registerSystem(system);
-        return system;
-    }
-}
-/**
- * Executable system that can be run with world.runSystems().
- *
- * Uses reusable proxy entity with optimized getter/setter access.
- */
-export class ExecutableSystem {
-    constructor(world, components, userCallback, fieldArrayCache, componentByAlias, aliases, queryMaskKey, queryMask) {
-        this.world = world;
-        this.components = components;
-        this.userCallback = userCallback;
-        this.fieldArrayCache = fieldArrayCache;
-        this.componentByAlias = componentByAlias;
-        this.aliases = aliases;
-        this.queryMaskKey = queryMaskKey;
-        this.queryMask = queryMask;
-        // Create proxy entity once and reuse
-        this.proxyEntity = this.createProxyEntity();
-    }
-    /**
-     * Execute the system for all matching entities.
-     *
-     * @param deltaTime - Time delta to pass to system callback
-     */
-    execute(deltaTime) {
-        // Use precomputed mask key and mask to bypass getQueryMask() overhead
-        const entities = this.world._queryByMaskKey(this.queryMaskKey, this.queryMask);
-        const callback = this.userCallback;
-        const world = this.world;
-        const entity = this.proxyEntity;
-        // Execute callback for each entity
-        const length = entities.length;
-        for (let i = 0; i < length; i++) {
-            entity.eid = entities[i];
-            callback(entity, deltaTime, world);
-        }
-    }
-    /**
-     * Create proxy entity that exposes arrays directly.
-     *
-     * Instead of entity.transform_x (getter/setter),
-     * use entity.transform_x_array[entity.eid] for direct access.
-     *
-     * BUT ALSO provide getter/setter for convenience.
-     */
-    createProxyEntity() {
-        const entity = { eid: 0 };
-        // Expose arrays directly AND provide getter/setter for ergonomics
-        for (const alias of this.aliases) {
-            const fields = this.fieldArrayCache[alias];
-            for (const [fieldName, array] of Object.entries(fields)) {
-                const flattenedName = `${alias}_${fieldName}`;
-                // Direct array access (FAST - for power users)
-                entity[`${flattenedName}_array`] = array;
-                // Getter/setter access (SLOW but ergonomic)
-                Object.defineProperty(entity, flattenedName, {
-                    get() { return array[this.eid]; },
-                    set(value) { array[this.eid] = value; },
-                    enumerable: true,
-                    configurable: false
-                });
-            }
-        }
-        return entity;
-    }
-    /**
-     * Get the components this system operates on.
-     */
-    getComponents() {
-        return this.components;
-    }
-}

package/dist/ecs/system.d.ts

@@ -1,63 +0,0 @@
-import { Component } from "./component";
-import { Entity, World } from "./world";
-/**
- * System helper that provides automatic field array caching.
- *
- * Combines the ergonomics of EntityHandle with the performance of RAW API.
- * Field arrays are cached on first access for zero-cost abstraction.
- *
- * @example
- * ```typescript
- * // Create system once at initialization
- * const movement = world.system(Transform, Velocity);
- *
- * // Access field arrays - cached on first access
- * const { Transform_x: tx, Transform_y: ty, Velocity_vx: vx, Velocity_vy: vy } = movement.fields;
- *
- * // In game loop - direct array access (RAW API performance)
- * for (const eid of movement.query()) {
- *   tx[eid] += vx[eid] * dt;
- *   ty[eid] += vy[eid] * dt;
- * }
- * ```
- */
-export declare class System<C extends Component<any>[]> {
-    private world;
-    private components;
-    private fieldCache;
-    /**
-     * Proxy that automatically caches field arrays on first access.
-     * Access fields using ComponentName_fieldName format.
-     */
-    readonly fields: any;
-    constructor(world: World, components: C);
-    /**
-     * Query entities matching the system's components.
-     *
-     * @returns Array of entity IDs
-     *
-     * @example
-     * ```typescript
-     * for (const eid of system.query()) {
-     *   // Process entity...
-     * }
-     * ```
-     */
-    query(): readonly Entity[];
-    /**
-     * Run a callback for each entity in the query.
-     * Convenience method that combines query() with a loop.
-     *
-     * @param fn - Callback function that receives entity ID and system instance
-     *
-     * @example
-     * ```typescript
-     * const { Transform_x: tx, Velocity_vx: vx } = system.fields;
-     *
-     * system.run((eid) => {
-     *   tx[eid] += vx[eid] * dt;
-     * });
-     * ```
-     */
-    run(fn: (eid: Entity, sys: this) => void): void;
-}

package/dist/ecs/system.js

@@ -1,92 +0,0 @@
-/**
- * System helper that provides automatic field array caching.
- *
- * Combines the ergonomics of EntityHandle with the performance of RAW API.
- * Field arrays are cached on first access for zero-cost abstraction.
- *
- * @example
- * ```typescript
- * // Create system once at initialization
- * const movement = world.system(Transform, Velocity);
- *
- * // Access field arrays - cached on first access
- * const { Transform_x: tx, Transform_y: ty, Velocity_vx: vx, Velocity_vy: vy } = movement.fields;
- *
- * // In game loop - direct array access (RAW API performance)
- * for (const eid of movement.query()) {
- *   tx[eid] += vx[eid] * dt;
- *   ty[eid] += vy[eid] * dt;
- * }
- * ```
- */
-export class System {
-    constructor(world, components) {
-        this.world = world;
-        this.components = components;
-        this.fieldCache = {};
-        const cache = this.fieldCache;
-        const worldRef = this.world;
-        const componentsRef = this.components;
-        // Create proxy that auto-caches field arrays
-        this.fields = new Proxy({}, {
-            get(target, prop) {
-                // Check cache first
-                if (cache[prop] !== undefined) {
-                    return cache[prop];
-                }
-                // Parse "ComponentName_fieldName" format
-                const underscoreIndex = prop.indexOf('_');
-                if (underscoreIndex === -1) {
-                    return undefined;
-                }
-                const compName = prop.substring(0, underscoreIndex);
-                const fieldName = prop.substring(underscoreIndex + 1);
-                // Find component by name
-                const component = componentsRef.find(c => c.name === compName);
-                if (component && fieldName) {
-                    // Get and cache the field array
-                    const array = worldRef.getFieldArray(component, fieldName);
-                    cache[prop] = array;
-                    return array;
-                }
-                return undefined;
-            }
-        });
-    }
-    /**
-     * Query entities matching the system's components.
-     *
-     * @returns Array of entity IDs
-     *
-     * @example
-     * ```typescript
-     * for (const eid of system.query()) {
-     *   // Process entity...
-     * }
-     * ```
-     */
-    query() {
-        return this.world.query(...this.components);
-    }
-    /**
-     * Run a callback for each entity in the query.
-     * Convenience method that combines query() with a loop.
-     *
-     * @param fn - Callback function that receives entity ID and system instance
-     *
-     * @example
-     * ```typescript
-     * const { Transform_x: tx, Velocity_vx: vx } = system.fields;
-     *
-     * system.run((eid) => {
-     *   tx[eid] += vx[eid] * dt;
-     * });
-     * ```
-     */
-    run(fn) {
-        const entities = this.query();
-        for (let i = 0; i < entities.length; i++) {
-            fn(entities[i], this);
-        }
-    }
-}

package/dist/ecs/world-systems.js

@@ -1,79 +0,0 @@
-import { SystemBuilder } from "./system-builder";
-/**
- * Systems API for a World.
- *
- * The world extends this class to provide system building capabilities.
- *
- * **Performance Comparison** (50K entities benchmark):
- * - Raw API: 8.94ms (baseline - fastest)
- * - Hybrid API: 15.65ms (1.75x slower - recommended!)
- * - Ergonomic API: 18.79ms (2.1x slower - most convenient)
- *
- * **Recommendation:**
- * Use the hybrid API pattern (see examples below) for the best balance of
- * performance and ergonomics. It's only ~75% slower than raw while maintaining
- * the convenience of the system builder.
- */
-export class WorldSystems {
-    constructor() {
-        /** Registered systems that run automatically with runSystems() */
-        this.registeredSystems = [];
-    }
-    /**
-     * Create a new system builder for ergonomic system definition.
-     *
-     * @example
-     * Basic usage (ergonomic but ~2x slower):
-     * ```typescript
-     * world.addSystem()
-     *   .query(Transform2D, Velocity)
-     *   .fields([
-     *     { transform: ['x', 'y'] },
-     *     { velocity: ['vx', 'vy'] }
-     *   ])
-     *   .run((entity, deltaTime) => {
-     *     entity.transform_x += entity.velocity_vx * deltaTime;
-     *     entity.transform_y += entity.velocity_vy * deltaTime;
-     *   });
-     * ```
-     *
-     * @example
-     * Performance mode (raw speed, still ergonomic):
-     * ```typescript
-     * world.addSystem()
-     *   .query(Transform2D, Velocity)
-     *   .fields([
-     *     { transform: ['x', 'y'] },
-     *     { velocity: ['vx', 'vy'] }
-     *   ])
-     *   .run((entity, deltaTime) => {
-     *     // Destructure arrays for direct access (fast!)
-     *     const {eid, transform_x_array: tx, transform_y_array: ty,
-     *            velocity_vx_array: vx, velocity_vy_array: vy} = entity;
-     *     tx[eid] += vx[eid] * deltaTime;
-     *     ty[eid] += vy[eid] * deltaTime;
-     *   });
-     * ```
-     */
-    addSystem() {
-        return new SystemBuilder(this, [], undefined, undefined);
-    }
-    /**
-     * Run all registered systems with the given deltaTime.
-     * Systems are executed in registration order.
-     *
-     * @param deltaTime - Time delta to pass to each system
-     */
-    runSystems(deltaTime) {
-        for (let i = 0; i < this.registeredSystems.length; i++) {
-            this.registeredSystems[i].execute(deltaTime);
-        }
-    }
-    /**
-     * Register a system for automatic execution.
-     * @internal - Called by SystemBuilder
-     */
-    _registerSystem(system) {
-        this.registeredSystems.push(system);
-    }
-}