@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Serialization/ComponentSerializer.js

@@ -0,0 +1,251 @@
+/**
+ * 组件序列化器
+ *
+ * 负责组件的序列化和反序列化操作
+ */
+import { getComponentTypeName } from '../Decorators';
+import { getSerializationMetadata } from './SerializationDecorators';
+/**
+ * 组件序列化器类
+ */
+export class ComponentSerializer {
+    /**
+     * 序列化单个组件
+     *
+     * @param component 要序列化的组件实例
+     * @returns 序列化后的组件数据，如果组件不可序列化则返回null
+     */
+    static serialize(component) {
+        const metadata = getSerializationMetadata(component);
+        if (!metadata) {
+            // 组件没有使用@Serializable装饰器，不可序列化
+            return null;
+        }
+        const componentType = component.constructor;
+        const typeName = metadata.options.typeId || getComponentTypeName(componentType);
+        const data = {};
+        // 序列化标记的字段
+        for (const [fieldName, options] of metadata.fields) {
+            const fieldKey = typeof fieldName === 'symbol' ? fieldName.toString() : fieldName;
+            const value = component[fieldName];
+            // 跳过忽略的字段
+            if (metadata.ignoredFields.has(fieldName)) {
+                continue;
+            }
+            // 使用自定义序列化器或默认序列化
+            const serializedValue = options.serializer
+                ? options.serializer(value)
+                : this.serializeValue(value);
+            // 使用别名或原始字段名
+            const key = options.alias || fieldKey;
+            data[key] = serializedValue;
+        }
+        return {
+            type: typeName,
+            version: metadata.options.version,
+            data
+        };
+    }
+    /**
+     * 反序列化组件
+     *
+     * @param serializedData 序列化的组件数据
+     * @param componentRegistry 组件类型注册表 (类型名 -> 构造函数)
+     * @returns 反序列化后的组件实例，如果失败则返回null
+     */
+    static deserialize(serializedData, componentRegistry) {
+        const componentClass = componentRegistry.get(serializedData.type);
+        if (!componentClass) {
+            console.warn(`未找到组件类型: ${serializedData.type}`);
+            return null;
+        }
+        const metadata = getSerializationMetadata(componentClass);
+        if (!metadata) {
+            console.warn(`组件 ${serializedData.type} 不可序列化`);
+            return null;
+        }
+        // 创建组件实例
+        const component = new componentClass();
+        // 反序列化字段
+        for (const [fieldName, options] of metadata.fields) {
+            const fieldKey = typeof fieldName === 'symbol' ? fieldName.toString() : fieldName;
+            const key = options.alias || fieldKey;
+            const serializedValue = serializedData.data[key];
+            if (serializedValue === undefined) {
+                continue; // 字段不存在于序列化数据中
+            }
+            // 使用自定义反序列化器或默认反序列化
+            const value = options.deserializer
+                ? options.deserializer(serializedValue)
+                : this.deserializeValue(serializedValue);
+            component[fieldName] = value;
+        }
+        return component;
+    }
+    /**
+     * 批量序列化组件
+     *
+     * @param components 组件数组
+     * @returns 序列化后的组件数据数组
+     */
+    static serializeComponents(components) {
+        const result = [];
+        for (const component of components) {
+            const serialized = this.serialize(component);
+            if (serialized) {
+                result.push(serialized);
+            }
+        }
+        return result;
+    }
+    /**
+     * 批量反序列化组件
+     *
+     * @param serializedComponents 序列化的组件数据数组
+     * @param componentRegistry 组件类型注册表
+     * @returns 反序列化后的组件数组
+     */
+    static deserializeComponents(serializedComponents, componentRegistry) {
+        const result = [];
+        for (const serialized of serializedComponents) {
+            const component = this.deserialize(serialized, componentRegistry);
+            if (component) {
+                result.push(component);
+            }
+        }
+        return result;
+    }
+    /**
+     * 默认值序列化
+     *
+     * 处理基本类型、数组、对象等的序列化
+     */
+    static serializeValue(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        // 基本类型
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean') {
+            return value;
+        }
+        // 日期
+        if (value instanceof Date) {
+            return {
+                __type: 'Date',
+                value: value.toISOString()
+            };
+        }
+        // 数组
+        if (Array.isArray(value)) {
+            return value.map((item) => this.serializeValue(item));
+        }
+        // Map (如果没有使用@SerializeMap装饰器)
+        if (value instanceof Map) {
+            return {
+                __type: 'Map',
+                value: Array.from(value.entries())
+            };
+        }
+        // Set
+        if (value instanceof Set) {
+            return {
+                __type: 'Set',
+                value: Array.from(value)
+            };
+        }
+        // 普通对象
+        if (type === 'object' && typeof value === 'object' && !Array.isArray(value)) {
+            const result = {};
+            const obj = value;
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    result[key] = this.serializeValue(obj[key]);
+                }
+            }
+            return result;
+        }
+        // 其他类型（函数等）不序列化
+        return undefined;
+    }
+    /**
+     * 默认值反序列化
+     */
+    static deserializeValue(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        // 基本类型直接返回
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean') {
+            return value;
+        }
+        // 处理特殊类型标记
+        if (type === 'object' && typeof value === 'object' && '__type' in value) {
+            const typedValue = value;
+            switch (typedValue.__type) {
+                case 'Date':
+                    return { __type: 'Date', value: typeof typedValue.value === 'string' ? typedValue.value : String(typedValue.value) };
+                case 'Map':
+                    return { __type: 'Map', value: typedValue.value };
+                case 'Set':
+                    return { __type: 'Set', value: typedValue.value };
+            }
+        }
+        // 数组
+        if (Array.isArray(value)) {
+            return value.map((item) => this.deserializeValue(item));
+        }
+        // 普通对象
+        if (type === 'object' && typeof value === 'object' && !Array.isArray(value)) {
+            const result = {};
+            const obj = value;
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    result[key] = this.deserializeValue(obj[key]);
+                }
+            }
+            return result;
+        }
+        return value;
+    }
+    /**
+     * 验证序列化数据的版本
+     *
+     * @param serializedData 序列化数据
+     * @param expectedVersion 期望的版本号
+     * @returns 版本是否匹配
+     */
+    static validateVersion(serializedData, expectedVersion) {
+        return serializedData.version === expectedVersion;
+    }
+    /**
+     * 获取组件的序列化信息
+     *
+     * @param component 组件实例或组件类
+     * @returns 序列化信息对象，包含类型名、版本、可序列化字段列表
+     */
+    static getSerializationInfo(component) {
+        const metadata = getSerializationMetadata(component);
+        if (!metadata) {
+            return {
+                type: 'unknown',
+                version: 0,
+                fields: [],
+                ignoredFields: [],
+                isSerializable: false
+            };
+        }
+        const componentType = typeof component === 'function'
+            ? component
+            : component.constructor;
+        return {
+            type: metadata.options.typeId || getComponentTypeName(componentType),
+            version: metadata.options.version,
+            fields: Array.from(metadata.fields.keys()).map((k) => typeof k === 'symbol' ? k.toString() : k),
+            ignoredFields: Array.from(metadata.ignoredFields).map((k) => typeof k === 'symbol' ? k.toString() : k),
+            isSerializable: true
+        };
+    }
+}
+//# sourceMappingURL=ComponentSerializer.js.map

