refactor(plugin): 重构插件系统架构，统一类型导入路径 (#296)
* refactor(plugin): 重构插件系统架构，统一类型导入路径 ## 主要更改 ### 新增 @esengine/plugin-types 包 - 提供打破循环依赖的最小类型定义 - 包含 ServiceToken, createServiceToken, PluginServiceRegistry, IEditorModuleBase ### engine-core 类型统一 - IPlugin<T> 泛型参数改为 T = unknown - 所有运行时类型（IRuntimeModule, ModuleManifest, SystemContext）在此定义 - 新增 PluginServiceRegistry.ts 导出服务令牌相关类型 ### editor-core 类型优化 - 重命名 IPluginLoader.ts 为 EditorModule.ts - 新增 IEditorPlugin = IPlugin<IEditorModuleLoader> 类型别名 - 移除弃用别名 IPluginLoader, IRuntimeModuleLoader ### 编辑器插件更新 - 所有 9 个编辑器插件使用 IEditorPlugin 类型 - 统一从 editor-core 导入编辑器类型 ### 服务令牌规范 - 各模块在 tokens.ts 中定义自己的服务接口和令牌 - 遵循"谁定义接口，谁导出 Token"原则 ## 导入规范 | 场景 | 导入来源 | |------|---------| | 运行时模块 | @esengine/engine-core | | 编辑器插件 | @esengine/editor-core | | 服务令牌 | @esengine/engine-core | * refactor(plugin): 完善服务令牌规范，统一运行时模块 ## 更改内容 ### 运行时模块优化 - particle: 使用 PluginServiceRegistry 获取依赖服务 - physics-rapier2d: 通过服务令牌注册/获取物理查询接口 - tilemap: 使用服务令牌获取物理系统依赖 - sprite: 导出服务令牌 - ui: 导出服务令牌 - behavior-tree: 使用服务令牌系统 ### 资产系统增强 - IAssetManager 接口扩展 - 加载器使用服务令牌获取依赖 ### 运行时核心 - GameRuntime 使用 PluginServiceRegistry - 导出服务令牌相关类型 ### 编辑器服务 - EngineService 适配新的服务令牌系统 - AssetRegistryService 优化 * fix: 修复 editor-app 和 behavior-tree-editor 中的类型引用 - editor-app/PluginLoader.ts: 使用 IPlugin 替代 IPluginLoader - behavior-tree-editor: 使用 IEditorPlugin 替代 IPluginLoader * fix(ui): 添加缺失的 ecs-engine-bindgen 依赖 UIRuntimeModule 使用 EngineBridgeToken，需要声明对 ecs-engine-bindgen 的依赖 * fix(type): 解决 ServiceToken 跨包类型兼容性问题 - 在 engine-core 中直接定义 ServiceToken 和 PluginServiceRegistry 而不是从 plugin-types 重新导出，确保 tsup 生成的类型声明 以 engine-core 作为类型来源 - 移除 RuntimeResolver.ts 中的硬编码模块 ID 检查， 改用 module.json 中的 name 配置 - 修复 pnpm-lock.yaml 中的依赖记录 * refactor(arch): 改进架构设计，移除硬编码 - 统一类型导出：editor-core 从 engine-core 导入 IEditorModuleBase - RuntimeResolver: 将硬编码路径改为配置常量和搜索路径列表 - 添加跨平台安装路径支持（Windows/macOS/Linux） - 使用 ENGINE_WASM_CONFIG 配置引擎 WASM 文件信息 - IBundlePackOptions 添加 preloadBundles 配置项 * fix(particle): 添加缺失的 ecs-engine-bindgen 依赖 ParticleRuntimeModule 导入了 @esengine/ecs-engine-bindgen 的 tokens， 但 package.json 中未声明该依赖，导致 CI 构建失败。 * fix(physics-rapier2d): 移除不存在的 PhysicsSystemContext 导出 PhysicsRuntimeModule 中不存在该类型，导致 type-check 失败
This commit is contained in:
YHH
GitHub
@@ -2,14 +2,43 @@
|
||||
* 插件系统核心类型定义
|
||||
* Plugin system core type definitions
|
||||
*
|
||||
* 这是插件类型的唯一定义源，editor-core 重新导出并扩展这些类型。
|
||||
* This is the single source of truth for plugin types. editor-core re-exports and extends them.
|
||||
* 这是运行时插件类型的唯一定义源。
|
||||
* 编辑器类型在 editor-core 中扩展这些类型。
|
||||
*
|
||||
* This is the single source of truth for runtime plugin types.
|
||||
* Editor types extend these in editor-core.
|
||||
*
|
||||
* @see docs/architecture/plugin-system-design.md
|
||||
*/
|
||||
|
||||
import type { ComponentRegistry as ComponentRegistryType, IScene, ServiceContainer } from '@esengine/ecs-framework';
|
||||
import { TransformComponent } from './TransformComponent';
|
||||
import type { ModuleManifest } from './ModuleManifest';
|
||||
|
||||
// 从本地模块导入服务令牌系统（确保 tsup 生成的类型以 engine-core 为源）
|
||||
// Import service token system from local module (ensures tsup generates types with engine-core as source)
|
||||
import {
|
||||
PluginServiceRegistry,
|
||||
createServiceToken,
|
||||
TransformTypeToken,
|
||||
type ServiceToken
|
||||
} from './PluginServiceRegistry';
|
||||
|
||||
// 导出服务令牌系统 | Export service token system
|
||||
export {
|
||||
PluginServiceRegistry,
|
||||
createServiceToken,
|
||||
TransformTypeToken,
|
||||
type ServiceToken
|
||||
};
|
||||
|
||||
// 重新导出 IEditorModuleBase（供编辑器插件使用）| Re-export for editor plugins
|
||||
export type { IEditorModuleBase } from '@esengine/plugin-types';
|
||||
|
||||
// ============================================================================
|
||||
// 加载阶段 | Loading Phase
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 加载阶段 - 控制插件模块的加载顺序
|
||||
* Loading phase - controls the loading order of plugin modules
|
||||
@@ -28,16 +57,38 @@ export type LoadingPhase =
|
||||
/**
|
||||
* 系统创建上下文
|
||||
* System creation context
|
||||
*
|
||||
* 包含运行时配置和插件服务注册表。
|
||||
* Contains runtime configuration and plugin service registry.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // 导入需要的 Token | Import needed tokens
|
||||
* import { Physics2DQueryToken } from '@esengine/physics-rapier2d';
|
||||
* import { AssetManagerToken } from '@esengine/asset-system';
|
||||
*
|
||||
* // 注册服务 | Register service
|
||||
* context.services.register(Physics2DQueryToken, physicsSystem);
|
||||
*
|
||||
* // 获取服务（可选）| Get service (optional)
|
||||
* const physics = context.services.get(Physics2DQueryToken);
|
||||
*
|
||||
* // 获取服务（必需）| Get service (required)
|
||||
* const physics = context.services.require(Physics2DQueryToken);
|
||||
* ```
|
||||
*/
|
||||
export interface SystemContext {
|
||||
/** 是否为编辑器模式 | Is editor mode */
|
||||
isEditor: boolean;
|
||||
/** 引擎桥接（如有） | Engine bridge (if available) */
|
||||
engineBridge?: any;
|
||||
/** 渲染系统（如有） | Render system (if available) */
|
||||
renderSystem?: any;
|
||||
/** 其他已创建的系统引用 | Other created system references */
|
||||
[key: string]: any;
|
||||
readonly isEditor: boolean;
|
||||
|
||||
/**
|
||||
* 插件服务注册表
|
||||
* Plugin service registry
|
||||
*
|
||||
* 用于跨插件共享服务。
|
||||
* For sharing services between plugins.
|
||||
*/
|
||||
readonly services: PluginServiceRegistry;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
@@ -95,15 +146,41 @@ export interface IRuntimeModule {
|
||||
* Plugin interface
|
||||
*
|
||||
* 这是所有插件包导出的统一类型。
|
||||
* 使用泛型允许编辑器模块使用更具体的类型。
|
||||
*
|
||||
* This is the unified type that all plugin packages export.
|
||||
* Uses generics to allow editor modules to use more specific types.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // 纯运行时插件 | Pure runtime plugin
|
||||
* const MyPlugin: IPlugin = {
|
||||
* manifest,
|
||||
* runtimeModule: new MyRuntimeModule()
|
||||
* };
|
||||
*
|
||||
* // 编辑器插件（在 editor-core 中定义 IEditorPlugin）
|
||||
* // Editor plugin (IEditorPlugin defined in editor-core)
|
||||
* const MyEditorPlugin: IEditorPlugin = {
|
||||
* manifest,
|
||||
* runtimeModule: new MyRuntimeModule(),
|
||||
* editorModule: new MyEditorModule()
|
||||
* };
|
||||
* ```
|
||||
*/
|
||||
export interface IPlugin {
|
||||
export interface IPlugin<TEditorModule = unknown> {
|
||||
/** 模块清单 | Module manifest */
|
||||
readonly manifest: ModuleManifest;
|
||||
/** 运行时模块（可选） | Runtime module (optional) */
|
||||
readonly runtimeModule?: IRuntimeModule;
|
||||
/** 编辑器模块（可选，类型为 any 以避免循环依赖） | Editor module (optional, typed as any to avoid circular deps) */
|
||||
readonly editorModule?: any;
|
||||
/**
|
||||
* 编辑器模块（可选）
|
||||
* Editor module (optional)
|
||||
*
|
||||
* 泛型参数允许 editor-core 使用 IEditorModuleLoader 类型。
|
||||
* Generic parameter allows editor-core to use IEditorModuleLoader type.
|
||||
*/
|
||||
readonly editorModule?: TEditorModule;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
|
||||
Reference in New Issue
Block a user