@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Systems/ProcessingSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessingSystem.d.ts","sourceRoot":"","sources":["../../../src/ECS/Systems/ProcessingSystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,8BAAsB,gBAAiB,SAAQ,YAAY;gBAE3C,OAAO,CAAC,EAAE,OAAO;IAI7B;;;OAGG;cACgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAKrD;;OAEG;aACa,aAAa,IAAI,IAAI;CACxC"}

package/bin/ECS/Systems/ProcessingSystem.js

@@ -0,0 +1,20 @@
+import { EntitySystem } from './EntitySystem';
+/**
+ * 处理系统抽象类
+ * 定义一个处理实体的抽象类，继承自EntitySystem类
+ * 子类需要实现processSystem方法，用于实现具体的处理逻辑
+ */
+export class ProcessingSystem extends EntitySystem {
+    constructor(matcher) {
+        super(matcher);
+    }
+    /**
+     * 处理实体，每帧调用processSystem方法进行处理
+     * @param entities 实体数组，未被使用
+     */
+    process(_entities) {
+        // 调用子类实现的processSystem方法进行实体处理
+        this.processSystem();
+    }
+}
+//# sourceMappingURL=ProcessingSystem.js.map

package/bin/ECS/Systems/ProcessingSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessingSystem.js","sourceRoot":"","sources":["../../../src/ECS/Systems/ProcessingSystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAI9C;;;;GAIG;AACH,MAAM,OAAgB,gBAAiB,SAAQ,YAAY;IAEvD,YAAY,OAAiB;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACnB,CAAC;IAED;;;OAGG;IACgB,OAAO,CAAC,SAAmB;QAC1C,+BAA+B;QAC/B,IAAI,CAAC,aAAa,EAAE,CAAC;IACzB,CAAC;CAMJ"}

package/bin/ECS/Systems/WorkerEntitySystem.d.ts