package/bin/ECS/Serialization/ComponentSerializer.js.map

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

package/bin/ECS/Serialization/EntitySerializer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 实体序列化器
+ *
+ * 负责实体的序列化和反序列化操作
+ */
+import { Entity } from '../Entity';
+import { ComponentType } from '../Core/ComponentStorage';
+import { SerializedComponent } from './ComponentSerializer';
+import { IScene } from '../IScene';
+import { HierarchySystem } from '../Systems/HierarchySystem';
+/**
+ * 序列化后的实体数据
+ */
+export interface SerializedEntity {
+    /**
+     * 实体ID
+     */
+    id: number;
+    /**
+     * 实体名称
+     */
+    name: string;
+    /**
+     * 实体标签
+     */
+    tag: number;
+    /**
+     * 激活状态
+     */
+    active: boolean;
+    /**
+     * 启用状态
+     */
+    enabled: boolean;
+    /**
+     * 更新顺序
+     */
+    updateOrder: number;
+    /**
+     * 组件列表
+     */
+    components: SerializedComponent[];
+    /**
+     * 子实体列表
+     */
+    children: SerializedEntity[];
+    /**
+     * 父实体ID（如果有）
+     */
+    parentId?: number;
+}
+/**
+ * 实体序列化器类
+ */
+export declare class EntitySerializer {
+    /**
+     * 序列化单个实体
+     *
+     * @param entity 要序列化的实体
+     * @param includeChildren 是否包含子实体（默认true）
+     * @param hierarchySystem 层级系统（可选，用于获取层级信息）
+     * @returns 序列化后的实体数据
+     */
+    static serialize(entity: Entity, includeChildren?: boolean, hierarchySystem?: HierarchySystem): SerializedEntity;
+    /**
+     * 反序列化实体
+     *
+     * @param serializedEntity 序列化的实体数据
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器（用于生成新ID或保持原ID）
+     * @param preserveIds 是否保持原始ID（默认false）
+     * @param scene 目标场景（可选，用于设置entity.scene以支持添加组件）
+     * @param hierarchySystem 层级系统（可选，用于建立层级关系）
+     * @returns 反序列化后的实体
+     */
+    static deserialize(serializedEntity: SerializedEntity, componentRegistry: Map<string, ComponentType>, idGenerator: () => number, preserveIds?: boolean, scene?: IScene, hierarchySystem?: HierarchySystem | null, allEntities?: Map<number, Entity>): Entity;
+    /**
+     * 批量序列化实体
+     *
+     * @param entities 实体数组
+     * @param includeChildren 是否包含子实体
+     * @param hierarchySystem 层级系统（可选，用于获取层级信息）
+     * @returns 序列化后的实体数据数组
+     */
+    static serializeEntities(entities: Entity[], includeChildren?: boolean, hierarchySystem?: HierarchySystem): SerializedEntity[];
+    /**
+     * 批量反序列化实体
+     *
+     * @param serializedEntities 序列化的实体数据数组
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器
+     * @param preserveIds 是否保持原始ID
+     * @param scene 目标场景（可选，用于设置entity.scene以支持添加组件）
+     * @param hierarchySystem 层级系统（可选，用于建立层级关系）
+     * @returns 反序列化后的实体数组
+     */
+    static deserializeEntities(serializedEntities: SerializedEntity[], componentRegistry: Map<string, ComponentType>, idGenerator: () => number, preserveIds?: boolean, scene?: IScene, hierarchySystem?: HierarchySystem | null): {
+        rootEntities: Entity[];
+        allEntities: Map<number, Entity>;
+    };
+    /**
+     * 创建实体的深拷贝
+     *
+     * @param entity 要拷贝的实体
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator ID生成器
+     * @returns 拷贝后的新实体
+     */
+    static clone(entity: Entity, componentRegistry: Map<string, ComponentType>, idGenerator: () => number): Entity;
+}
+//# sourceMappingURL=EntitySerializer.d.ts.map

