@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Core/CommandBuffer.d.ts

@@ -0,0 +1,154 @@
+import { Entity } from '../Entity';
+import { Component } from '../Component';
+import { ComponentType } from './ComponentStorage';
+import { IScene } from '../IScene';
+/**
+ * 延迟命令类型
+ * Deferred command type
+ */
+export declare enum CommandType {
+    /** 添加组件 | Add component */
+    ADD_COMPONENT = "add_component",
+    /** 移除组件 | Remove component */
+    REMOVE_COMPONENT = "remove_component",
+    /** 销毁实体 | Destroy entity */
+    DESTROY_ENTITY = "destroy_entity",
+    /** 设置实体激活状态 | Set entity active state */
+    SET_ENTITY_ACTIVE = "set_entity_active"
+}
+/**
+ * 延迟命令接口
+ * Deferred command interface
+ */
+export interface DeferredCommand {
+    /** 命令类型 | Command type */
+    type: CommandType;
+    /** 目标实体 | Target entity */
+    entity: Entity;
+    /** 组件实例（用于 ADD_COMPONENT）| Component instance (for ADD_COMPONENT) */
+    component?: Component;
+    /** 组件类型（用于 REMOVE_COMPONENT）| Component type (for REMOVE_COMPONENT) */
+    componentType?: ComponentType;
+    /** 布尔值（用于启用/激活状态）| Boolean value (for enabled/active state) */
+    value?: boolean;
+}
+/**
+ * 命令缓冲区 - 用于延迟执行实体操作
+ * Command Buffer - for deferred entity operations
+ *
+ * 在系统的 process() 方法中使用 CommandBuffer 可以避免迭代过程中修改实体列表，
+ * 从而提高性能（无需每帧拷贝数组）并保证迭代安全。
+ *
+ * Using CommandBuffer in system's process() method avoids modifying entity list during iteration,
+ * improving performance (no array copy per frame) and ensuring iteration safety.
+ *
+ * @example
+ * ```typescript
+ * class DamageSystem extends EntitySystem {
+ *     protected process(entities: readonly Entity[]): void {
+ *         for (const entity of entities) {
+ *             const health = entity.getComponent(Health);
+ *             if (health.value <= 0) {
+ *                 // 延迟到帧末执行，不影响当前迭代
+ *                 // Deferred to end of frame, doesn't affect current iteration
+ *                 this.commands.addComponent(entity, new DeadMarker());
+ *                 this.commands.destroyEntity(entity);
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export declare class CommandBuffer {
+    /** 命令队列 | Command queue */
+    private _commands;
+    /** 关联的场景 | Associated scene */
+    private _scene;
+    /** 是否启用调试日志 | Enable debug logging */
+    private _debug;
+    /**
+     * 创建命令缓冲区
+     * Create command buffer
+     *
+     * @param scene - 关联的场景 | Associated scene
+     * @param debug - 是否启用调试 | Enable debug
+     */
+    constructor(scene?: IScene, debug?: boolean);
+    /**
+     * 设置关联的场景
+     * Set associated scene
+     */
+    setScene(scene: IScene | null): void;
+    /**
+     * 获取关联的场景
+     * Get associated scene
+     */
+    get scene(): IScene | null;
+    /**
+     * 获取待执行的命令数量
+     * Get pending command count
+     */
+    get pendingCount(): number;
+    /**
+     * 检查是否有待执行的命令
+     * Check if there are pending commands
+     */
+    get hasPending(): boolean;
+    /**
+     * 延迟添加组件
+     * Deferred add component
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param component - 要添加的组件 | Component to add
+     */
+    addComponent(entity: Entity, component: Component): void;
+    /**
+     * 延迟移除组件
+     * Deferred remove component
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param componentType - 要移除的组件类型 | Component type to remove
+     */
+    removeComponent<T extends Component>(entity: Entity, componentType: ComponentType<T>): void;
+    /**
+     * 延迟销毁实体
+     * Deferred destroy entity
+     *
+     * @param entity - 要销毁的实体 | Entity to destroy
+     */
+    destroyEntity(entity: Entity): void;
+    /**
+     * 延迟设置实体激活状态
+     * Deferred set entity active state
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param active - 激活状态 | Active state
+     */
+    setEntityActive(entity: Entity, active: boolean): void;
+    /**
+     * 执行所有待处理的命令
+     * Execute all pending commands
+     *
+     * 通常在帧末由 Scene 自动调用。
+     * Usually called automatically by Scene at end of frame.
+     *
+     * @returns 执行的命令数量 | Number of commands executed
+     */
+    flush(): number;
+    /**
+     * 执行单个命令
+     * Execute single command
+     */
+    private executeCommand;
+    /**
+     * 清空所有待处理的命令（不执行）
+     * Clear all pending commands (without executing)
+     */
+    clear(): void;
+    /**
+     * 销毁命令缓冲区
+     * Dispose command buffer
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=CommandBuffer.d.ts.map

package/bin/ECS/Core/CommandBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandBuffer.d.ts","sourceRoot":"","sources":["../../../src/ECS/Core/CommandBuffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKnC;;;GAGG;AACH,oBAAY,WAAW;IACnB,2BAA2B;IAC3B,aAAa,kBAAkB;IAC/B,8BAA8B;IAC9B,gBAAgB,qBAAqB;IACrC,4BAA4B;IAC5B,cAAc,mBAAmB;IACjC,yCAAyC;IACzC,iBAAiB,sBAAsB;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACtB,2BAA2B;IAC3B,OAAO,CAAC,SAAS,CAAyB;IAE1C,+BAA+B;IAC/B,OAAO,CAAC,MAAM,CAAuB;IAErC,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;;;;OAMG;gBACS,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe;IAKlD;;;OAGG;IACI,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI3C;;;OAGG;IACH,IAAW,KAAK,IAAI,MAAM,GAAG,IAAI,CAEhC;IAED;;;OAGG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;;OAGG;IACH,IAAW,UAAU,IAAI,OAAO,CAE/B;IAED;;;;;;OAMG;IACI,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAY/D;;;;;;OAMG;IACI,eAAe,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IAYlG;;;;;OAKG;IACI,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAW1C;;;;;;OAMG;IACI,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAY7D;;;;;;;;OAQG;IACI,KAAK,IAAI,MAAM;IA2BtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAuCtB;;;OAGG;IACI,KAAK,IAAI,IAAI;IAOpB;;;OAGG;IACI,OAAO,IAAI,IAAI;CAIzB"}

package/bin/ECS/Core/CommandBuffer.js

@@ -0,0 +1,244 @@
+import { createLogger } from '../../Utils/Logger';
+const logger = createLogger('CommandBuffer');
+/**
+ * 延迟命令类型
+ * Deferred command type
+ */
+export var CommandType;
+(function (CommandType) {
+    /** 添加组件 | Add component */
+    CommandType["ADD_COMPONENT"] = "add_component";
+    /** 移除组件 | Remove component */
+    CommandType["REMOVE_COMPONENT"] = "remove_component";
+    /** 销毁实体 | Destroy entity */
+    CommandType["DESTROY_ENTITY"] = "destroy_entity";
+    /** 设置实体激活状态 | Set entity active state */
+    CommandType["SET_ENTITY_ACTIVE"] = "set_entity_active";
+})(CommandType || (CommandType = {}));
+/**
+ * 命令缓冲区 - 用于延迟执行实体操作
+ * Command Buffer - for deferred entity operations
+ *
+ * 在系统的 process() 方法中使用 CommandBuffer 可以避免迭代过程中修改实体列表，
+ * 从而提高性能（无需每帧拷贝数组）并保证迭代安全。
+ *
+ * Using CommandBuffer in system's process() method avoids modifying entity list during iteration,
+ * improving performance (no array copy per frame) and ensuring iteration safety.
+ *
+ * @example
+ * ```typescript
+ * class DamageSystem extends EntitySystem {
+ *     protected process(entities: readonly Entity[]): void {
+ *         for (const entity of entities) {
+ *             const health = entity.getComponent(Health);
+ *             if (health.value <= 0) {
+ *                 // 延迟到帧末执行，不影响当前迭代
+ *                 // Deferred to end of frame, doesn't affect current iteration
+ *                 this.commands.addComponent(entity, new DeadMarker());
+ *                 this.commands.destroyEntity(entity);
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export class CommandBuffer {
+    /**
+     * 创建命令缓冲区
+     * Create command buffer
+     *
+     * @param scene - 关联的场景 | Associated scene
+     * @param debug - 是否启用调试 | Enable debug
+     */
+    constructor(scene, debug = false) {
+        /** 命令队列 | Command queue */
+        this._commands = [];
+        /** 关联的场景 | Associated scene */
+        this._scene = null;
+        /** 是否启用调试日志 | Enable debug logging */
+        this._debug = false;
+        this._scene = scene ?? null;
+        this._debug = debug;
+    }
+    /**
+     * 设置关联的场景
+     * Set associated scene
+     */
+    setScene(scene) {
+        this._scene = scene;
+    }
+    /**
+     * 获取关联的场景
+     * Get associated scene
+     */
+    get scene() {
+        return this._scene;
+    }
+    /**
+     * 获取待执行的命令数量
+     * Get pending command count
+     */
+    get pendingCount() {
+        return this._commands.length;
+    }
+    /**
+     * 检查是否有待执行的命令
+     * Check if there are pending commands
+     */
+    get hasPending() {
+        return this._commands.length > 0;
+    }
+    /**
+     * 延迟添加组件
+     * Deferred add component
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param component - 要添加的组件 | Component to add
+     */
+    addComponent(entity, component) {
+        this._commands.push({
+            type: CommandType.ADD_COMPONENT,
+            entity,
+            component
+        });
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 延迟添加组件 ${component.constructor.name} 到实体 ${entity.name}`);
+        }
+    }
+    /**
+     * 延迟移除组件
+     * Deferred remove component
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param componentType - 要移除的组件类型 | Component type to remove
+     */
+    removeComponent(entity, componentType) {
+        this._commands.push({
+            type: CommandType.REMOVE_COMPONENT,
+            entity,
+            componentType
+        });
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 延迟移除组件 ${componentType.name} 从实体 ${entity.name}`);
+        }
+    }
+    /**
+     * 延迟销毁实体
+     * Deferred destroy entity
+     *
+     * @param entity - 要销毁的实体 | Entity to destroy
+     */
+    destroyEntity(entity) {
+        this._commands.push({
+            type: CommandType.DESTROY_ENTITY,
+            entity
+        });
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 延迟销毁实体 ${entity.name}`);
+        }
+    }
+    /**
+     * 延迟设置实体激活状态
+     * Deferred set entity active state
+     *
+     * @param entity - 目标实体 | Target entity
+     * @param active - 激活状态 | Active state
+     */
+    setEntityActive(entity, active) {
+        this._commands.push({
+            type: CommandType.SET_ENTITY_ACTIVE,
+            entity,
+            value: active
+        });
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 延迟设置实体 ${entity.name} 激活状态为 ${active}`);
+        }
+    }
+    /**
+     * 执行所有待处理的命令
+     * Execute all pending commands
+     *
+     * 通常在帧末由 Scene 自动调用。
+     * Usually called automatically by Scene at end of frame.
+     *
+     * @returns 执行的命令数量 | Number of commands executed
+     */
+    flush() {
+        if (this._commands.length === 0) {
+            return 0;
+        }
+        const count = this._commands.length;
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 开始执行 ${count} 个延迟命令`);
+        }
+        // 复制命令列表并清空，防止执行过程中有新命令加入
+        // Copy and clear command list to prevent new commands during execution
+        const commands = this._commands;
+        this._commands = [];
+        for (const cmd of commands) {
+            this.executeCommand(cmd);
+        }
+        if (this._debug) {
+            logger.debug(`CommandBuffer: 完成执行 ${count} 个延迟命令`);
+        }
+        return count;
+    }
+    /**
+     * 执行单个命令
+     * Execute single command
+     */
+    executeCommand(cmd) {
+        // 检查实体是否仍然有效
+        // Check if entity is still valid
+        if (!cmd.entity.scene) {
+            if (this._debug) {
+                logger.debug(`CommandBuffer: 跳过命令，实体 ${cmd.entity.name} 已无效`);
+            }
+            return;
+        }
+        try {
+            switch (cmd.type) {
+                case CommandType.ADD_COMPONENT:
+                    if (cmd.component) {
+                        cmd.entity.addComponent(cmd.component);
+                    }
+                    break;
+                case CommandType.REMOVE_COMPONENT:
+                    if (cmd.componentType) {
+                        cmd.entity.removeComponentByType(cmd.componentType);
+                    }
+                    break;
+                case CommandType.DESTROY_ENTITY:
+                    cmd.entity.destroy();
+                    break;
+                case CommandType.SET_ENTITY_ACTIVE:
+                    if (cmd.value !== undefined) {
+                        cmd.entity.active = cmd.value;
+                    }
+                    break;
+            }
+        }
+        catch (error) {
+            logger.error(`CommandBuffer: 执行命令失败`, { command: cmd, error });
+        }
+    }
+    /**
+     * 清空所有待处理的命令（不执行）
+     * Clear all pending commands (without executing)
+     */
+    clear() {
+        if (this._debug && this._commands.length > 0) {
+            logger.debug(`CommandBuffer: 清空 ${this._commands.length} 个未执行的命令`);
+        }
+        this._commands.length = 0;
+    }
+    /**
+     * 销毁命令缓冲区
+     * Dispose command buffer
+     */
+    dispose() {
+        this.clear();
+        this._scene = null;
+    }
+}
+//# sourceMappingURL=CommandBuffer.js.map

package/bin/ECS/Core/CommandBuffer.js.map

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

package/bin/ECS/Core/ComponentPool.d.ts

@@ -0,0 +1,139 @@
+import { Component } from '../Component';
+/**
+ * 组件对象池，用于复用组件实例以减少内存分配
+ */
+export declare class ComponentPool<T extends Component> {
+    private pool;
+    private createFn;
+    private resetFn?;
+    private maxSize;
+    private minSize;
+    private stats;
+    constructor(createFn: () => T, resetFn?: (component: T) => void, maxSize?: number, minSize?: number);
+    /**
+     * 获取一个组件实例
+     */
+    acquire(): T;
+    /**
+     * 释放一个组件实例回池中
+     */
+    release(component: T): void;
+    /**
+     * 预填充对象池
+     */
+    prewarm(count: number): void;
+    /**
+     * 自动收缩池大小
+     */
+    shrink(): void;
+    /**
+     * 清空对象池
+     */
+    clear(): void;
+    /**
+     * 获取池中可用对象数量
+     */
+    getAvailableCount(): number;
+    /**
+     * 获取池的最大容量
+     */
+    getMaxSize(): number;
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        totalCreated: number;
+        totalAcquired: number;
+        totalReleased: number;
+        hitRate: number;
+        currentSize: number;
+        maxSize: number;
+        minSize: number;
+        utilizationRate: number;
+    };
+}
+/**
+ * 组件使用追踪
+ */
+interface ComponentUsageTracker {
+    createCount: number;
+    releaseCount: number;
+    lastAccessTime: number;
+}
+/**
+ * 全局组件池管理器
+ */
+export declare class ComponentPoolManager {
+    private static instance;
+    private pools;
+    private usageTracker;
+    private autoCleanupInterval;
+    private lastCleanupTime;
+    private constructor();
+    static getInstance(): ComponentPoolManager;
+    /**
+     * 注册组件池
+     */
+    registerPool<T extends Component>(componentName: string, createFn: () => T, resetFn?: (component: T) => void, maxSize?: number, minSize?: number): void;
+    /**
+     * 获取组件实例
+     */
+    acquireComponent<T extends Component>(componentName: string): T | null;
+    /**
+     * 释放组件实例
+     */
+    releaseComponent<T extends Component>(componentName: string, component: T): void;
+    /**
+     * 追踪使用情况
+     */
+    private trackUsage;
+    /**
+     * 自动清理(定期调用)
+     */
+    update(): void;
+    /**
+     * 获取热点组件列表
+     */
+    getHotComponents(threshold?: number): string[];
+    /**
+     * 预热所有池
+     */
+    prewarmAll(count?: number): void;
+    /**
+     * 清空所有池
+     */
+    clearAll(): void;
+    /**
+     * 重置管理器
+     */
+    reset(): void;
+    /**
+     * 获取全局统计信息
+     */
+    getGlobalStats(): Array<{
+        componentName: string;
+        poolStats: ReturnType<ComponentPool<Component>['getStats']>;
+        usage: ComponentUsageTracker | undefined;
+    }>;
+    /**
+     * 获取池统计信息
+     */
+    getPoolStats(): Map<string, {
+        available: number;
+        maxSize: number;
+    }>;
+    /**
+     * 获取池利用率信息
+     */
+    getPoolUtilization(): Map<string, {
+        used: number;
+        total: number;
+        utilization: number;
+    }>;
+    /**
+     * 获取指定组件的池利用率
+     */
+    getComponentUtilization(componentName: string): number;
+}
+export {};
+//# sourceMappingURL=ComponentPool.d.ts.map

package/bin/ECS/Core/ComponentPool.d.ts.map

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