@nice2dev/game-engine 1.0.4 → 1.0.10

package/dist/cjs/performance/ECSOptimization.js

@@ -0,0 +1,726 @@
+'use strict';
+
+/**
+ * @file ECSOptimization.ts
+ * @description Optimized ECS with SIMD-like operations and job scheduling
+ * PRO-1.5: Runtime & Performance
+ *
+ * Features:
+ * - SIMD-like batch operations on typed arrays
+ * - Job scheduler for parallel system execution
+ * - Component pools with cache-friendly layout
+ * - Query caching and invalidation
+ * - Archetype-based storage
+ * - System dependency graph
+ * - Batch entity operations
+ * - Memory-aligned components
+ */
+// ============================================================
+// Constants
+// ============================================================
+const DEFAULT_ARCHETYPE_CAPACITY = 1024;
+// ============================================================
+// Component Registry
+// ============================================================
+class ComponentRegistry {
+    constructor() {
+        this.schemas = new Map();
+        this.nameToId = new Map();
+        this.nextId = 0;
+    }
+    register(name, fields) {
+        if (this.nameToId.has(name)) {
+            return this.nameToId.get(name);
+        }
+        const id = this.nextId++;
+        let offset = 0;
+        let maxAlignment = 1;
+        const processedFields = fields.map((f) => {
+            const size = this.getFieldSize(f.type) * f.count;
+            const alignment = this.getFieldAlignment(f.type);
+            maxAlignment = Math.max(maxAlignment, alignment);
+            // Align offset
+            offset = Math.ceil(offset / alignment) * alignment;
+            const field = { ...f, offset };
+            offset += size;
+            return field;
+        });
+        // Align total size
+        const size = Math.ceil(offset / maxAlignment) * maxAlignment;
+        const schema = {
+            id,
+            name,
+            size,
+            alignment: maxAlignment,
+            fields: processedFields,
+        };
+        this.schemas.set(id, schema);
+        this.nameToId.set(name, id);
+        return id;
+    }
+    getSchema(id) {
+        return this.schemas.get(id);
+    }
+    getIdByName(name) {
+        return this.nameToId.get(name);
+    }
+    getFieldSize(type) {
+        switch (type) {
+            case 'f64':
+                return 8;
+            case 'f32':
+            case 'i32':
+            case 'u32':
+                return 4;
+            case 'i16':
+            case 'u16':
+                return 2;
+            case 'i8':
+            case 'u8':
+            case 'bool':
+                return 1;
+        }
+    }
+    getFieldAlignment(type) {
+        return this.getFieldSize(type);
+    }
+}
+// ============================================================
+// Archetype Manager
+// ============================================================
+class ArchetypeManager {
+    constructor(componentRegistry) {
+        this.archetypes = new Map();
+        this.componentRegistry = componentRegistry;
+    }
+    getOrCreateArchetype(componentIds) {
+        const sorted = [...componentIds].sort((a, b) => a - b);
+        const id = sorted.join(',');
+        if (this.archetypes.has(id)) {
+            return this.archetypes.get(id);
+        }
+        let mask = BigInt(0);
+        for (const cid of sorted) {
+            mask |= BigInt(1) << BigInt(cid);
+        }
+        const archetype = {
+            id,
+            componentMask: mask,
+            componentIds: sorted,
+            entityCount: 0,
+            capacity: DEFAULT_ARCHETYPE_CAPACITY,
+            storage: new Map(),
+            entities: new Array(DEFAULT_ARCHETYPE_CAPACITY),
+        };
+        // Allocate storage for each component
+        for (const cid of sorted) {
+            const schema = this.componentRegistry.getSchema(cid);
+            if (schema) {
+                archetype.storage.set(cid, new ArrayBuffer(schema.size * DEFAULT_ARCHETYPE_CAPACITY));
+            }
+        }
+        this.archetypes.set(id, archetype);
+        return archetype;
+    }
+    ensureCapacity(archetype, needed) {
+        if (archetype.capacity >= needed) {
+            return;
+        }
+        const newCapacity = Math.max(archetype.capacity * 2, needed);
+        // Resize entity array
+        const newEntities = new Array(newCapacity);
+        for (let i = 0; i < archetype.entityCount; i++) {
+            newEntities[i] = archetype.entities[i];
+        }
+        archetype.entities = newEntities;
+        // Resize component storage
+        for (const cid of archetype.componentIds) {
+            const schema = this.componentRegistry.getSchema(cid);
+            if (!schema) {
+                continue;
+            }
+            const oldBuffer = archetype.storage.get(cid);
+            const newBuffer = new ArrayBuffer(schema.size * newCapacity);
+            new Uint8Array(newBuffer).set(new Uint8Array(oldBuffer));
+            archetype.storage.set(cid, newBuffer);
+        }
+        archetype.capacity = newCapacity;
+    }
+    getArchetypes() {
+        return Array.from(this.archetypes.values());
+    }
+    findArchetypesWithComponents(componentIds) {
+        let mask = BigInt(0);
+        for (const cid of componentIds) {
+            mask |= BigInt(1) << BigInt(cid);
+        }
+        return Array.from(this.archetypes.values()).filter((a) => (a.componentMask & mask) === mask);
+    }
+    findArchetypesWithoutComponents(componentIds) {
+        let mask = BigInt(0);
+        for (const cid of componentIds) {
+            mask |= BigInt(1) << BigInt(cid);
+        }
+        return Array.from(this.archetypes.values()).filter((a) => (a.componentMask & mask) === BigInt(0));
+    }
+}
+// ============================================================
+// Query Cache
+// ============================================================
+class QueryCache {
+    constructor() {
+        this.cache = new Map();
+        this.descriptors = new Map();
+        this.invalidated = new Set();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    register(descriptor) {
+        this.descriptors.set(descriptor.id, descriptor);
+        this.invalidated.add(descriptor.id);
+    }
+    get(id) {
+        if (this.invalidated.has(id)) {
+            this.misses++;
+            return undefined;
+        }
+        const result = this.cache.get(id);
+        if (result) {
+            this.hits++;
+        }
+        else {
+            this.misses++;
+        }
+        return result;
+    }
+    set(id, result) {
+        this.cache.set(id, result);
+        this.invalidated.delete(id);
+    }
+    invalidate(componentId) {
+        for (const [id, desc] of this.descriptors) {
+            if (desc.include.includes(componentId) || desc.exclude.includes(componentId)) {
+                this.invalidated.add(id);
+            }
+        }
+    }
+    invalidateAll() {
+        for (const id of this.descriptors.keys()) {
+            this.invalidated.add(id);
+        }
+    }
+    getStats() {
+        return { hits: this.hits, misses: this.misses };
+    }
+}
+// ============================================================
+// Job Scheduler
+// ============================================================
+class JobScheduler {
+    constructor() {
+        this.jobs = new Map();
+        this.executionOrder = [];
+        this.handles = new Map();
+        this.dirty = true;
+    }
+    register(job) {
+        this.jobs.set(job.id, job);
+        this.dirty = true;
+    }
+    unregister(jobId) {
+        this.jobs.delete(jobId);
+        this.dirty = true;
+    }
+    setEnabled(jobId, enabled) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            job.enabled = enabled;
+        }
+    }
+    buildExecutionOrder() {
+        if (!this.dirty) {
+            return;
+        }
+        const enabledJobs = Array.from(this.jobs.values()).filter((j) => j.enabled);
+        // Topological sort with dependency resolution
+        const visited = new Set();
+        const order = [];
+        const visit = (jobId) => {
+            if (visited.has(jobId)) {
+                return;
+            }
+            visited.add(jobId);
+            const job = this.jobs.get(jobId);
+            if (!job || !job.enabled) {
+                return;
+            }
+            for (const dep of job.dependencies) {
+                visit(dep);
+            }
+            order.push(jobId);
+        };
+        // Sort by priority first
+        enabledJobs.sort((a, b) => b.priority - a.priority);
+        for (const job of enabledJobs) {
+            visit(job.id);
+        }
+        this.executionOrder = order;
+        this.dirty = false;
+    }
+    execute(world, deltaTime) {
+        this.buildExecutionOrder();
+        const frameHandles = new Map();
+        for (const jobId of this.executionOrder) {
+            const job = this.jobs.get(jobId);
+            if (!job || !job.enabled) {
+                continue;
+            }
+            const handle = {
+                id: jobId,
+                status: 'running',
+                startTime: performance.now(),
+            };
+            frameHandles.set(jobId, handle);
+            try {
+                job.fn(world, deltaTime);
+                handle.status = 'complete';
+            }
+            catch (error) {
+                handle.status = 'failed';
+                handle.error = error;
+            }
+            handle.endTime = performance.now();
+        }
+        this.handles = frameHandles;
+        return frameHandles;
+    }
+    getExecutionOrder() {
+        this.buildExecutionOrder();
+        return [...this.executionOrder];
+    }
+    getLastHandles() {
+        return new Map(this.handles);
+    }
+    canParallelize(jobA, jobB) {
+        const a = this.jobs.get(jobA);
+        const b = this.jobs.get(jobB);
+        if (!a || !b) {
+            return false;
+        }
+        // Check for write conflicts
+        for (const writeA of a.writeComponents) {
+            if (b.readComponents.includes(writeA) || b.writeComponents.includes(writeA)) {
+                return false;
+            }
+        }
+        for (const writeB of b.writeComponents) {
+            if (a.readComponents.includes(writeB)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+// ============================================================
+// SIMD-like Batch Operations
+// ============================================================
+class SIMDOperations {
+    /**
+     * Add two float32 arrays element-wise
+     */
+    static addF32(a, b, out) {
+        const len = Math.min(a.length, b.length, out.length);
+        // Unroll loop for better performance
+        let i = 0;
+        for (; i + 4 <= len; i += 4) {
+            out[i] = a[i] + b[i];
+            out[i + 1] = a[i + 1] + b[i + 1];
+            out[i + 2] = a[i + 2] + b[i + 2];
+            out[i + 3] = a[i + 3] + b[i + 3];
+        }
+        for (; i < len; i++) {
+            out[i] = a[i] + b[i];
+        }
+    }
+    /**
+     * Multiply float32 array by scalar
+     */
+    static mulScalarF32(a, scalar, out) {
+        const len = Math.min(a.length, out.length);
+        let i = 0;
+        for (; i + 4 <= len; i += 4) {
+            out[i] = a[i] * scalar;
+            out[i + 1] = a[i + 1] * scalar;
+            out[i + 2] = a[i + 2] * scalar;
+            out[i + 3] = a[i + 3] * scalar;
+        }
+        for (; i < len; i++) {
+            out[i] = a[i] * scalar;
+        }
+    }
+    /**
+     * Fused multiply-add: out = a * b + c
+     */
+    static fmaF32(a, b, c, out) {
+        const len = Math.min(a.length, b.length, c.length, out.length);
+        let i = 0;
+        for (; i + 4 <= len; i += 4) {
+            out[i] = a[i] * b[i] + c[i];
+            out[i + 1] = a[i + 1] * b[i + 1] + c[i + 1];
+            out[i + 2] = a[i + 2] * b[i + 2] + c[i + 2];
+            out[i + 3] = a[i + 3] * b[i + 3] + c[i + 3];
+        }
+        for (; i < len; i++) {
+            out[i] = a[i] * b[i] + c[i];
+        }
+    }
+    /**
+     * Linear interpolation
+     */
+    static lerpF32(a, b, t, out) {
+        const len = Math.min(a.length, b.length, out.length);
+        const oneMinusT = 1 - t;
+        let i = 0;
+        for (; i + 4 <= len; i += 4) {
+            out[i] = a[i] * oneMinusT + b[i] * t;
+            out[i + 1] = a[i + 1] * oneMinusT + b[i + 1] * t;
+            out[i + 2] = a[i + 2] * oneMinusT + b[i + 2] * t;
+            out[i + 3] = a[i + 3] * oneMinusT + b[i + 3] * t;
+        }
+        for (; i < len; i++) {
+            out[i] = a[i] * oneMinusT + b[i] * t;
+        }
+    }
+    /**
+     * Dot product of 3D vectors stored in SOA format
+     */
+    static dot3DSOA(ax, ay, az, bx, by, bz, out) {
+        const len = Math.min(ax.length, ay.length, az.length, bx.length, by.length, bz.length, out.length);
+        for (let i = 0; i < len; i++) {
+            out[i] = ax[i] * bx[i] + ay[i] * by[i] + az[i] * bz[i];
+        }
+    }
+    /**
+     * Normalize 3D vectors stored in SOA format
+     */
+    static normalize3DSOA(x, y, z, outX, outY, outZ) {
+        const len = Math.min(x.length, y.length, z.length);
+        for (let i = 0; i < len; i++) {
+            const lenSq = x[i] * x[i] + y[i] * y[i] + z[i] * z[i];
+            if (lenSq > 0) {
+                const invLen = 1 / Math.sqrt(lenSq);
+                outX[i] = x[i] * invLen;
+                outY[i] = y[i] * invLen;
+                outZ[i] = z[i] * invLen;
+            }
+            else {
+                outX[i] = 0;
+                outY[i] = 0;
+                outZ[i] = 0;
+            }
+        }
+    }
+    /**
+     * Cross product of 3D vectors stored in SOA format
+     */
+    static cross3DSOA(ax, ay, az, bx, by, bz, outX, outY, outZ) {
+        const len = Math.min(ax.length, ay.length, az.length);
+        for (let i = 0; i < len; i++) {
+            outX[i] = ay[i] * bz[i] - az[i] * by[i];
+            outY[i] = az[i] * bx[i] - ax[i] * bz[i];
+            outZ[i] = ax[i] * by[i] - ay[i] * bx[i];
+        }
+    }
+    /**
+     * Transform 3D positions by 4x4 matrix (assumes w=1)
+     */
+    static transformPositions(x, y, z, matrix, // 16 elements, column-major
+    outX, outY, outZ) {
+        const len = Math.min(x.length, y.length, z.length);
+        for (let i = 0; i < len; i++) {
+            outX[i] = matrix[0] * x[i] + matrix[4] * y[i] + matrix[8] * z[i] + matrix[12];
+            outY[i] = matrix[1] * x[i] + matrix[5] * y[i] + matrix[9] * z[i] + matrix[13];
+            outZ[i] = matrix[2] * x[i] + matrix[6] * y[i] + matrix[10] * z[i] + matrix[14];
+        }
+    }
+}
+// ============================================================
+// Optimized World
+// ============================================================
+class OptimizedWorld {
+    constructor() {
+        this.componentRegistry = new ComponentRegistry();
+        this.queryCache = new QueryCache();
+        this.jobScheduler = new JobScheduler();
+        // Entity management
+        this.entityToArchetype = new Map();
+        this.freeEntityIds = [];
+        this.nextEntityId = 1;
+        // Performance tracking
+        this.stats = {
+            frameTime: 0,
+            systemTimes: new Map(),
+            entityCount: 0,
+            componentCount: 0,
+            archetypeCount: 0,
+            queryCount: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            memoryUsed: 0,
+        };
+        this.archetypeManager = new ArchetypeManager(this.componentRegistry);
+    }
+    // ─── Component Registration ────────────────────────────
+    registerComponent(name, fields) {
+        return this.componentRegistry.register(name, fields);
+    }
+    getComponentId(name) {
+        return this.componentRegistry.getIdByName(name);
+    }
+    getComponentSchema(id) {
+        return this.componentRegistry.getSchema(id);
+    }
+    // ─── Entity Management ─────────────────────────────────
+    createEntity(componentIds) {
+        const id = this.freeEntityIds.pop() ?? this.nextEntityId++;
+        const archetype = this.archetypeManager.getOrCreateArchetype(componentIds);
+        this.archetypeManager.ensureCapacity(archetype, archetype.entityCount + 1);
+        const index = archetype.entityCount++;
+        archetype.entities[index] = id;
+        this.entityToArchetype.set(id, { archetype, index });
+        this.queryCache.invalidateAll();
+        this.stats.entityCount++;
+        return id;
+    }
+    createEntities(componentIds, count) {
+        const ids = [];
+        const archetype = this.archetypeManager.getOrCreateArchetype(componentIds);
+        this.archetypeManager.ensureCapacity(archetype, archetype.entityCount + count);
+        for (let i = 0; i < count; i++) {
+            const id = this.freeEntityIds.pop() ?? this.nextEntityId++;
+            const index = archetype.entityCount++;
+            archetype.entities[index] = id;
+            this.entityToArchetype.set(id, { archetype, index });
+            ids.push(id);
+        }
+        this.queryCache.invalidateAll();
+        this.stats.entityCount += count;
+        return ids;
+    }
+    destroyEntity(id) {
+        const location = this.entityToArchetype.get(id);
+        if (!location) {
+            return false;
+        }
+        const { archetype, index } = location;
+        // Swap with last entity
+        const lastIndex = archetype.entityCount - 1;
+        if (index !== lastIndex) {
+            const lastEntityId = archetype.entities[lastIndex];
+            archetype.entities[index] = lastEntityId;
+            // Update storage
+            for (const cid of archetype.componentIds) {
+                const schema = this.componentRegistry.getSchema(cid);
+                if (!schema) {
+                    continue;
+                }
+                const buffer = archetype.storage.get(cid);
+                const view = new Uint8Array(buffer);
+                view.copyWithin(index * schema.size, lastIndex * schema.size, (lastIndex + 1) * schema.size);
+            }
+            this.entityToArchetype.set(lastEntityId, { archetype, index });
+        }
+        archetype.entityCount--;
+        this.entityToArchetype.delete(id);
+        this.freeEntityIds.push(id);
+        this.queryCache.invalidateAll();
+        this.stats.entityCount--;
+        return true;
+    }
+    hasEntity(id) {
+        return this.entityToArchetype.has(id);
+    }
+    // ─── Component Access ──────────────────────────────────
+    getComponentBuffer(entityId, componentId) {
+        const location = this.entityToArchetype.get(entityId);
+        if (!location) {
+            return null;
+        }
+        const { archetype, index } = location;
+        const schema = this.componentRegistry.getSchema(componentId);
+        if (!schema) {
+            return null;
+        }
+        const buffer = archetype.storage.get(componentId);
+        if (!buffer) {
+            return null;
+        }
+        return buffer.slice(index * schema.size, (index + 1) * schema.size);
+    }
+    setComponentData(entityId, componentId, data) {
+        const location = this.entityToArchetype.get(entityId);
+        if (!location) {
+            return false;
+        }
+        const { archetype, index } = location;
+        const schema = this.componentRegistry.getSchema(componentId);
+        if (!schema) {
+            return false;
+        }
+        const buffer = archetype.storage.get(componentId);
+        if (!buffer) {
+            return false;
+        }
+        new Uint8Array(buffer, index * schema.size, schema.size).set(new Uint8Array(data));
+        return true;
+    }
+    // ─── Queries ───────────────────────────────────────────
+    registerQuery(descriptor) {
+        this.queryCache.register(descriptor);
+    }
+    query(descriptor) {
+        // Try cache
+        let result = this.queryCache.get(descriptor.id);
+        if (result) {
+            return result;
+        }
+        // Find matching archetypes
+        const withComponents = this.archetypeManager.findArchetypesWithComponents(descriptor.include);
+        const archetypes = descriptor.exclude.length > 0
+            ? withComponents.filter((a) => {
+                for (const excl of descriptor.exclude) {
+                    if ((a.componentMask & (BigInt(1) << BigInt(excl))) !== BigInt(0)) {
+                        return false;
+                    }
+                }
+                return true;
+            })
+            : withComponents;
+        result = {
+            archetypes,
+            entityCount: archetypes.reduce((sum, a) => sum + a.entityCount, 0),
+            lastUpdated: performance.now(),
+        };
+        if (descriptor.cached) {
+            this.queryCache.set(descriptor.id, result);
+        }
+        this.stats.queryCount++;
+        return result;
+    }
+    // ─── Batch Operations ──────────────────────────────────
+    executeBatch(operations) {
+        for (const op of operations) {
+            switch (op.type) {
+                case 'create':
+                    if (op.count && op.componentId !== undefined) {
+                        this.createEntities([op.componentId], op.count);
+                    }
+                    break;
+                case 'destroy':
+                    if (op.entities) {
+                        for (const id of op.entities) {
+                            this.destroyEntity(id);
+                        }
+                    }
+                    break;
+            }
+        }
+    }
+    // ─── System Management ─────────────────────────────────
+    registerSystem(job) {
+        this.jobScheduler.register(job);
+    }
+    unregisterSystem(jobId) {
+        this.jobScheduler.unregister(jobId);
+    }
+    setSystemEnabled(jobId, enabled) {
+        this.jobScheduler.setEnabled(jobId, enabled);
+    }
+    // ─── Update ────────────────────────────────────────────
+    update(deltaTime) {
+        const startTime = performance.now();
+        const handles = this.jobScheduler.execute(this, deltaTime);
+        // Update stats
+        for (const [id, handle] of handles) {
+            if (handle.startTime && handle.endTime) {
+                this.stats.systemTimes.set(id, handle.endTime - handle.startTime);
+            }
+        }
+        this.stats.frameTime = performance.now() - startTime;
+        this.stats.archetypeCount = this.archetypeManager.getArchetypes().length;
+        const cacheStats = this.queryCache.getStats();
+        this.stats.cacheHits = cacheStats.hits;
+        this.stats.cacheMisses = cacheStats.misses;
+    }
+    // ─── Stats ─────────────────────────────────────────────
+    getStats() {
+        return { ...this.stats };
+    }
+    // ─── Direct Access ─────────────────────────────────────
+    getComponentRegistry() {
+        return this.componentRegistry;
+    }
+    getArchetypeManager() {
+        return this.archetypeManager;
+    }
+    getJobScheduler() {
+        return this.jobScheduler;
+    }
+    /**
+     * Get typed array view for a component field across all entities in query
+     */
+    getComponentFieldArray(queryResult, componentId, fieldName, arrayType) {
+        const schema = this.componentRegistry.getSchema(componentId);
+        if (!schema) {
+            return null;
+        }
+        const field = schema.fields.find((f) => f.name === fieldName);
+        if (!field) {
+            return null;
+        }
+        // For simplicity, return first archetype's data
+        // Real implementation would concatenate or provide iterator
+        const archetype = queryResult.archetypes[0];
+        if (!archetype || archetype.entityCount === 0) {
+            return null;
+        }
+        const buffer = archetype.storage.get(componentId);
+        if (!buffer) {
+            return null;
+        }
+        // This assumes SOA layout - real implementation would handle both SOA and AOS
+        return new arrayType(buffer, field.offset, archetype.entityCount * field.count);
+    }
+}
+// ============================================================
+// Factory Functions
+// ============================================================
+function createOptimizedWorld() {
+    return new OptimizedWorld();
+}
+function createSystemJob(id, name, fn, options = {}) {
+    return {
+        id,
+        name,
+        fn,
+        dependencies: options.dependencies ?? [],
+        readComponents: options.readComponents ?? [],
+        writeComponents: options.writeComponents ?? [],
+        priority: options.priority ?? 0,
+        enabled: options.enabled ?? true,
+    };
+}
+function createQueryDescriptor(id, include, exclude = [], cached = true) {
+    return { id, include, exclude, cached };
+}
+
+exports.ArchetypeManager = ArchetypeManager;
+exports.ComponentRegistry = ComponentRegistry;
+exports.JobScheduler = JobScheduler;
+exports.OptimizedWorld = OptimizedWorld;
+exports.QueryCache = QueryCache;
+exports.SIMDOperations = SIMDOperations;
+exports.createOptimizedWorld = createOptimizedWorld;
+exports.createQueryDescriptor = createQueryDescriptor;
+exports.createSystemJob = createSystemJob;
+//# sourceMappingURL=ECSOptimization.js.map