package/bin/ECS/Serialization/EntitySerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitySerializer.d.ts","sourceRoot":"","sources":["../../../src/ECS/Serialization/EntitySerializer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAuB,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAElC;;OAEG;IACH,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IACzB;;;;;;;OAOG;WACW,SAAS,CACnB,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,OAAc,EAC/B,eAAe,CAAC,EAAE,eAAe,GAClC,gBAAgB;IAwCnB;;;;;;;;;;OAUG;WACW,WAAW,CACrB,gBAAgB,EAAE,gBAAgB,EAClC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,WAAW,EAAE,MAAM,MAAM,EACzB,WAAW,GAAE,OAAe,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,EACxC,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,MAAM;IAwDT;;;;;;;OAOG;WACW,iBAAiB,CAC3B,QAAQ,EAAE,MAAM,EAAE,EAClB,eAAe,GAAE,OAAc,EAC/B,eAAe,CAAC,EAAE,eAAe,GAClC,gBAAgB,EAAE;IAgBrB;;;;;;;;;;OAUG;WACW,mBAAmB,CAC7B,kBAAkB,EAAE,gBAAgB,EAAE,EACtC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,WAAW,EAAE,MAAM,MAAM,EACzB,WAAW,GAAE,OAAe,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,GACzC;QAAE,YAAY,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE;IAoB/D;;;;;;;OAOG;WACW,KAAK,CACf,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,WAAW,EAAE,MAAM,MAAM,GAC1B,MAAM;CAIZ"}