@@ -0,0 +1,313 @@
+import { Entity } from '../Entity';
+import { EntitySystem } from './EntitySystem';
+import { Matcher } from '../Utils/Matcher';
+/**
+ * Worker处理函数类型
+ * 用户编写的处理逻辑，会被序列化到Worker中执行
+ */
+export type WorkerProcessFunction<T extends Record<string, any> = any> = (entities: T[], deltaTime: number, config?: any) => T[] | Promise<T[]>;
+/**
+ * Worker配置接口
+ */
+export interface WorkerSystemConfig {
+    /** 是否启用Worker并行处理 */
+    enableWorker?: boolean;
+    /** Worker数量，默认为CPU核心数，自动限制在系统最大值内 */
+    workerCount?: number;
+    /** 每个Worker处理的实体数量，用于控制负载分布 */
+    entitiesPerWorker?: number;
+    /** 系统配置数据，会传递给Worker */
+    systemConfig?: any;
+    /** 是否使用SharedArrayBuffer优化 */
+    useSharedArrayBuffer?: boolean;
+    /** 每个实体在SharedArrayBuffer中占用的Float32数量 */
+    entityDataSize?: number;
+    /** 最大实体数量（用于预分配SharedArrayBuffer） */
+    maxEntities?: number;
+}
+/**
+ * SharedArrayBuffer处理函数类型
+ */
+export type SharedArrayBufferProcessFunction = (sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, systemConfig?: any) => void;
+/**
+ * 支持Worker并行处理的EntitySystem基类
+ *
+ * 支持传统Worker和SharedArrayBuffer两种优化模式：
+ * - 传统模式：数据序列化传输，适用于复杂计算
+ * - SharedArrayBuffer模式：零拷贝数据共享，适用于大量简单计算
+ *
+ * 用户需要实现：
+ * 1. extractEntityData - 定义数据提取逻辑
+ * 2. workerProcess - 编写处理函数（纯函数，可序列化）
+ * 3. applyResult - 定义结果应用逻辑
+ * 4. (可选) SharedArrayBuffer相关方法
+ *
+ * @example
+ * ```typescript
+ * class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
+ *     constructor() {
+ *         super(Matcher.all(Transform, Velocity), {
+ *             enableWorker: true,
+ *             workerCount: 8, // 指定8个worker，系统会自动限制在系统最大值内
+ *             entitiesPerWorker: 100, // 每个worker处理100个实体
+ *             useSharedArrayBuffer: true,
+ *             entityDataSize: 6, // x, y, vx, vy, radius, mass
+ *             maxEntities: 10000,
+ *             systemConfig: { gravity: 100, friction: 0.95 }
+ *         });
+ *     }
+ *
+ *     protected getDefaultEntityDataSize(): number {
+ *         return 6; // x, y, vx, vy, radius, mass
+ *     }
+ *
+ *     protected extractEntityData(entity: Entity): PhysicsData {
+ *         const transform = entity.getComponent(Transform);
+ *         const velocity = entity.getComponent(Velocity);
+ *         const physics = entity.getComponent(PhysicsComponent);
+ *         return {
+ *             x: transform.x,
+ *             y: transform.y,
+ *             vx: velocity.x,
+ *             vy: velocity.y,
+ *             radius: physics.radius,
+ *             mass: physics.mass
+ *         };
+ *     }
+ *
+ *     protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] {
+ *         return entities.map(entity => {
+ *             // 应用重力
+ *             entity.vy += config.gravity * deltaTime;
+ *
+ *             // 更新位置
+ *             entity.x += entity.vx * deltaTime;
+ *             entity.y += entity.vy * deltaTime;
+ *
+ *             // 应用摩擦力
+ *             entity.vx *= config.friction;
+ *             entity.vy *= config.friction;
+ *
+ *             return entity;
+ *         });
+ *     }
+ *
+ *     protected applyResult(entity: Entity, result: PhysicsData): void {
+ *         const transform = entity.getComponent(Transform);
+ *         const velocity = entity.getComponent(Velocity);
+ *
+ *         transform.x = result.x;
+ *         transform.y = result.y;
+ *         velocity.x = result.vx;
+ *         velocity.y = result.vy;
+ *     }
+ *
+ *     // SharedArrayBuffer优化支持
+ *     protected writeEntityToBuffer(entityData: PhysicsData, offset: number): void {
+ *         if (!this.sharedFloatArray) return;
+ *
+ *         this.sharedFloatArray[offset] = entityData.x;
+ *         this.sharedFloatArray[offset + 1] = entityData.y;
+ *         this.sharedFloatArray[offset + 2] = entityData.vx;
+ *         this.sharedFloatArray[offset + 3] = entityData.vy;
+ *         this.sharedFloatArray[offset + 4] = entityData.radius;
+ *         this.sharedFloatArray[offset + 5] = entityData.mass;
+ *     }
+ *
+ *     protected readEntityFromBuffer(offset: number): PhysicsData | null {
+ *         if (!this.sharedFloatArray) return null;
+ *
+ *         return {
+ *             x: this.sharedFloatArray[offset],
+ *             y: this.sharedFloatArray[offset + 1],
+ *             vx: this.sharedFloatArray[offset + 2],
+ *             vy: this.sharedFloatArray[offset + 3],
+ *             radius: this.sharedFloatArray[offset + 4],
+ *             mass: this.sharedFloatArray[offset + 5]
+ *         };
+ *     }
+ *
+ *     protected getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction {
+ *         return function(sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, config: any) {
+ *             const entitySize = 6;
+ *             for (let i = startIndex; i < endIndex; i++) {
+ *                 const offset = i * entitySize;
+ *
+ *                 // 读取数据
+ *                 let x = sharedFloatArray[offset];
+ *                 let y = sharedFloatArray[offset + 1];
+ *                 let vx = sharedFloatArray[offset + 2];
+ *                 let vy = sharedFloatArray[offset + 3];
+ *                 const radius = sharedFloatArray[offset + 4];
+ *                 const mass = sharedFloatArray[offset + 5];
+ *
+ *                 // 物理计算
+ *                 vy += config.gravity * deltaTime;
+ *                 x += vx * deltaTime;
+ *                 y += vy * deltaTime;
+ *                 vx *= config.friction;
+ *                 vy *= config.friction;
+ *
+ *                 // 写回数据
+ *                 sharedFloatArray[offset] = x;
+ *                 sharedFloatArray[offset + 1] = y;
+ *                 sharedFloatArray[offset + 2] = vx;
+ *                 sharedFloatArray[offset + 3] = vy;
+ *             }
+ *         };
+ *     }
+ * }
+ *
+ * interface PhysicsData {
+ *     x: number;
+ *     y: number;
+ *     vx: number;
+ *     vy: number;
+ *     radius: number;
+ *     mass: number;
+ * }
+ * ```
+ */
+export declare abstract class WorkerEntitySystem<TEntityData = any> extends EntitySystem {
+    protected config: Required<Omit<WorkerSystemConfig, 'systemConfig' | 'entitiesPerWorker'>> & {
+        systemConfig?: any;
+        entitiesPerWorker?: number;
+    };
+    private workerPool;
+    private isProcessing;
+    protected sharedBuffer: SharedArrayBuffer | null;
+    protected sharedFloatArray: Float32Array | null;
+    private platformAdapter;
+    private hasLoggedSyncMode;
+    constructor(matcher?: Matcher, config?: WorkerSystemConfig);
+    /**
+     * 检查是否支持Worker
+     */
+    private isWorkerSupported;
+    /**
+     * 检查是否支持SharedArrayBuffer
+     */
+    private isSharedArrayBufferSupported;
+    /**
+     * 获取系统支持的最大Worker数量
+     */
+    private getMaxSystemWorkerCount;
+    /**
+     * 获取实体数据大小 - 子类必须实现
+     * 返回每个实体在SharedArrayBuffer中占用的Float32数量
+     */
+    protected abstract getDefaultEntityDataSize(): number;
+    /**
+     * 初始化SharedArrayBuffer
+     */
+    private initializeSharedArrayBuffer;
+    /**
+     * 初始化Worker池
+     */
+    private initializeWorkerPool;
+    /**
+     * 创建Worker脚本
+     */
+    private createWorkerScript;
+    /**
+     * 重写process方法，支持Worker并行处理
+     */
+    protected process(entities: readonly Entity[]): void;
+    /**
+     * 使用SharedArrayBuffer优化的Worker处理
+     */
+    private processWithSharedArrayBuffer;
+    /**
+     * 使用Worker并行处理
+     */
+    private processWithWorker;
+    /**
+     * 同步处理（fallback）
+     */
+    private processSynchronously;
+    /**
+     * 创建数据批次 - 支持用户指定每个Worker的实体数量
+     */
+    private createBatches;
+    /**
+     * 将实体数据写入SharedArrayBuffer
+     */
+    private writeEntitiesToSharedBuffer;
+    /**
+     * 将单个实体数据写入SharedArrayBuffer - 子类必须实现
+     * @param entityData 实体数据
+     * @param offset 在SharedArrayBuffer中的偏移位置（Float32索引）
+     */
+    protected abstract writeEntityToBuffer(entityData: TEntityData, offset: number): void;
+    /**
+     * 创建SharedArrayBuffer任务 - 支持用户指定每个Worker的实体数量
+     */
+    private createSharedArrayBufferTasks;
+    /**
+     * 从SharedArrayBuffer读取结果并应用
+     */
+    private readResultsFromSharedBuffer;
+    /**
+     * 从SharedArrayBuffer读取单个实体数据 - 子类必须实现
+     * @param offset 在SharedArrayBuffer中的偏移位置（Float32索引）
+     * @returns 实体数据或null
+     */
+    protected abstract readEntityFromBuffer(offset: number): TEntityData | null;
+    /**
+     * 获取SharedArrayBuffer处理函数 - 子类可选实现
+     * 返回一个函数，该函数将被序列化到Worker中执行
+     */
+    protected getSharedArrayBufferProcessFunction?(): SharedArrayBufferProcessFunction;
+    /**
+     * 提取实体数据 - 子类必须实现
+     *
+     * 将Entity转换为可序列化的数据对象
+     */
+    protected abstract extractEntityData(entity: Entity): TEntityData;
+    /**
+     * Worker处理函数 - 子类必须实现
+     *
+     * 这个函数会被序列化并在Worker中执行，因此：
+     * 1. 必须是纯函数，不能访问外部变量
+     * 2. 不能使用闭包或this
+     * 3. 只能使用标准JavaScript API
+     */
+    protected abstract workerProcess(entities: TEntityData[], deltaTime: number, systemConfig?: any): TEntityData[] | Promise<TEntityData[]>;
+    /**
+     * 应用处理结果 - 子类必须实现
+     *
+     * 将Worker处理的结果应用回Entity的组件
+     */
+    protected abstract applyResult(entity: Entity, result: TEntityData): void;
+    /**
+     * 更新Worker配置
+     */
+    updateConfig(newConfig: Partial<WorkerSystemConfig>): void;
+    /**
+     * 重新初始化整个 Worker 系统（包括 SharedArrayBuffer）
+     */
+    private reinitializeWorkerSystem;
+    /**
+     * 重新初始化 Worker 池（保持 SharedArrayBuffer）
+     */
+    private reinitializeWorkerPool;
+    /**
+     * 获取系统性能信息
+     */
+    getWorkerInfo(): {
+        enabled: boolean;
+        workerCount: number;
+        entitiesPerWorker?: number;
+        maxSystemWorkerCount: number;
+        isProcessing: boolean;
+        sharedArrayBufferSupported: boolean;
+        sharedArrayBufferEnabled: boolean;
+        currentMode: 'shared-buffer' | 'worker' | 'sync';
+    };
+    /**
+     * 销毁系统时清理Worker池
+     */
+    protected onDestroy(): void;
+    protected getLoggerName(): string;
+}
+//# sourceMappingURL=WorkerEntitySystem.d.ts.map

package/bin/ECS/Systems/WorkerEntitySystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerEntitySystem.d.ts","sourceRoot":"","sources":["../../../src/ECS/Systems/WorkerEntitySystem.ts"],"names":[],"mappings":"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"}