@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Core/SoAStorage.js

@@ -0,0 +1,685 @@
+import { SoATypeRegistry } from './SoATypeRegistry';
+import { SoASerializer } from './SoASerializer';
+export { SoATypeRegistry } from './SoATypeRegistry';
+export { SoASerializer } from './SoASerializer';
+/**
+ * 启用SoA优化装饰器
+ * 默认关闭SoA，只有在大规模批量操作场景下才建议开启
+ */
+export function EnableSoA(target) {
+    target.__enableSoA = true;
+    return target;
+}
+/**
+ * 64位浮点数装饰器
+ * 标记字段使用Float64Array存储（更高精度但更多内存）
+ */
+export function Float64(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__float64Fields) {
+        target.constructor.__float64Fields = new Set();
+    }
+    target.constructor.__float64Fields.add(key);
+}
+/**
+ * 32位浮点数装饰器
+ * 标记字段使用Float32Array存储（默认类型，平衡性能和精度）
+ */
+export function Float32(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__float32Fields) {
+        target.constructor.__float32Fields = new Set();
+    }
+    target.constructor.__float32Fields.add(key);
+}
+/**
+ * 32位整数装饰器
+ * 标记字段使用Int32Array存储（适用于整数值）
+ */
+export function Int32(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__int32Fields) {
+        target.constructor.__int32Fields = new Set();
+    }
+    target.constructor.__int32Fields.add(key);
+}
+/**
+ * 32位无符号整数装饰器
+ * 标记字段使用Uint32Array存储（适用于无符号整数，如ID、标志位等）
+ */
+export function Uint32(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__uint32Fields) {
+        target.constructor.__uint32Fields = new Set();
+    }
+    target.constructor.__uint32Fields.add(key);
+}
+/**
+ * 16位整数装饰器
+ * 标记字段使用Int16Array存储（适用于小范围整数）
+ */
+export function Int16(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__int16Fields) {
+        target.constructor.__int16Fields = new Set();
+    }
+    target.constructor.__int16Fields.add(key);
+}
+/**
+ * 16位无符号整数装饰器
+ * 标记字段使用Uint16Array存储（适用于小范围无符号整数）
+ */
+export function Uint16(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__uint16Fields) {
+        target.constructor.__uint16Fields = new Set();
+    }
+    target.constructor.__uint16Fields.add(key);
+}
+/**
+ * 8位整数装饰器
+ * 标记字段使用Int8Array存储（适用于很小的整数值）
+ */
+export function Int8(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__int8Fields) {
+        target.constructor.__int8Fields = new Set();
+    }
+    target.constructor.__int8Fields.add(key);
+}
+/**
+ * 8位无符号整数装饰器
+ * 标记字段使用Uint8Array存储（适用于字节值、布尔标志等）
+ */
+export function Uint8(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__uint8Fields) {
+        target.constructor.__uint8Fields = new Set();
+    }
+    target.constructor.__uint8Fields.add(key);
+}
+/**
+ * 8位夹紧整数装饰器
+ * 标记字段使用Uint8ClampedArray存储（适用于颜色值等需要夹紧的数据）
+ */
+export function Uint8Clamped(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__uint8ClampedFields) {
+        target.constructor.__uint8ClampedFields = new Set();
+    }
+    target.constructor.__uint8ClampedFields.add(key);
+}
+/**
+ * 序列化Map装饰器
+ * 标记Map字段需要序列化/反序列化存储
+ */
+export function SerializeMap(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__serializeMapFields) {
+        target.constructor.__serializeMapFields = new Set();
+    }
+    target.constructor.__serializeMapFields.add(key);
+}
+/**
+ * 序列化Set装饰器
+ * 标记Set字段需要序列化/反序列化存储
+ */
+export function SerializeSet(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__serializeSetFields) {
+        target.constructor.__serializeSetFields = new Set();
+    }
+    target.constructor.__serializeSetFields.add(key);
+}
+/**
+ * 序列化Array装饰器
+ * 标记Array字段需要序列化/反序列化存储
+ */
+export function SerializeArray(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__serializeArrayFields) {
+        target.constructor.__serializeArrayFields = new Set();
+    }
+    target.constructor.__serializeArrayFields.add(key);
+}
+/**
+ * 深拷贝装饰器
+ * 标记字段需要深拷贝处理（适用于嵌套对象）
+ */
+export function DeepCopy(target, propertyKey) {
+    const key = String(propertyKey);
+    if (!target.constructor.__deepCopyFields) {
+        target.constructor.__deepCopyFields = new Set();
+    }
+    target.constructor.__deepCopyFields.add(key);
+}
+/**
+ * SoA存储器（需要装饰器启用）
+ * 使用Structure of Arrays存储模式，在大规模批量操作时提供优异性能
+ */
+export class SoAStorage {
+    constructor(componentType) {
+        this.fields = new Map();
+        this.stringFields = new Map();
+        this.serializedFields = new Map();
+        this.complexFields = new Map();
+        this.entityToIndex = new Map();
+        this.indexToEntity = [];
+        this.freeIndices = [];
+        this._size = 0;
+        this._capacity = 1000;
+        // 缓存字段类型信息，避免重复创建实例
+        this.fieldTypes = new Map();
+        // 缓存装饰器元数据
+        this.serializeMapFields = new Set();
+        this.serializeSetFields = new Set();
+        this.serializeArrayFields = new Set();
+        this.type = componentType;
+        this.initializeFields(componentType);
+    }
+    initializeFields(componentType) {
+        const instance = new componentType();
+        const typeWithMeta = componentType;
+        const float64Fields = typeWithMeta.__float64Fields || new Set();
+        const float32Fields = typeWithMeta.__float32Fields || new Set();
+        const int32Fields = typeWithMeta.__int32Fields || new Set();
+        const uint32Fields = typeWithMeta.__uint32Fields || new Set();
+        const int16Fields = typeWithMeta.__int16Fields || new Set();
+        const uint16Fields = typeWithMeta.__uint16Fields || new Set();
+        const int8Fields = typeWithMeta.__int8Fields || new Set();
+        const uint8Fields = typeWithMeta.__uint8Fields || new Set();
+        const uint8ClampedFields = typeWithMeta.__uint8ClampedFields || new Set();
+        // 缓存装饰器元数据
+        this.serializeMapFields = typeWithMeta.__serializeMapFields || new Set();
+        this.serializeSetFields = typeWithMeta.__serializeSetFields || new Set();
+        this.serializeArrayFields = typeWithMeta.__serializeArrayFields || new Set();
+        // 先收集所有有装饰器的字段，避免重复遍历
+        const decoratedFields = new Map(); // fieldName -> arrayType
+        // 处理各类型装饰器标记的字段
+        for (const key of float64Fields)
+            decoratedFields.set(key, 'float64');
+        for (const key of float32Fields)
+            decoratedFields.set(key, 'float32');
+        for (const key of int32Fields)
+            decoratedFields.set(key, 'int32');
+        for (const key of uint32Fields)
+            decoratedFields.set(key, 'uint32');
+        for (const key of int16Fields)
+            decoratedFields.set(key, 'int16');
+        for (const key of uint16Fields)
+            decoratedFields.set(key, 'uint16');
+        for (const key of int8Fields)
+            decoratedFields.set(key, 'int8');
+        for (const key of uint8Fields)
+            decoratedFields.set(key, 'uint8');
+        for (const key of uint8ClampedFields)
+            decoratedFields.set(key, 'uint8clamped');
+        // 只遍历实例自身的属性（不包括原型链），跳过 id
+        const instanceKeys = Object.keys(instance).filter((key) => key !== 'id');
+        for (const key of instanceKeys) {
+            const value = instance[key];
+            const type = typeof value;
+            // 跳过函数（通常不会出现在 Object.keys 中，但以防万一）
+            if (type === 'function')
+                continue;
+            // 检查装饰器类型
+            const decoratorType = decoratedFields.get(key);
+            const effectiveType = decoratorType ? 'number' : type;
+            this.fieldTypes.set(key, effectiveType);
+            if (decoratorType) {
+                // 有装饰器标记的数字字段
+                const ArrayConstructor = SoATypeRegistry.getConstructor(decoratorType);
+                this.fields.set(key, new ArrayConstructor(this._capacity));
+            }
+            else if (type === 'number') {
+                // 无装饰器的数字字段，默认使用 Float32Array
+                this.fields.set(key, new Float32Array(this._capacity));
+            }
+            else if (type === 'boolean') {
+                // 布尔值使用 Uint8Array 存储为 0/1
+                this.fields.set(key, new Uint8Array(this._capacity));
+            }
+            else if (type === 'string') {
+                // 字符串专门处理
+                this.stringFields.set(key, new Array(this._capacity));
+            }
+            else if (type === 'object' && value !== null) {
+                // 处理集合类型
+                if (this.serializeMapFields.has(key) || this.serializeSetFields.has(key) || this.serializeArrayFields.has(key)) {
+                    // 序列化存储
+                    this.serializedFields.set(key, new Array(this._capacity));
+                }
+                // 其他对象类型会在updateComponentAtIndex中作为复杂对象处理
+            }
+        }
+    }
+    addComponent(entityId, component) {
+        if (this.entityToIndex.has(entityId)) {
+            const index = this.entityToIndex.get(entityId);
+            this.updateComponentAtIndex(index, component);
+            return;
+        }
+        let index;
+        if (this.freeIndices.length > 0) {
+            index = this.freeIndices.pop();
+        }
+        else {
+            index = this._size;
+            if (index >= this._capacity) {
+                this.resize(this._capacity * 2);
+            }
+        }
+        this.entityToIndex.set(entityId, index);
+        this.indexToEntity[index] = entityId;
+        this.updateComponentAtIndex(index, component);
+        this._size++;
+    }
+    updateComponentAtIndex(index, component) {
+        const entityId = this.indexToEntity[index];
+        const complexFieldMap = new Map();
+        const highPrecisionFields = this.type.__highPrecisionFields || new Set();
+        const serializeMapFields = this.type.__serializeMapFields || new Set();
+        const serializeSetFields = this.type.__serializeSetFields || new Set();
+        const serializeArrayFields = this.type.__serializeArrayFields || new Set();
+        const deepCopyFields = this.type.__deepCopyFields || new Set();
+        // 处理所有字段
+        for (const key in component) {
+            if (component.hasOwnProperty(key) && key !== 'id') {
+                const value = component[key];
+                const type = typeof value;
+                if (type === 'number') {
+                    if (highPrecisionFields.has(key) || !this.fields.has(key)) {
+                        // 标记为高精度或未在TypedArray中的数值作为复杂对象存储
+                        complexFieldMap.set(key, value);
+                    }
+                    else {
+                        // 存储到TypedArray
+                        const array = this.fields.get(key);
+                        array[index] = value;
+                    }
+                }
+                else if (type === 'boolean' && this.fields.has(key)) {
+                    // 布尔值存储到TypedArray
+                    const array = this.fields.get(key);
+                    array[index] = value ? 1 : 0;
+                }
+                else if (this.stringFields.has(key)) {
+                    // 字符串字段专门处理
+                    const stringArray = this.stringFields.get(key);
+                    stringArray[index] = String(value);
+                }
+                else if (this.serializedFields.has(key)) {
+                    // 序列化字段处理
+                    const serializedArray = this.serializedFields.get(key);
+                    serializedArray[index] = SoASerializer.serialize(value, key, {
+                        isMap: serializeMapFields.has(key),
+                        isSet: serializeSetFields.has(key),
+                        isArray: serializeArrayFields.has(key)
+                    });
+                }
+                else {
+                    // 复杂字段单独存储
+                    if (deepCopyFields.has(key)) {
+                        // 深拷贝处理
+                        complexFieldMap.set(key, SoASerializer.deepClone(value));
+                    }
+                    else {
+                        complexFieldMap.set(key, value);
+                    }
+                }
+            }
+        }
+        // 存储复杂字段
+        if (complexFieldMap.size > 0) {
+            this.complexFields.set(entityId, complexFieldMap);
+        }
+    }
+    getComponent(entityId) {
+        const index = this.entityToIndex.get(entityId);
+        if (index === undefined) {
+            return null;
+        }
+        // 返回 Proxy，直接操作底层 TypedArray
+        return this.createProxyView(entityId, index);
+    }
+    /**
+     * 创建组件的 Proxy 视图
+     * 读写操作直接映射到底层 TypedArray，无数据复制
+     */
+    createProxyView(entityId, index) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        // Proxy handler 类型定义
+        const handler = {
+            get(_, prop) {
+                const propStr = String(prop);
+                // TypedArray 字段
+                const array = self.fields.get(propStr);
+                if (array) {
+                    const fieldType = self.getFieldType(propStr);
+                    if (fieldType === 'boolean') {
+                        return array[index] === 1;
+                    }
+                    return array[index];
+                }
+                // 字符串字段
+                const stringArray = self.stringFields.get(propStr);
+                if (stringArray) {
+                    return stringArray[index];
+                }
+                // 序列化字段
+                const serializedArray = self.serializedFields.get(propStr);
+                if (serializedArray) {
+                    const serialized = serializedArray[index];
+                    if (serialized) {
+                        return SoASerializer.deserialize(serialized, propStr, {
+                            isMap: self.serializeMapFields.has(propStr),
+                            isSet: self.serializeSetFields.has(propStr),
+                            isArray: self.serializeArrayFields.has(propStr)
+                        });
+                    }
+                    return undefined;
+                }
+                // 复杂字段
+                const complexFieldMap = self.complexFields.get(entityId);
+                if (complexFieldMap?.has(propStr)) {
+                    return complexFieldMap.get(propStr);
+                }
+                return undefined;
+            },
+            set(_, prop, value) {
+                const propStr = String(prop);
+                // entityId 是只读的
+                if (propStr === 'entityId') {
+                    return false;
+                }
+                // TypedArray 字段
+                const array = self.fields.get(propStr);
+                if (array) {
+                    const fieldType = self.getFieldType(propStr);
+                    if (fieldType === 'boolean') {
+                        array[index] = value ? 1 : 0;
+                    }
+                    else {
+                        array[index] = value;
+                    }
+                    return true;
+                }
+                // 字符串字段
+                const stringArray = self.stringFields.get(propStr);
+                if (stringArray) {
+                    stringArray[index] = String(value);
+                    return true;
+                }
+                // 序列化字段
+                if (self.serializedFields.has(propStr)) {
+                    const serializedArray = self.serializedFields.get(propStr);
+                    serializedArray[index] = SoASerializer.serialize(value, propStr, {
+                        isMap: self.serializeMapFields.has(propStr),
+                        isSet: self.serializeSetFields.has(propStr),
+                        isArray: self.serializeArrayFields.has(propStr)
+                    });
+                    return true;
+                }
+                // 复杂字段
+                let complexFieldMap = self.complexFields.get(entityId);
+                if (!complexFieldMap) {
+                    complexFieldMap = new Map();
+                    self.complexFields.set(entityId, complexFieldMap);
+                }
+                complexFieldMap.set(propStr, value);
+                return true;
+            },
+            has(_, prop) {
+                const propStr = String(prop);
+                return self.fields.has(propStr) ||
+                    self.stringFields.has(propStr) ||
+                    self.serializedFields.has(propStr) ||
+                    self.complexFields.get(entityId)?.has(propStr) || false;
+            },
+            ownKeys() {
+                const keys = [];
+                for (const key of self.fields.keys())
+                    keys.push(key);
+                for (const key of self.stringFields.keys())
+                    keys.push(key);
+                for (const key of self.serializedFields.keys())
+                    keys.push(key);
+                const complexFieldMap = self.complexFields.get(entityId);
+                if (complexFieldMap) {
+                    for (const key of complexFieldMap.keys())
+                        keys.push(key);
+                }
+                return keys;
+            },
+            getOwnPropertyDescriptor(_, prop) {
+                const propStr = String(prop);
+                if (self.fields.has(propStr) ||
+                    self.stringFields.has(propStr) ||
+                    self.serializedFields.has(propStr) ||
+                    self.complexFields.get(entityId)?.has(propStr)) {
+                    return {
+                        enumerable: true,
+                        configurable: true,
+                        // entityId 是只读的
+                        writable: propStr !== 'entityId'
+                    };
+                }
+                return undefined;
+            }
+        };
+        return new Proxy({}, handler);
+    }
+    /**
+     * 获取组件的快照副本（用于序列化等需要独立副本的场景）
+     */
+    getComponentSnapshot(entityId) {
+        const index = this.entityToIndex.get(entityId);
+        if (index === undefined) {
+            return null;
+        }
+        // 需要 any 因为要动态写入泛型 T 的属性
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const component = new this.type();
+        // 恢复数值字段
+        for (const [fieldName, array] of this.fields.entries()) {
+            const value = array[index];
+            const fieldType = this.getFieldType(fieldName);
+            if (fieldType === 'boolean') {
+                component[fieldName] = value === 1;
+            }
+            else {
+                component[fieldName] = value;
+            }
+        }
+        // 恢复字符串字段
+        for (const [fieldName, stringArray] of this.stringFields.entries()) {
+            component[fieldName] = stringArray[index];
+        }
+        // 恢复序列化字段
+        for (const [fieldName, serializedArray] of this.serializedFields.entries()) {
+            const serialized = serializedArray[index];
+            if (serialized) {
+                component[fieldName] = SoASerializer.deserialize(serialized, fieldName, {
+                    isMap: this.serializeMapFields.has(fieldName),
+                    isSet: this.serializeSetFields.has(fieldName),
+                    isArray: this.serializeArrayFields.has(fieldName)
+                });
+            }
+        }
+        // 恢复复杂字段
+        const complexFieldMap = this.complexFields.get(entityId);
+        if (complexFieldMap) {
+            for (const [fieldName, value] of complexFieldMap.entries()) {
+                component[fieldName] = value;
+            }
+        }
+        return component;
+    }
+    getFieldType(fieldName) {
+        // 使用缓存的字段类型
+        return this.fieldTypes.get(fieldName) || 'unknown';
+    }
+    hasComponent(entityId) {
+        return this.entityToIndex.has(entityId);
+    }
+    removeComponent(entityId) {
+        const index = this.entityToIndex.get(entityId);
+        if (index === undefined) {
+            return null;
+        }
+        // 获取组件副本以便返回
+        const component = this.getComponent(entityId);
+        // 清理复杂字段
+        this.complexFields.delete(entityId);
+        this.entityToIndex.delete(entityId);
+        this.freeIndices.push(index);
+        this._size--;
+        return component;
+    }
+    resize(newCapacity) {
+        // 调整数值字段的TypedArray
+        for (const [fieldName, oldArray] of this.fields.entries()) {
+            const newArray = SoATypeRegistry.createSameType(oldArray, newCapacity);
+            newArray.set(oldArray);
+            this.fields.set(fieldName, newArray);
+        }
+        // 调整字符串字段的数组
+        for (const [fieldName, oldArray] of this.stringFields.entries()) {
+            const newArray = new Array(newCapacity);
+            for (let i = 0; i < oldArray.length; i++) {
+                newArray[i] = oldArray[i];
+            }
+            this.stringFields.set(fieldName, newArray);
+        }
+        // 调整序列化字段的数组
+        for (const [fieldName, oldArray] of this.serializedFields.entries()) {
+            const newArray = new Array(newCapacity);
+            for (let i = 0; i < oldArray.length; i++) {
+                newArray[i] = oldArray[i];
+            }
+            this.serializedFields.set(fieldName, newArray);
+        }
+        this._capacity = newCapacity;
+    }
+    getActiveIndices() {
+        return Array.from(this.entityToIndex.values());
+    }
+    getFieldArray(fieldName) {
+        return this.fields.get(fieldName) || null;
+    }
+    getTypedFieldArray(fieldName) {
+        return this.fields.get(String(fieldName)) || null;
+    }
+    getEntityIndex(entityId) {
+        return this.entityToIndex.get(entityId);
+    }
+    getEntityIdByIndex(index) {
+        return this.indexToEntity[index];
+    }
+    size() {
+        return this._size;
+    }
+    clear() {
+        this.entityToIndex.clear();
+        this.indexToEntity = [];
+        this.freeIndices = [];
+        this.complexFields.clear();
+        this._size = 0;
+        // 重置数值字段数组
+        for (const array of this.fields.values()) {
+            array.fill(0);
+        }
+        // 重置字符串字段数组
+        for (const stringArray of this.stringFields.values()) {
+            for (let i = 0; i < stringArray.length; i++) {
+                stringArray[i] = undefined;
+            }
+        }
+        // 重置序列化字段数组
+        for (const serializedArray of this.serializedFields.values()) {
+            for (let i = 0; i < serializedArray.length; i++) {
+                serializedArray[i] = undefined;
+            }
+        }
+    }
+    compact() {
+        if (this.freeIndices.length === 0) {
+            return;
+        }
+        const activeEntries = Array.from(this.entityToIndex.entries())
+            .sort((a, b) => a[1] - b[1]);
+        // 重新映射索引
+        const newEntityToIndex = new Map();
+        const newIndexToEntity = [];
+        for (let newIndex = 0; newIndex < activeEntries.length; newIndex++) {
+            const entry = activeEntries[newIndex];
+            if (!entry)
+                continue;
+            const [entityId, oldIndex] = entry;
+            newEntityToIndex.set(entityId, newIndex);
+            newIndexToEntity[newIndex] = entityId;
+            // 移动字段数据
+            if (newIndex !== oldIndex) {
+                // 移动数值字段
+                for (const [, array] of this.fields.entries()) {
+                    const value = array[oldIndex];
+                    if (value !== undefined) {
+                        array[newIndex] = value;
+                    }
+                }
+                // 移动字符串字段
+                for (const [, stringArray] of this.stringFields.entries()) {
+                    const value = stringArray[oldIndex];
+                    if (value !== undefined) {
+                        stringArray[newIndex] = value;
+                    }
+                }
+                // 移动序列化字段
+                for (const [, serializedArray] of this.serializedFields.entries()) {
+                    const value = serializedArray[oldIndex];
+                    if (value !== undefined) {
+                        serializedArray[newIndex] = value;
+                    }
+                }
+            }
+        }
+        this.entityToIndex = newEntityToIndex;
+        this.indexToEntity = newIndexToEntity;
+        this.freeIndices = [];
+        this._size = activeEntries.length;
+    }
+    getStats() {
+        let totalMemory = 0;
+        const fieldStats = new Map();
+        for (const [fieldName, array] of this.fields.entries()) {
+            const typeName = SoATypeRegistry.getTypeName(array);
+            const bytesPerElement = SoATypeRegistry.getBytesPerElement(typeName);
+            const memory = array.length * bytesPerElement;
+            totalMemory += memory;
+            fieldStats.set(fieldName, {
+                size: this._size,
+                capacity: array.length,
+                type: typeName,
+                memory: memory
+            });
+        }
+        return {
+            size: this._size,
+            capacity: this._capacity,
+            usedSlots: this._size, // 兼容原测试
+            fragmentation: this.freeIndices.length / this._capacity,
+            memoryUsage: totalMemory,
+            fieldStats: fieldStats
+        };
+    }
+    /**
+     * 执行向量化批量操作
+     * @param operation 操作函数，接收字段数组和活跃索引
+     */
+    performVectorizedOperation(operation) {
+        const activeIndices = this.getActiveIndices();
+        operation(this.fields, activeIndices);
+    }
+}
+//# sourceMappingURL=SoAStorage.js.map