package/bin/ECS/Serialization/EntitySerializer.js

@@ -0,0 +1,155 @@
+/**
+ * 实体序列化器
+ *
+ * 负责实体的序列化和反序列化操作
+ */
+import { Entity } from '../Entity';
+import { ComponentSerializer } from './ComponentSerializer';
+import { HierarchyComponent } from '../Components/HierarchyComponent';
+/**
+ * 实体序列化器类
+ */
+export class EntitySerializer {
+    /**
+     * 序列化单个实体
+     *
+     * @param entity 要序列化的实体
+     * @param includeChildren 是否包含子实体（默认true）
+     * @param hierarchySystem 层级系统（可选，用于获取层级信息）
+     * @returns 序列化后的实体数据
+     */
+    static serialize(entity, includeChildren = true, hierarchySystem) {
+        const serializedComponents = ComponentSerializer.serializeComponents(Array.from(entity.components));
+        const serializedEntity = {
+            id: entity.id,
+            name: entity.name,
+            tag: entity.tag,
+            active: entity.active,
+            enabled: entity.enabled,
+            updateOrder: entity.updateOrder,
+            components: serializedComponents,
+            children: []
+        };
+        // 通过 HierarchyComponent 获取层级信息
+        const hierarchy = entity.getComponent(HierarchyComponent);
+        if (hierarchy?.parentId !== null && hierarchy?.parentId !== undefined) {
+            serializedEntity.parentId = hierarchy.parentId;
+        }
+        // 序列化子实体
+        // 直接使用 HierarchyComponent.childIds 获取子实体
+        if (includeChildren && hierarchy && hierarchy.childIds.length > 0) {
+            // 获取场景引用：优先从 hierarchySystem，否则从 entity.scene
+            const scene = hierarchySystem?.scene ?? entity.scene;
+            if (scene) {
+                for (const childId of hierarchy.childIds) {
+                    const child = scene.findEntityById(childId);
+                    if (child) {
+                        serializedEntity.children.push(this.serialize(child, true, hierarchySystem));
+                    }
+                }
+            }
+        }
+        return serializedEntity;
+    }
+    /**
+     * 反序列化实体
+     *
+     * @param serializedEntity 序列化的实体数据
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器（用于生成新ID或保持原ID）
+     * @param preserveIds 是否保持原始ID（默认false）
+     * @param scene 目标场景（可选，用于设置entity.scene以支持添加组件）
+     * @param hierarchySystem 层级系统（可选，用于建立层级关系）
+     * @returns 反序列化后的实体
+     */
+    static deserialize(serializedEntity, componentRegistry, idGenerator, preserveIds = false, scene, hierarchySystem, allEntities) {
+        // 创建实体（使用原始ID或新生成的ID）
+        const entityId = preserveIds ? serializedEntity.id : idGenerator();
+        const entity = new Entity(serializedEntity.name, entityId);
+        // 将实体添加到收集 Map 中（用于后续添加到场景）
+        allEntities?.set(entity.id, entity);
+        // 如果提供了scene，先设置entity.scene以支持添加组件
+        if (scene) {
+            entity.scene = scene;
+        }
+        // 恢复实体属性
+        entity.tag = serializedEntity.tag;
+        entity.active = serializedEntity.active;
+        entity.enabled = serializedEntity.enabled;
+        entity.updateOrder = serializedEntity.updateOrder;
+        // 反序列化组件
+        const components = ComponentSerializer.deserializeComponents(serializedEntity.components, componentRegistry);
+        for (const component of components) {
+            entity.addComponent(component);
+        }
+        // 重要：清除 HierarchyComponent 中的旧 ID
+        // 当 preserveIds=false 时，序列化的 parentId 和 childIds 是旧 ID，需要重新建立
+        // 通过 hierarchySystem.setParent 会正确设置新的 ID
+        const hierarchy = entity.getComponent(HierarchyComponent);
+        if (hierarchy) {
+            hierarchy.parentId = null;
+            hierarchy.childIds = [];
+        }
+        // 反序列化子实体并建立层级关系
+        for (const childData of serializedEntity.children) {
+            const childEntity = this.deserialize(childData, componentRegistry, idGenerator, preserveIds, scene, hierarchySystem, allEntities);
+            // 使用 HierarchySystem 建立层级关系
+            hierarchySystem?.setParent(childEntity, entity);
+        }
+        return entity;
+    }
+    /**
+     * 批量序列化实体
+     *
+     * @param entities 实体数组
+     * @param includeChildren 是否包含子实体
+     * @param hierarchySystem 层级系统（可选，用于获取层级信息）
+     * @returns 序列化后的实体数据数组
+     */
+    static serializeEntities(entities, includeChildren = true, hierarchySystem) {
+        const result = [];
+        for (const entity of entities) {
+            // 只序列化顶层实体（没有父实体的实体）
+            // 子实体会在父实体序列化时一并处理
+            const hierarchy = entity.getComponent(HierarchyComponent);
+            const bHasParent = hierarchy?.parentId !== null && hierarchy?.parentId !== undefined;
+            if (!bHasParent || !includeChildren) {
+                result.push(this.serialize(entity, includeChildren, hierarchySystem));
+            }
+        }
+        return result;
+    }
+    /**
+     * 批量反序列化实体
+     *
+     * @param serializedEntities 序列化的实体数据数组
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator 实体ID生成器
+     * @param preserveIds 是否保持原始ID
+     * @param scene 目标场景（可选，用于设置entity.scene以支持添加组件）
+     * @param hierarchySystem 层级系统（可选，用于建立层级关系）
+     * @returns 反序列化后的实体数组
+     */
+    static deserializeEntities(serializedEntities, componentRegistry, idGenerator, preserveIds = false, scene, hierarchySystem) {
+        const rootEntities = [];
+        const allEntities = new Map();
+        for (const serialized of serializedEntities) {
+            const entity = this.deserialize(serialized, componentRegistry, idGenerator, preserveIds, scene, hierarchySystem, allEntities);
+            rootEntities.push(entity);
+        }
+        return { rootEntities, allEntities };
+    }
+    /**
+     * 创建实体的深拷贝
+     *
+     * @param entity 要拷贝的实体
+     * @param componentRegistry 组件类型注册表
+     * @param idGenerator ID生成器
+     * @returns 拷贝后的新实体
+     */
+    static clone(entity, componentRegistry, idGenerator) {
+        const serialized = this.serialize(entity, true);
+        return this.deserialize(serialized, componentRegistry, idGenerator, false);
+    }
+}
+//# sourceMappingURL=EntitySerializer.js.map

package/bin/ECS/Serialization/EntitySerializer.js.map

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