@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Core/ReferenceTracker.js

@@ -0,0 +1,254 @@
+/**
+ * WeakRef Polyfill for ES2020 compatibility
+ *
+ * 为了兼容 Cocos Creator、Laya、微信小游戏等目标平台（仅支持 ES2020），
+ * 提供 WeakRef 的 Polyfill 实现。
+ *
+ * - 现代浏览器：自动使用原生 WeakRef (自动 GC)
+ * - 旧环境：使用 Polyfill (无自动 GC，但 Scene 销毁时会手动清理)
+ */
+class WeakRefPolyfill {
+    constructor(target) {
+        this._target = target;
+    }
+    deref() {
+        return this._target;
+    }
+}
+/**
+ * WeakRef 实现
+ *
+ * 优先使用原生 WeakRef，不支持时降级到 Polyfill
+ */
+const WeakRefImpl = ((typeof globalThis !== 'undefined' && globalThis.WeakRef) ||
+    (typeof global !== 'undefined' && global.WeakRef) ||
+    (typeof window !== 'undefined' && window.WeakRef) ||
+    WeakRefPolyfill);
+/**
+ * 全局EntityID到Scene的映射
+ *
+ * 使用全局Map记录每个Entity ID对应的Scene，用于装饰器通过Component.entityId查找Scene。
+ */
+const globalEntitySceneMap = new Map();
+/**
+ * 通过Entity ID获取Scene
+ *
+ * @param entityId Entity ID
+ * @returns Scene实例，如果不存在则返回null
+ */
+export function getSceneByEntityId(entityId) {
+    const sceneRef = globalEntitySceneMap.get(entityId);
+    return sceneRef?.deref() || null;
+}
+/**
+ * Entity引用追踪器
+ *
+ * 追踪Component中对Entity的引用，当Entity被销毁时自动清理所有引用。
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ReferenceTracker();
+ * tracker.registerReference(targetEntity, component, 'parent');
+ * targetEntity.destroy(); // 自动将 component.parent 设为 null
+ * ```
+ */
+export class ReferenceTracker {
+    constructor() {
+        /**
+         * Entity ID -> 引用该Entity的所有组件记录
+         */
+        this._references = new Map();
+    }
+    /**
+     * 注册Entity引用
+     *
+     * @param entity 被引用的Entity
+     * @param component 持有引用的Component
+     * @param propertyKey Component中存储引用的属性名
+     */
+    registerReference(entity, component, propertyKey) {
+        const entityId = entity.id;
+        let records = this._references.get(entityId);
+        if (!records) {
+            records = new Set();
+            this._references.set(entityId, records);
+        }
+        const existingRecord = this._findRecord(records, component, propertyKey);
+        if (existingRecord) {
+            return;
+        }
+        records.add({
+            component: new WeakRefImpl(component),
+            propertyKey
+        });
+    }
+    /**
+     * 注销Entity引用
+     *
+     * @param entity 被引用的Entity
+     * @param component 持有引用的Component
+     * @param propertyKey Component中存储引用的属性名
+     */
+    unregisterReference(entity, component, propertyKey) {
+        const entityId = entity.id;
+        const records = this._references.get(entityId);
+        if (!records) {
+            return;
+        }
+        const record = this._findRecord(records, component, propertyKey);
+        if (record) {
+            records.delete(record);
+            if (records.size === 0) {
+                this._references.delete(entityId);
+            }
+        }
+    }
+    /**
+     * 清理所有指向指定Entity的引用
+     *
+     * 将所有引用该Entity的Component属性设为null。
+     *
+     * @param entityId 被销毁的Entity ID
+     */
+    clearReferencesTo(entityId) {
+        const records = this._references.get(entityId);
+        if (!records) {
+            return;
+        }
+        const validRecords = [];
+        for (const record of records) {
+            const component = record.component.deref();
+            if (component) {
+                validRecords.push(record);
+            }
+        }
+        for (const record of validRecords) {
+            const component = record.component.deref();
+            if (component) {
+                component[record.propertyKey] = null;
+            }
+        }
+        this._references.delete(entityId);
+    }
+    /**
+     * 清理Component的所有引用注册
+     *
+     * 当Component被移除时调用，清理该Component注册的所有引用。
+     *
+     * @param component 被移除的Component
+     */
+    clearComponentReferences(component) {
+        for (const [entityId, records] of this._references.entries()) {
+            const toDelete = [];
+            for (const record of records) {
+                const comp = record.component.deref();
+                if (!comp || comp === component) {
+                    toDelete.push(record);
+                }
+            }
+            for (const record of toDelete) {
+                records.delete(record);
+            }
+            if (records.size === 0) {
+                this._references.delete(entityId);
+            }
+        }
+    }
+    /**
+     * 获取指向指定Entity的所有引用记录
+     *
+     * @param entityId Entity ID
+     * @returns 引用记录数组（仅包含有效引用）
+     */
+    getReferencesTo(entityId) {
+        const records = this._references.get(entityId);
+        if (!records) {
+            return [];
+        }
+        const validRecords = [];
+        for (const record of records) {
+            const component = record.component.deref();
+            if (component) {
+                validRecords.push(record);
+            }
+        }
+        return validRecords;
+    }
+    /**
+     * 清理所有失效的WeakRef引用
+     *
+     * 遍历所有记录，移除已被GC回收的Component引用。
+     */
+    cleanup() {
+        const entitiesToDelete = [];
+        for (const [entityId, records] of this._references.entries()) {
+            const toDelete = [];
+            for (const record of records) {
+                if (!record.component.deref()) {
+                    toDelete.push(record);
+                }
+            }
+            for (const record of toDelete) {
+                records.delete(record);
+            }
+            if (records.size === 0) {
+                entitiesToDelete.push(entityId);
+            }
+        }
+        for (const entityId of entitiesToDelete) {
+            this._references.delete(entityId);
+        }
+    }
+    /**
+     * 注册Entity到Scene的映射
+     *
+     * @param entityId Entity ID
+     * @param scene Scene实例
+     */
+    registerEntityScene(entityId, scene) {
+        globalEntitySceneMap.set(entityId, new WeakRefImpl(scene));
+    }
+    /**
+     * 注销Entity到Scene的映射
+     *
+     * @param entityId Entity ID
+     */
+    unregisterEntityScene(entityId) {
+        globalEntitySceneMap.delete(entityId);
+    }
+    /**
+     * 获取调试信息
+     */
+    getDebugInfo() {
+        const info = {};
+        for (const [entityId, records] of this._references.entries()) {
+            const validRecords = [];
+            for (const record of records) {
+                const component = record.component.deref();
+                if (component) {
+                    validRecords.push({
+                        componentId: component.id,
+                        propertyKey: record.propertyKey
+                    });
+                }
+            }
+            if (validRecords.length > 0) {
+                info[`entity_${entityId}`] = validRecords;
+            }
+        }
+        return info;
+    }
+    /**
+     * 查找指定的引用记录
+     */
+    _findRecord(records, component, propertyKey) {
+        for (const record of records) {
+            const comp = record.component.deref();
+            if (comp === component && record.propertyKey === propertyKey) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=ReferenceTracker.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * SoA 序列化器
+ * 负责复杂类型的序列化/反序列化和深拷贝
+ */
+export declare class SoASerializer {
+    private static readonly _logger;
+    /**
+     * 序列化值为 JSON 字符串
+     */
+    static serialize(value: unknown, fieldName: string, options?: {
+        isMap?: boolean;
+        isSet?: boolean;
+        isArray?: boolean;
+    }): string;
+    /**
+     * 反序列化 JSON 字符串为值
+     */
+    static deserialize(serialized: string, fieldName: string, options?: {
+        isMap?: boolean;
+        isSet?: boolean;
+        isArray?: boolean;
+    }): unknown;
+    /**
+     * 深拷贝对象
+     */
+    static deepClone<T>(obj: T): T;
+}
+//# sourceMappingURL=SoASerializer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SoASerializer.d.ts","sourceRoot":"","sources":["../../../src/ECS/Core/SoASerializer.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEhE;;OAEG;WACW,SAAS,CACnB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QACL,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KAChB,GACP,MAAM;IAkBT;;OAEG;WACW,WAAW,CACrB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QACL,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KAChB,GACP,OAAO;IAiBV;;OAEG;WACW,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC;CAsCxC"}

package/bin/ECS/Core/SoASerializer.js

@@ -0,0 +1,85 @@
+import { createLogger } from '../../Utils/Logger';
+/**
+ * SoA 序列化器
+ * 负责复杂类型的序列化/反序列化和深拷贝
+ */
+export class SoASerializer {
+    /**
+     * 序列化值为 JSON 字符串
+     */
+    static serialize(value, fieldName, options = {}) {
+        try {
+            if (options.isMap && value instanceof Map) {
+                return JSON.stringify(Array.from(value.entries()));
+            }
+            if (options.isSet && value instanceof Set) {
+                return JSON.stringify(Array.from(value));
+            }
+            if (options.isArray && Array.isArray(value)) {
+                return JSON.stringify(value);
+            }
+            return JSON.stringify(value);
+        }
+        catch (error) {
+            this._logger.warn(`SoA序列化字段 ${fieldName} 失败:`, error);
+            return '{}';
+        }
+    }
+    /**
+     * 反序列化 JSON 字符串为值
+     */
+    static deserialize(serialized, fieldName, options = {}) {
+        try {
+            const parsed = JSON.parse(serialized);
+            if (options.isMap) {
+                return new Map(parsed);
+            }
+            if (options.isSet) {
+                return new Set(parsed);
+            }
+            return parsed;
+        }
+        catch (error) {
+            this._logger.warn(`SoA反序列化字段 ${fieldName} 失败:`, error);
+            return null;
+        }
+    }
+    /**
+     * 深拷贝对象
+     */
+    static deepClone(obj) {
+        if (obj === null || typeof obj !== 'object') {
+            return obj;
+        }
+        if (obj instanceof Date) {
+            return new Date(obj.getTime());
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.deepClone(item));
+        }
+        if (obj instanceof Map) {
+            const cloned = new Map();
+            for (const [key, value] of obj.entries()) {
+                cloned.set(key, this.deepClone(value));
+            }
+            return cloned;
+        }
+        if (obj instanceof Set) {
+            const cloned = new Set();
+            for (const value of obj.values()) {
+                cloned.add(this.deepClone(value));
+            }
+            return cloned;
+        }
+        // 普通对象
+        const cloned = {};
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                cloned[key] = this.deepClone(obj[key]);
+            }
+        }
+        return cloned;
+    }
+}
+SoASerializer._logger = createLogger('SoASerializer');
+//# sourceMappingURL=SoASerializer.js.map

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

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

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

