fix(build): 修复 Web 构建组件注册和用户脚本打包问题 (#302)

* refactor(build): 重构 Web 构建管线，支持配置驱动的 Import Maps - 重构 WebBuildPipeline 支持 split-bundles 和 single-bundle 两种构建模式 - 使用 module.json 的 isCore 字段识别核心模块，消除硬编码列表 - 动态生成 Import Map，从模块清单的 name 字段获取包名映射 - 动态扫描 module.json 文件，不再依赖固定模块列表 - 添加 HTTP 服务器启动脚本 (start-server.bat/sh) 支持 ESM 模块 - 更新 BuildSettingsPanel UI 支持新的构建模式选项 - 添加多语言支持 (zh/en/es) * fix(build): 修复 Web 构建组件注册和用户脚本打包问题主要修复: - 修复组件反序列化时找不到类型的问题 - @ECSComponent 装饰器现在自动注册到 ComponentRegistry - 添加未使用装饰器的组件警告 - 构建管线自动扫描用户脚本（无需入口文件）架构改进: - 解决 Decorators ↔ ComponentRegistry 循环依赖 - 新建 ComponentTypeUtils.ts 作为底层无依赖模块 - 移除冗余的防御性 register 调用 - 统一 ComponentType 定义位置 * refactor(build): 统一 WASM 配置架构，移除硬编码 - 新增 wasmConfig 统一配置替代 wasmPaths/wasmBindings - wasmConfig.files 支持多候选源路径和明确目标路径 - wasmConfig.runtimePath 指定运行时加载路径 - 重构 _copyWasmFiles 使用统一配置 - HTML 生成使用配置中的 runtimePath - 移除 physics-rapier2d 的冗余 WASM 配置（由 rapier2d 负责） - IBuildFileSystem 新增 deleteFile 方法 * feat(build): 单文件构建模式完善和场景配置驱动 ## 主要改动 ### 单文件构建（single-file mode） - 修复 WASM 初始化问题，支持 initSync 同步初始化 - 配置驱动的 WASM 识别，通过 wasmConfig.isEngineCore 标识核心引擎模块 - 从 wasmConfig.files 动态获取 JS 绑定路径，消除硬编码 ### 场景配置 - 构建验证：必须选择至少一个场景才能构建 - 自动扫描：项目加载时扫描 scenes 目录 - 抽取 _filterScenesByWhitelist 公共方法统一过滤逻辑 ### 构建面板优化 - availableScenes prop 传递场景列表 - 场景复选框可点击切换启用状态 - 移除动态 import，使用 prop 传入数据 * chore(build): 补充构建相关的辅助改动 - 添加 BuildFileSystemService 的 listFilesByExtension 优化 - 更新 module.json 添加 externalDependencies 配置 - BrowserRuntime 支持 wasmModule 参数传递 - GameRuntime 添加 loadSceneFromData 方法 - Rust 构建命令更新 - 国际化文案更新 * feat(build): 持久化构建设置到项目配置 ## 设计架构 ### ProjectService 扩展 - 新增 BuildSettingsConfig 接口定义构建配置字段 - ProjectConfig 添加 buildSettings 字段 - 新增 getBuildSettings / updateBuildSettings 方法 ### BuildSettingsPanel - 组件挂载时从 projectService 加载已保存配置 - 设置变化时自动保存（500ms 防抖） - 场景选择状态与项目配置同步 ### 配置保存位置保存在项目的 ecs-editor.config.json 中： - scenes: 选中的场景列表 - buildMode: 构建模式 - companyName/productName/version: 产品信息 - developmentBuild/sourceMap: 构建选项 * fix(editor): Ctrl+S 仅在主编辑区域触发保存场景 - 模态窗口打开时跳过（构建设置、设置、关于等） - 焦点在 input/textarea/contenteditable 时跳过 * fix(tests): 修复 ECS 测试中 Component 注册问题 - 为所有测试 Component 类添加 @ECSComponent 装饰器 - 移除 beforeEach 中的 ComponentRegistry.reset() 调用 - 将内联 Component 类移到文件顶层以支持装饰器 - 更新测试预期值匹配新的组件类型名称 - 添加缺失的 HierarchyComponent 导入所有 1388 个测试现已通过。
2025-12-10 18:23:29 +08:00
parent 1b0d38edce
commit a716d8006c
67 changed files with 3671 additions and 1455 deletions
--- a/packages/core/src/ECS/Core/ArchetypeSystem.ts
+++ b/packages/core/src/ECS/Core/ArchetypeSystem.ts
@@ -271,9 +271,6 @@ export class ArchetypeSystem {
    private generateArchetypeId(componentTypes: ComponentType[]): ArchetypeId {
        const mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
        for (const type of componentTypes) {
-            if (!ComponentRegistry.isRegistered(type)) {
-                ComponentRegistry.register(type);
-            }
            const bitMask = ComponentRegistry.getBitMask(type);
            BitMask64Utils.orInPlace(mask, bitMask);
        }
--- a/packages/core/src/ECS/Core/ComponentStorage.ts
+++ b/packages/core/src/ECS/Core/ComponentStorage.ts
@@ -2,11 +2,12 @@ import { Component } from '../Component';
 import { BitMask64Utils, BitMask64Data } from '../Utils/BigIntCompatibility';
 import { SoAStorage, SupportedTypedArray } from './SoAStorage';
 import { createLogger } from '../../Utils/Logger';
-import { getComponentTypeName } from '../Decorators';
-import { ComponentRegistry, ComponentType } from './ComponentStorage/ComponentRegistry';
+import { getComponentTypeName, ComponentType } from '../Decorators';
+import { ComponentRegistry } from './ComponentStorage/ComponentRegistry';

 // 导出核心类型
-export { ComponentRegistry, ComponentType };
+export { ComponentRegistry };
+export type { ComponentType };


 /**
@@ -20,11 +21,6 @@ export class ComponentStorage<T extends Component> {

    constructor(componentType: ComponentType<T>) {
        this.componentType = componentType;
-
-        // 确保组件类型已注册
-        if (!ComponentRegistry.isRegistered(componentType)) {
-            ComponentRegistry.register(componentType);
-        }
    }

    /**
--- a/packages/core/src/ECS/Core/ComponentStorage/ComponentRegistry.ts
+++ b/packages/core/src/ECS/Core/ComponentStorage/ComponentRegistry.ts
@@ -1,12 +1,11 @@
 import { Component } from '../../Component';
 import { BitMask64Utils, BitMask64Data } from '../../Utils/BigIntCompatibility';
 import { createLogger } from '../../../Utils/Logger';
-import { getComponentTypeName } from '../../Decorators';
-
-/**
- * 组件类型定义
- */
-export type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
+import {
+    ComponentType,
+    getComponentTypeName,
+    hasECSComponentDecorator
+} from './ComponentTypeUtils';

 /**
 * 组件注册表
@@ -29,14 +28,33 @@ export class ComponentRegistry {
     */
    private static hotReloadEnabled = false;

+    /**
+     * 已警告过的组件类型集合，避免重复警告
+     * Set of warned component types to avoid duplicate warnings
+     */
+    private static warnedComponents = new Set<Function>();
+
    /**
     * 注册组件类型并分配位掩码
+     * Register component type and allocate bitmask
+     *
     * @param componentType 组件类型
     * @returns 分配的位索引
     */
    public static register<T extends Component>(componentType: ComponentType<T>): number {
        const typeName = getComponentTypeName(componentType);

+        // 检查是否使用了 @ECSComponent 装饰器
+        // Check if @ECSComponent decorator is used
+        if (!hasECSComponentDecorator(componentType) && !this.warnedComponents.has(componentType)) {
+            this.warnedComponents.add(componentType);
+            console.warn(
+                `[ComponentRegistry] Component "${typeName}" is missing @ECSComponent decorator. ` +
+                `This may cause issues with serialization and code minification. ` +
+                `Please add: @ECSComponent('${typeName}')`
+            );
+        }
+
        if (this.componentTypes.has(componentType)) {
            const existingIndex = this.componentTypes.get(componentType)!;
            return existingIndex;
@@ -324,6 +342,7 @@ export class ComponentRegistry {
        this.componentNameToType.clear();
        this.componentNameToId.clear();
        this.maskCache.clear();
+        this.warnedComponents.clear();
        this.nextBitIndex = 0;
        this.hotReloadEnabled = false;
    }
--- a/packages/core/src/ECS/Core/ComponentStorage/ComponentTypeUtils.ts
+++ b/packages/core/src/ECS/Core/ComponentStorage/ComponentTypeUtils.ts
@@ -0,0 +1,83 @@
+/**
+ * Component Type Utilities
+ * 组件类型工具函数
+ *
+ * This module contains low-level utilities for component type handling.
+ * It has NO dependencies on other ECS modules to avoid circular imports.
+ *
+ * 此模块包含组件类型处理的底层工具函数。
+ * 它不依赖其他 ECS 模块，以避免循环导入。
+ */
+
+import type { Component } from '../../Component';
+
+/**
+ * 组件类型定义
+ * Component type definition
+ */
+export type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
+
+/**
+ * 存储组件类型名称的 Symbol 键
+ * Symbol key for storing component type name
+ */
+export const COMPONENT_TYPE_NAME = Symbol('ComponentTypeName');
+
+/**
+ * 存储组件依赖的 Symbol 键
+ * Symbol key for storing component dependencies
+ */
+export const COMPONENT_DEPENDENCIES = Symbol('ComponentDependencies');
+
+/**
+ * 检查组件是否使用了 @ECSComponent 装饰器
+ * Check if component has @ECSComponent decorator
+ *
+ * @param componentType 组件构造函数
+ * @returns 是否有装饰器
+ */
+export function hasECSComponentDecorator(componentType: ComponentType): boolean {
+    return !!(componentType as any)[COMPONENT_TYPE_NAME];
+}
+
+/**
+ * 获取组件类型的名称，优先使用装饰器指定的名称
+ * Get component type name, preferring decorator-specified name
+ *
+ * @param componentType 组件构造函数
+ * @returns 组件类型名称
+ */
+export function getComponentTypeName(componentType: ComponentType): string {
+    // 优先使用装饰器指定的名称
+    // Prefer decorator-specified name
+    const decoratorName = (componentType as any)[COMPONENT_TYPE_NAME];
+    if (decoratorName) {
+        return decoratorName;
+    }
+
+    // 回退到 constructor.name
+    // Fallback to constructor.name
+    return componentType.name || 'UnknownComponent';
+}
+
+/**
+ * 从组件实例获取类型名称
+ * Get type name from component instance
+ *
+ * @param component 组件实例
+ * @returns 组件类型名称
+ */
+export function getComponentInstanceTypeName(component: Component): string {
+    return getComponentTypeName(component.constructor as ComponentType);
+}
+
+/**
+ * 获取组件的依赖列表
+ * Get component dependencies
+ *
+ * @param componentType 组件构造函数
+ * @returns 依赖的组件名称列表
+ */
+export function getComponentDependencies(componentType: ComponentType): string[] | undefined {
+    return (componentType as any)[COMPONENT_DEPENDENCIES];
+}
--- a/packages/core/src/ECS/Core/QuerySystem.ts
+++ b/packages/core/src/ECS/Core/QuerySystem.ts
@@ -821,13 +821,9 @@ export class QuerySystem {
            return cached;
        }

-        // 使用ComponentRegistry而不是ComponentTypeManager,确保bitIndex一致
+        // 使用ComponentRegistry确保bitIndex一致
        const mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
        for (const type of componentTypes) {
-            // 确保组件已注册
-            if (!ComponentRegistry.isRegistered(type)) {
-                ComponentRegistry.register(type);
-            }
            const bitMask = ComponentRegistry.getBitMask(type);
            BitMask64Utils.orInPlace(mask, bitMask);
        }
--- a/packages/core/src/ECS/Decorators/TypeDecorators.ts
+++ b/packages/core/src/ECS/Decorators/TypeDecorators.ts
@@ -1,36 +1,48 @@
+/**
+ * Type Decorators for ECS Components and Systems
+ * ECS 组件和系统的类型装饰器
+ *
+ * Provides decorators to mark component/system types with stable names
+ * that survive code minification.
+ *
+ * 提供装饰器为组件/系统类型标记稳定的名称，使其在代码混淆后仍然有效。
+ */
+
 import type { Component } from '../Component';
 import type { EntitySystem } from '../Systems';
-import { ComponentType } from '../../Types';
-
-/**
- * 存储组件类型名称的Symbol键
- */
-export const COMPONENT_TYPE_NAME = Symbol('ComponentTypeName');
-
-/**
- * 存储组件依赖的Symbol键
- */
-export const COMPONENT_DEPENDENCIES = Symbol('ComponentDependencies');
+import { ComponentRegistry } from '../Core/ComponentStorage/ComponentRegistry';
+import {
+    COMPONENT_TYPE_NAME,
+    COMPONENT_DEPENDENCIES
+} from '../Core/ComponentStorage/ComponentTypeUtils';

 /**
 * 存储系统类型名称的Symbol键
+ * Symbol key for storing system type name
 */
 export const SYSTEM_TYPE_NAME = Symbol('SystemTypeName');

 /**
 * 组件装饰器配置选项
+ * Component decorator options
 */
 export interface ComponentOptions {
-    /** 依赖的其他组件名称列表 */
+    /** 依赖的其他组件名称列表 | List of required component names */
    requires?: string[];
 }

 /**
 * 组件类型装饰器
- * 用于为组件类指定固定的类型名称，避免在代码混淆后失效
+ * Component type decorator
 *
- * @param typeName 组件类型名称
- * @param options 组件配置选项
+ * 用于为组件类指定固定的类型名称，避免在代码混淆后失效。
+ * 装饰器执行时会自动注册到 ComponentRegistry，使组件可以通过名称反序列化。
+ *
+ * Assigns a stable type name to component classes that survives minification.
+ * The decorator automatically registers to ComponentRegistry, enabling deserialization by name.
+ *
+ * @param typeName 组件类型名称 | Component type name
+ * @param options 组件配置选项 | Component options
 * @example
 * ```typescript
 * @ECSComponent('Position')
@@ -39,7 +51,7 @@ export interface ComponentOptions {
 *     y: number = 0;
 * }
 *
- * // 带依赖声明
+ * // 带依赖声明 | With dependency declaration
 * @ECSComponent('SpriteAnimator', { requires: ['Sprite'] })
 * class SpriteAnimatorComponent extends Component {
 *     // ...
@@ -53,48 +65,52 @@ export function ECSComponent(typeName: string, options?: ComponentOptions) {
        }

        // 在构造函数上存储类型名称
+        // Store type name on constructor
        (target as any)[COMPONENT_TYPE_NAME] = typeName;

        // 存储依赖关系
+        // Store dependencies
        if (options?.requires) {
            (target as any)[COMPONENT_DEPENDENCIES] = options.requires;
        }

+        // 自动注册到 ComponentRegistry，使组件可以通过名称查找
+        // Auto-register to ComponentRegistry, enabling lookup by name
+        ComponentRegistry.register(target);
+
        return target;
    };
 }

 /**
- * 获取组件的依赖列表
- */
-export function getComponentDependencies(componentType: ComponentType): string[] | undefined {
-    return (componentType as any)[COMPONENT_DEPENDENCIES];
-}
-
-/**
- * System元数据配置
+ * System 元数据配置
+ * System metadata configuration
 */
 export interface SystemMetadata {
    /**
     * 更新顺序（数值越小越先执行，默认0）
+     * Update order (lower values execute first, default 0)
     */
    updateOrder?: number;

    /**
     * 是否默认启用（默认true）
+     * Whether enabled by default (default true)
     */
    enabled?: boolean;
 }

 /**
 * 系统类型装饰器
- * 用于为系统类指定固定的类型名称，避免在代码混淆后失效
+ * System type decorator
 *
- * @param typeName 系统类型名称
- * @param metadata 系统元数据配置
+ * 用于为系统类指定固定的类型名称，避免在代码混淆后失效。
+ * Assigns a stable type name to system classes that survives minification.
+ *
+ * @param typeName 系统类型名称 | System type name
+ * @param metadata 系统元数据配置 | System metadata configuration
 * @example
 * ```typescript
- * // 基本使用
 * @ECSSystem('Movement')
 * class MovementSystem extends EntitySystem {
 *     protected process(entities: Entity[]): void {
@@ -102,16 +118,9 @@ export interface SystemMetadata {
 *     }
 * }
 *
- * // 配置更新顺序和依赖注入
- * @Injectable()
 * @ECSSystem('Physics', { updateOrder: 10 })
 * class PhysicsSystem extends EntitySystem {
- *     @InjectProperty(CollisionSystem)
- *     private collision!: CollisionSystem;
- *
- *     constructor() {
- *         super(Matcher.empty().all(Transform, RigidBody));
- *     }
+ *     // ...
 * }
 * ```
 */
@@ -122,9 +131,11 @@ export function ECSSystem(typeName: string, metadata?: SystemMetadata) {
        }

        // 在构造函数上存储类型名称
+        // Store type name on constructor
        (target as any)[SYSTEM_TYPE_NAME] = typeName;

        // 存储元数据
+        // Store metadata
        if (metadata) {
            (target as any).__systemMetadata__ = metadata;
        }
@@ -134,67 +145,37 @@ export function ECSSystem(typeName: string, metadata?: SystemMetadata) {
 }

 /**
- * 获取System的元数据
+ * 获取 System 的元数据
+ * Get System metadata
 */
 export function getSystemMetadata(systemType: new (...args: any[]) => EntitySystem): SystemMetadata | undefined {
    return (systemType as any).__systemMetadata__;
 }

-/**
- * 获取组件类型的名称，优先使用装饰器指定的名称
- *
- * @param componentType 组件构造函数
- * @returns 组件类型名称
- */
-export function getComponentTypeName(
-    componentType: ComponentType
-): string {
-    // 优先使用装饰器指定的名称
-    const decoratorName = (componentType as any)[COMPONENT_TYPE_NAME];
-    if (decoratorName) {
-        return decoratorName;
-    }
-
-    // 回退到constructor.name
-    return componentType.name || 'UnknownComponent';
-}
-
 /**
 * 获取系统类型的名称，优先使用装饰器指定的名称
+ * Get system type name, preferring decorator-specified name
 *
- * @param systemType 系统构造函数
- * @returns 系统类型名称
+ * @param systemType 系统构造函数 | System constructor
+ * @returns 系统类型名称 | System type name
 */
 export function getSystemTypeName<T extends EntitySystem>(
    systemType: new (...args: any[]) => T
 ): string {
-    // 优先使用装饰器指定的名称
    const decoratorName = (systemType as any)[SYSTEM_TYPE_NAME];
    if (decoratorName) {
        return decoratorName;
    }
-
-    // 回退到constructor.name
    return systemType.name || 'UnknownSystem';
 }

-/**
- * 从组件实例获取类型名称
- *
- * @param component 组件实例
- * @returns 组件类型名称
- */
-export function getComponentInstanceTypeName(component: Component): string {
-    return getComponentTypeName(component.constructor as ComponentType);
-}
-
 /**
 * 从系统实例获取类型名称
+ * Get type name from system instance
 *
- * @param system 系统实例
- * @returns 系统类型名称
+ * @param system 系统实例 | System instance
+ * @returns 系统类型名称 | System type name
 */
 export function getSystemInstanceTypeName(system: EntitySystem): string {
    return getSystemTypeName(system.constructor as new (...args: any[]) => EntitySystem);
 }
-
--- a/packages/core/src/ECS/Decorators/index.ts
+++ b/packages/core/src/ECS/Decorators/index.ts
@@ -1,19 +1,37 @@
+// ============================================================================
+// Component Type Utilities (from ComponentTypeUtils - no circular deps)
+// 组件类型工具（来自 ComponentTypeUtils - 无循环依赖）
+// ============================================================================
+export {
+    COMPONENT_TYPE_NAME,
+    COMPONENT_DEPENDENCIES,
+    getComponentTypeName,
+    getComponentInstanceTypeName,
+    getComponentDependencies,
+    hasECSComponentDecorator
+} from '../Core/ComponentStorage/ComponentTypeUtils';
+
+export type { ComponentType } from '../Core/ComponentStorage/ComponentTypeUtils';
+
+// ============================================================================
+// Type Decorators (ECSComponent, ECSSystem)
+// 类型装饰器
+// ============================================================================
 export {
    ECSComponent,
    ECSSystem,
-    getComponentTypeName,
    getSystemTypeName,
-    getComponentInstanceTypeName,
    getSystemInstanceTypeName,
    getSystemMetadata,
-    getComponentDependencies,
-    COMPONENT_TYPE_NAME,
-    COMPONENT_DEPENDENCIES,
    SYSTEM_TYPE_NAME
 } from './TypeDecorators';

 export type { SystemMetadata, ComponentOptions } from './TypeDecorators';

+// ============================================================================
+// Entity Reference Decorator
+// 实体引用装饰器
+// ============================================================================
 export {
    EntityRef,
    getEntityRefMetadata,
@@ -23,6 +41,10 @@ export {

 export type { EntityRefMetadata } from './EntityRefDecorator';

+// ============================================================================
+// Property Decorator
+// 属性装饰器
+// ============================================================================
 export {
    Property,
    getPropertyMetadata,
@@ -30,4 +52,11 @@ export {
    PROPERTY_METADATA
 } from './PropertyDecorator';

-export type { PropertyOptions, PropertyType, PropertyControl, PropertyAction, AssetType, EnumOption } from './PropertyDecorator';
+export type {
+    PropertyOptions,
+    PropertyType,
+    PropertyControl,
+    PropertyAction,
+    AssetType,
+    EnumOption
+} from './PropertyDecorator';
--- a/packages/core/src/ECS/Entity.ts
+++ b/packages/core/src/ECS/Entity.ts
@@ -368,11 +368,8 @@ export class Entity {
    private addComponentInternal<T extends Component>(component: T): T {
        const componentType = component.constructor as ComponentType<T>;

-        if (!ComponentRegistry.isRegistered(componentType)) {
-            ComponentRegistry.register(componentType);
-        }
-
-        // 更新位掩码
+        // 更新位掩码（组件已通过 @ECSComponent 装饰器自动注册）
+        // Update bitmask (component already registered via @ECSComponent decorator)
        const componentMask = ComponentRegistry.getBitMask(componentType);
        BitMask64Utils.orInPlace(this._componentMask, componentMask);

--- a/packages/core/src/ECS/Scene.ts
+++ b/packages/core/src/ECS/Scene.ts
@@ -672,10 +672,6 @@ export class Scene implements IScene {
     * @param system 系统 | System
     */
    private addSystemToComponentIndex(componentType: ComponentType, system: EntitySystem): void {
-        if (!ComponentRegistry.isRegistered(componentType)) {
-            ComponentRegistry.register(componentType);
-        }
-
        const componentId = ComponentRegistry.getBitIndex(componentType);
        let systems = this._componentIdToSystems.get(componentId);

--- a/packages/core/src/ECS/Utils/ComponentSparseSet.ts
+++ b/packages/core/src/ECS/Utils/ComponentSparseSet.ts
@@ -85,11 +85,6 @@ export class ComponentSparseSet {
            const componentType = component.constructor as ComponentType;
            entityComponents.add(componentType);

-            // 确保组件类型已注册
-            if (!ComponentRegistry.isRegistered(componentType)) {
-                ComponentRegistry.register(componentType);
-            }
-
            // 获取组件位掩码并合并
            const bitMask = ComponentRegistry.getBitMask(componentType);
            BitMask64Utils.orInPlace(componentMask, bitMask);
--- a/packages/core/src/Types/index.ts
+++ b/packages/core/src/Types/index.ts
@@ -49,14 +49,6 @@ export interface ISystemBase {
    lateUpdate?(): void;
 }

-/**
- * 组件类型定义
- *
- * 用于类型安全的组件操作
- * 支持任意构造函数签名，提供更好的类型安全性
- */
-export type ComponentType<T extends IComponent = IComponent> = new (...args: any[]) => T;
-
 /**
 * 事件总线接口
 * 提供类型安全的事件发布订阅机制