CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: 类型安全与接口清理 (#311)

Browse Source 
* refactor: 分解 IEngineBridge 为单一职责接口

- 新增 ITextureService, IDynamicAtlasService, ICoordinateService, IRenderConfigService
- 移除 EngineBridgeToken，改用具体服务 Token
- 更新 camera, ui, particle 等模块使用新接口
- 优化装饰器类型安全，使用 Symbol-based metadata 访问模式

* refactor: 删除 plugin-types 包，统一 createServiceToken 实现

- 移动 IEditorModuleBase 接口到 engine-core
- 移除 engine-core 和 editor-core 对 plugin-types 的依赖
- 删除冗余的 plugin-types 包
- 统一使用 core 中基于 Symbol.for() 的 createServiceToken

* refactor: 统一 IPlugin 接口，移除 deprecated 别名

- 移除 engine-core、editor-core、runtime-core 中的 IPlugin 别名
- 模块插件统一使用 IRuntimePlugin（运行时）或 IEditorPlugin（编辑器）
- 保留 core 包中的 IPlugin 作为 ECS 核心插件接口（不同概念）
- 更新所有消费方使用正确的类型

* refactor: 重命名 editor-core ComponentRegistry 为 EditorComponentRegistry

- 消除与 core 包 ComponentRegistry（ECS 位掩码管理）的命名歧义
- editor-core 的 EditorComponentRegistry 专用于编辑器组件元数据
- 更新所有编辑器包使用新名称
This commit is contained in:
YHH
2025-12-19 17:48:18 +08:00
committed by GitHub
parent ecdb8f2021
commit e24c850568
51 changed files with 492 additions and 623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
packages/core/src/ECS/Core/ComponentStorage/ComponentTypeUtils.ts
View File

@@ -14,7 +14,11 @@ import type { Component } from '../../Component';
/**
* 组件类型定义
* Component type definition
*
* 注意：构造函数参数使用 any[] 是必要的，因为组件可以有各种不同签名的构造函数
* Note: Constructor args use any[] because components can have various constructor signatures
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
/**
@@ -61,6 +65,51 @@ export interface ComponentEditorOptions {
icon?: string;
}
/**
* 组件构造函数上的元数据接口
* Metadata interface stored on component constructors
*
* 使用 Symbol 索引签名来类型安全地访问装饰器存储的元数据
* Uses Symbol index signature to safely access decorator-stored metadata
*/
export interface ComponentTypeMetadata {
readonly [COMPONENT_TYPE_NAME]?: string;
readonly [COMPONENT_DEPENDENCIES]?: string[];
readonly [COMPONENT_EDITOR_OPTIONS]?: ComponentEditorOptions;
}
/**
* 可写的组件类型元数据（用于装饰器设置）
* Writable component type metadata (for decorator setting)
*/
export interface WritableComponentTypeMetadata {
[COMPONENT_TYPE_NAME]?: string;
[COMPONENT_DEPENDENCIES]?: string[];
[COMPONENT_EDITOR_OPTIONS]?: ComponentEditorOptions;
}
/**
* 获取组件构造函数的元数据
* Get metadata from component constructor
*
* @param componentType 组件构造函数
* @returns 元数据对象
*/
export function getComponentTypeMetadata(componentType: ComponentType): ComponentTypeMetadata {
return componentType as unknown as ComponentTypeMetadata;
}
/**
* 获取可写的组件构造函数元数据（用于装饰器）
* Get writable metadata from component constructor (for decorators)
*
* @param componentType 组件构造函数
* @returns 可写的元数据对象
*/
export function getWritableComponentTypeMetadata(componentType: ComponentType): WritableComponentTypeMetadata {
return componentType as unknown as WritableComponentTypeMetadata;
}
/**
* 检查组件是否使用了 @ECSComponent 装饰器
* Check if component has @ECSComponent decorator
@@ -69,7 +118,8 @@ export interface ComponentEditorOptions {
* @returns 是否有装饰器
*/
export function hasECSComponentDecorator(componentType: ComponentType): boolean {
return !!(componentType as any)[COMPONENT_TYPE_NAME];
const metadata = getComponentTypeMetadata(componentType);
return metadata[COMPONENT_TYPE_NAME] !== undefined;
}
/**
@@ -82,7 +132,8 @@ export function hasECSComponentDecorator(componentType: ComponentType): boolean
export function getComponentTypeName(componentType: ComponentType): string {
// 优先使用装饰器指定的名称
// Prefer decorator-specified name
const decoratorName = (componentType as any)[COMPONENT_TYPE_NAME];
const metadata = getComponentTypeMetadata(componentType);
const decoratorName = metadata[COMPONENT_TYPE_NAME];
if (decoratorName) {
return decoratorName;
}
@@ -111,7 +162,8 @@ export function getComponentInstanceTypeName(component: Component): string {
* @returns 依赖的组件名称列表
*/
export function getComponentDependencies(componentType: ComponentType): string[] | undefined {
return (componentType as any)[COMPONENT_DEPENDENCIES];
const metadata = getComponentTypeMetadata(componentType);
return metadata[COMPONENT_DEPENDENCIES];
}
/**
@@ -122,7 +174,8 @@ export function getComponentDependencies(componentType: ComponentType): string[]
* @returns 编辑器选项
*/
export function getComponentEditorOptions(componentType: ComponentType): ComponentEditorOptions | undefined {
return (componentType as any)[COMPONENT_EDITOR_OPTIONS];
const metadata = getComponentTypeMetadata(componentType);
return metadata[COMPONENT_EDITOR_OPTIONS];
}
/**

84
packages/core/src/ECS/Decorators/TypeDecorators.ts
View File

@@ -15,7 +15,9 @@ import {
COMPONENT_TYPE_NAME,
COMPONENT_DEPENDENCIES,
COMPONENT_EDITOR_OPTIONS,
type ComponentEditorOptions
getWritableComponentTypeMetadata,
type ComponentEditorOptions,
type ComponentType
} from '../Core/ComponentStorage/ComponentTypeUtils';
/**
@@ -24,6 +26,50 @@ import {
*/
export const SYSTEM_TYPE_NAME = Symbol('SystemTypeName');
/**
* 系统类型元数据接口
* System type metadata interface
*/
export interface SystemTypeMetadata {
readonly [SYSTEM_TYPE_NAME]?: string;
readonly __systemMetadata__?: SystemMetadata;
}
/**
* 可写的系统类型元数据
* Writable system type metadata
*/
interface WritableSystemTypeMetadata {
[SYSTEM_TYPE_NAME]?: string;
__systemMetadata__?: SystemMetadata;
}
/**
* 获取系统类型元数据
* Get system type metadata
*/
function getSystemTypeMetadata(systemType: SystemConstructor): SystemTypeMetadata {
return systemType as unknown as SystemTypeMetadata;
}
/**
* 获取可写的系统类型元数据
* Get writable system type metadata
*/
function getWritableSystemTypeMetadata(systemType: SystemConstructor): WritableSystemTypeMetadata {
return systemType as unknown as WritableSystemTypeMetadata;
}
/**
* 系统构造函数类型
* System constructor type
*
* 注意：构造函数参数使用 any[] 是必要的，因为系统可以有各种不同签名的构造函数
* Note: Constructor args use any[] because systems can have various constructor signatures
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
type SystemConstructor<T extends EntitySystem = EntitySystem> = new (...args: any[]) => T;
/**
* 组件装饰器配置选项
* Component decorator options
@@ -67,25 +113,29 @@ export interface ComponentOptions {
* ```
*/
export function ECSComponent(typeName: string, options?: ComponentOptions) {
return function <T extends new (...args: any[]) => Component>(target: T): T {
return function <T extends ComponentType<Component>>(target: T): T {
if (!typeName || typeof typeName !== 'string') {
throw new Error('ECSComponent装饰器必须提供有效的类型名称');
}
// 获取可写的元数据对象
// Get writable metadata object
const metadata = getWritableComponentTypeMetadata(target);
// 在构造函数上存储类型名称
// Store type name on constructor
(target as any)[COMPONENT_TYPE_NAME] = typeName;
metadata[COMPONENT_TYPE_NAME] = typeName;
// 存储依赖关系
// Store dependencies
if (options?.requires) {
(target as any)[COMPONENT_DEPENDENCIES] = options.requires;
metadata[COMPONENT_DEPENDENCIES] = options.requires;
}
// 存储编辑器选项
// Store editor options
if (options?.editor) {
(target as any)[COMPONENT_EDITOR_OPTIONS] = options.editor;
metadata[COMPONENT_EDITOR_OPTIONS] = options.editor;
}
// 自动注册到全局 ComponentRegistry，使组件可以通过名称查找
@@ -154,19 +204,23 @@ export interface SystemMetadata {
* ```
*/
export function ECSSystem(typeName: string, metadata?: SystemMetadata) {
return function <T extends new (...args: any[]) => EntitySystem>(target: T): T {
return function <T extends SystemConstructor>(target: T): T {
if (!typeName || typeof typeName !== 'string') {
throw new Error('ECSSystem装饰器必须提供有效的类型名称');
}
// 获取可写的元数据对象
// Get writable metadata object
const meta = getWritableSystemTypeMetadata(target);
// 在构造函数上存储类型名称
// Store type name on constructor
(target as any)[SYSTEM_TYPE_NAME] = typeName;
meta[SYSTEM_TYPE_NAME] = typeName;
// 存储元数据
// Store metadata
if (metadata) {
(target as any).__systemMetadata__ = metadata;
meta.__systemMetadata__ = metadata;
}
return target;
@@ -177,8 +231,9 @@ export function ECSSystem(typeName: string, metadata?: SystemMetadata) {
* 获取 System 的元数据
* Get System metadata
*/
export function getSystemMetadata(systemType: new (...args: any[]) => EntitySystem): SystemMetadata | undefined {
return (systemType as any).__systemMetadata__;
export function getSystemMetadata(systemType: SystemConstructor): SystemMetadata | undefined {
const meta = getSystemTypeMetadata(systemType);
return meta.__systemMetadata__;
}
/**
@@ -189,7 +244,7 @@ export function getSystemMetadata(systemType: new (...args: any[]) => EntitySyst
* @returns 系统元数据 | System metadata
*/
export function getSystemInstanceMetadata(system: EntitySystem): SystemMetadata | undefined {
return getSystemMetadata(system.constructor as new (...args: any[]) => EntitySystem);
return getSystemMetadata(system.constructor as SystemConstructor);
}
/**
@@ -200,9 +255,10 @@ export function getSystemInstanceMetadata(system: EntitySystem): SystemMetadata
* @returns 系统类型名称 | System type name
*/
export function getSystemTypeName<T extends EntitySystem>(
systemType: new (...args: any[]) => T
systemType: SystemConstructor<T>
): string {
const decoratorName = (systemType as any)[SYSTEM_TYPE_NAME];
const meta = getSystemTypeMetadata(systemType);
const decoratorName = meta[SYSTEM_TYPE_NAME];
if (decoratorName) {
return decoratorName;
}
@@ -217,5 +273,5 @@ export function getSystemTypeName<T extends EntitySystem>(
* @returns 系统类型名称 | System type name
*/
export function getSystemInstanceTypeName(system: EntitySystem): string {
return getSystemTypeName(system.constructor as new (...args: any[]) => EntitySystem);
return getSystemTypeName(system.constructor as SystemConstructor);
}