@@ -0,0 +1,129 @@
+import { Component } from '../Component';
+import { ComponentType } from './ComponentStorage';
+import { SupportedTypedArray } from './SoATypeRegistry';
+export { SupportedTypedArray, TypedArrayTypeName } from './SoATypeRegistry';
+export { SoATypeRegistry } from './SoATypeRegistry';
+export { SoASerializer } from './SoASerializer';
+/**
+ * 启用SoA优化装饰器
+ * 默认关闭SoA，只有在大规模批量操作场景下才建议开启
+ */
+export declare function EnableSoA<T extends ComponentType>(target: T): T;
+/**
+ * 64位浮点数装饰器
+ * 标记字段使用Float64Array存储（更高精度但更多内存）
+ */
+export declare function Float64(target: any, propertyKey: string | symbol): void;
+/**
+ * 32位浮点数装饰器
+ * 标记字段使用Float32Array存储（默认类型，平衡性能和精度）
+ */
+export declare function Float32(target: any, propertyKey: string | symbol): void;
+/**
+ * 32位整数装饰器
+ * 标记字段使用Int32Array存储（适用于整数值）
+ */
+export declare function Int32(target: any, propertyKey: string | symbol): void;
+/**
+ * 32位无符号整数装饰器
+ * 标记字段使用Uint32Array存储（适用于无符号整数，如ID、标志位等）
+ */
+export declare function Uint32(target: any, propertyKey: string | symbol): void;
+/**
+ * 16位整数装饰器
+ * 标记字段使用Int16Array存储（适用于小范围整数）
+ */
+export declare function Int16(target: any, propertyKey: string | symbol): void;
+/**
+ * 16位无符号整数装饰器
+ * 标记字段使用Uint16Array存储（适用于小范围无符号整数）
+ */
+export declare function Uint16(target: any, propertyKey: string | symbol): void;
+/**
+ * 8位整数装饰器
+ * 标记字段使用Int8Array存储（适用于很小的整数值）
+ */
+export declare function Int8(target: any, propertyKey: string | symbol): void;
+/**
+ * 8位无符号整数装饰器
+ * 标记字段使用Uint8Array存储（适用于字节值、布尔标志等）
+ */
+export declare function Uint8(target: any, propertyKey: string | symbol): void;
+/**
+ * 8位夹紧整数装饰器
+ * 标记字段使用Uint8ClampedArray存储（适用于颜色值等需要夹紧的数据）
+ */
+export declare function Uint8Clamped(target: any, propertyKey: string | symbol): void;
+/**
+ * 序列化Map装饰器
+ * 标记Map字段需要序列化/反序列化存储
+ */
+export declare function SerializeMap(target: any, propertyKey: string | symbol): void;
+/**
+ * 序列化Set装饰器
+ * 标记Set字段需要序列化/反序列化存储
+ */
+export declare function SerializeSet(target: any, propertyKey: string | symbol): void;
+/**
+ * 序列化Array装饰器
+ * 标记Array字段需要序列化/反序列化存储
+ */
+export declare function SerializeArray(target: any, propertyKey: string | symbol): void;
+/**
+ * 深拷贝装饰器
+ * 标记字段需要深拷贝处理（适用于嵌套对象）
+ */
+export declare function DeepCopy(target: any, propertyKey: string | symbol): void;
+/**
+ * SoA存储器（需要装饰器启用）
+ * 使用Structure of Arrays存储模式，在大规模批量操作时提供优异性能
+ */
+export declare class SoAStorage<T extends Component> {
+    private fields;
+    private stringFields;
+    private serializedFields;
+    private complexFields;
+    private entityToIndex;
+    private indexToEntity;
+    private freeIndices;
+    private _size;
+    private _capacity;
+    readonly type: ComponentType<T>;
+    private fieldTypes;
+    private serializeMapFields;
+    private serializeSetFields;
+    private serializeArrayFields;
+    constructor(componentType: ComponentType<T>);
+    private initializeFields;
+    addComponent(entityId: number, component: T): void;
+    private updateComponentAtIndex;
+    getComponent(entityId: number): T | null;
+    /**
+     * 创建组件的 Proxy 视图
+     * 读写操作直接映射到底层 TypedArray，无数据复制
+     */
+    private createProxyView;
+    /**
+     * 获取组件的快照副本（用于序列化等需要独立副本的场景）
+     */
+    getComponentSnapshot(entityId: number): T | null;
+    private getFieldType;
+    hasComponent(entityId: number): boolean;
+    removeComponent(entityId: number): T | null;
+    private resize;
+    getActiveIndices(): number[];
+    getFieldArray(fieldName: string): SupportedTypedArray | null;
+    getTypedFieldArray<K extends keyof T>(fieldName: K): SupportedTypedArray | null;
+    getEntityIndex(entityId: number): number | undefined;
+    getEntityIdByIndex(index: number): number | undefined;
+    size(): number;
+    clear(): void;
+    compact(): void;
+    getStats(): any;
+    /**
+     * 执行向量化批量操作
+     * @param operation 操作函数，接收字段数组和活跃索引
+     */
+    performVectorizedOperation(operation: (fieldArrays: Map<string, SupportedTypedArray>, activeIndices: number[]) => void): void;
+}
+//# sourceMappingURL=SoAStorage.d.ts.map

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

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