Feature/editor optimization (#251)
* refactor: 编辑器/运行时架构拆分与构建系统升级 * feat(core): 层级系统重构与UI变换矩阵修复 * refactor: 移除 ecs-components 聚合包并修复跨包组件查找问题 * fix(physics): 修复跨包组件类引用问题 * feat: 统一运行时架构与浏览器运行支持 * feat(asset): 实现浏览器运行时资产加载系统 * fix: 修复文档、CodeQL安全问题和CI类型检查错误 * fix: 修复文档、CodeQL安全问题和CI类型检查错误 * fix: 修复文档、CodeQL安全问题、CI类型检查和测试错误 * test: 补齐核心模块测试用例，修复CI构建配置 * fix: 修复测试用例中的类型错误和断言问题 * fix: 修复 turbo build:npm 任务的依赖顺序问题 * fix: 修复 CI 构建错误并优化构建性能
This commit is contained in:
YHH
GitHub
227
packages/engine-core/src/EnginePlugin.ts
Normal file
227
packages/engine-core/src/EnginePlugin.ts
Normal file
@@ -0,0 +1,227 @@
|
||||
/**
|
||||
* 插件系统核心类型定义
|
||||
* Plugin system core type definitions
|
||||
*
|
||||
* 这是插件类型的唯一定义源，editor-core 重新导出并扩展这些类型。
|
||||
* This is the single source of truth for plugin types. editor-core re-exports and extends them.
|
||||
*/
|
||||
|
||||
import type { ComponentRegistry as ComponentRegistryType, IScene, ServiceContainer } from '@esengine/ecs-framework';
|
||||
import { TransformComponent } from './TransformComponent';
|
||||
|
||||
// ============================================================================
|
||||
// 基础类型 | Basic Types
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 插件类别
|
||||
* Plugin category
|
||||
*/
|
||||
export type PluginCategory =
|
||||
| 'core' // 核心功能 | Core functionality
|
||||
| 'rendering' // 渲染相关 | Rendering
|
||||
| 'ui' // UI 系统 | UI System
|
||||
| 'ai' // AI/行为树 | AI/Behavior
|
||||
| 'physics' // 物理引擎 | Physics
|
||||
| 'audio' // 音频系统 | Audio
|
||||
| 'networking' // 网络功能 | Networking
|
||||
| 'tools' // 工具/编辑器扩展 | Tools/Editor extensions
|
||||
| 'scripting' // 脚本/蓝图 | Scripting/Blueprint
|
||||
| 'tilemap' // 瓦片地图 | Tilemap
|
||||
| 'content'; // 内容/资源 | Content/Assets
|
||||
|
||||
/**
|
||||
* 加载阶段 - 控制插件模块的加载顺序
|
||||
* Loading phase - controls the loading order of plugin modules
|
||||
*/
|
||||
export type LoadingPhase =
|
||||
| 'earliest' // 最早加载（核心模块） | Earliest (core modules)
|
||||
| 'preDefault' // 默认之前 | Before default
|
||||
| 'default' // 默认阶段 | Default phase
|
||||
| 'postDefault' // 默认之后 | After default
|
||||
| 'postEngine'; // 引擎初始化后 | After engine init
|
||||
|
||||
/**
|
||||
* 模块类型
|
||||
* Module type
|
||||
*/
|
||||
export type ModuleType = 'runtime' | 'editor';
|
||||
|
||||
/**
|
||||
* 模块描述符
|
||||
* Module descriptor
|
||||
*/
|
||||
export interface ModuleDescriptor {
|
||||
/** 模块名称 | Module name */
|
||||
name: string;
|
||||
/** 模块类型 | Module type */
|
||||
type: ModuleType;
|
||||
/** 加载阶段 | Loading phase */
|
||||
loadingPhase?: LoadingPhase;
|
||||
}
|
||||
|
||||
/**
|
||||
* 插件依赖
|
||||
* Plugin dependency
|
||||
*/
|
||||
export interface PluginDependency {
|
||||
/** 依赖的插件ID | Dependent plugin ID */
|
||||
id: string;
|
||||
/** 版本要求 | Version requirement */
|
||||
version?: string;
|
||||
/** 是否可选 | Optional */
|
||||
optional?: boolean;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 插件描述符 | Plugin Descriptor
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 插件描述符
|
||||
* Plugin descriptor
|
||||
*
|
||||
* 所有字段都是可选的，PluginManager 会填充默认值。
|
||||
* All fields are optional, PluginManager will fill in defaults.
|
||||
*/
|
||||
export interface PluginDescriptor {
|
||||
/** 插件唯一标识符 | Unique plugin ID */
|
||||
id: string;
|
||||
/** 显示名称 | Display name */
|
||||
name: string;
|
||||
/** 版本号 | Version */
|
||||
version: string;
|
||||
/** 描述 | Description */
|
||||
description?: string;
|
||||
/** 插件类别 | Plugin category */
|
||||
category?: PluginCategory;
|
||||
/** 标签（用于搜索） | Tags (for search) */
|
||||
tags?: string[];
|
||||
/** 图标（Lucide 图标名） | Icon (Lucide icon name) */
|
||||
icon?: string;
|
||||
/** 是否默认启用 | Enabled by default */
|
||||
enabledByDefault?: boolean;
|
||||
/** 是否可以包含内容资产 | Can contain content assets */
|
||||
canContainContent?: boolean;
|
||||
/** 是否为引擎内置插件 | Is engine built-in plugin */
|
||||
isEnginePlugin?: boolean;
|
||||
/** 是否为核心插件（不可禁用） | Is core plugin (cannot be disabled) */
|
||||
isCore?: boolean;
|
||||
/** 模块列表 | Module list */
|
||||
modules?: ModuleDescriptor[];
|
||||
/** 依赖列表 | Dependency list */
|
||||
dependencies?: PluginDependency[];
|
||||
/** 平台要求 | Platform requirements */
|
||||
platforms?: ('web' | 'desktop' | 'mobile')[];
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 系统上下文 | System Context
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 系统创建上下文
|
||||
* System creation context
|
||||
*/
|
||||
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;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 运行时模块 | Runtime Module
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 运行时模块接口
|
||||
* Runtime module interface
|
||||
*/
|
||||
export interface IRuntimeModule {
|
||||
/**
|
||||
* 注册组件到 ComponentRegistry
|
||||
* Register components to ComponentRegistry
|
||||
*/
|
||||
registerComponents?(registry: typeof ComponentRegistryType): void;
|
||||
|
||||
/**
|
||||
* 注册服务到 ServiceContainer
|
||||
* Register services to ServiceContainer
|
||||
*/
|
||||
registerServices?(services: ServiceContainer): void;
|
||||
|
||||
/**
|
||||
* 为场景创建系统
|
||||
* Create systems for scene
|
||||
*/
|
||||
createSystems?(scene: IScene, context: SystemContext): void;
|
||||
|
||||
/**
|
||||
* 所有系统创建完成后调用
|
||||
* Called after all systems are created
|
||||
*/
|
||||
onSystemsCreated?(scene: IScene, context: SystemContext): void;
|
||||
|
||||
/**
|
||||
* 模块初始化完成回调
|
||||
* Module initialization complete callback
|
||||
*/
|
||||
onInitialize?(): Promise<void>;
|
||||
|
||||
/**
|
||||
* 模块销毁回调
|
||||
* Module destroy callback
|
||||
*/
|
||||
onDestroy?(): void;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 插件接口 | Plugin Interface
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 插件接口
|
||||
* Plugin interface
|
||||
*
|
||||
* 这是所有插件包导出的统一类型。
|
||||
* This is the unified type that all plugin packages export.
|
||||
*/
|
||||
export interface IPlugin {
|
||||
/** 插件描述符 | Plugin descriptor */
|
||||
readonly descriptor: PluginDescriptor;
|
||||
/** 运行时模块（可选） | Runtime module (optional) */
|
||||
readonly runtimeModule?: IRuntimeModule;
|
||||
/** 编辑器模块（可选，类型为 any 以避免循环依赖） | Editor module (optional, typed as any to avoid circular deps) */
|
||||
readonly editorModule?: any;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Engine Core 插件 | Engine Core Plugin
|
||||
// ============================================================================
|
||||
|
||||
class EngineRuntimeModule implements IRuntimeModule {
|
||||
registerComponents(registry: typeof ComponentRegistryType): void {
|
||||
registry.register(TransformComponent);
|
||||
}
|
||||
}
|
||||
|
||||
const descriptor: PluginDescriptor = {
|
||||
id: '@esengine/engine-core',
|
||||
name: 'Engine Core',
|
||||
version: '1.0.0',
|
||||
description: 'Transform 等核心组件',
|
||||
category: 'core',
|
||||
enabledByDefault: true,
|
||||
isEnginePlugin: true,
|
||||
isCore: true
|
||||
};
|
||||
|
||||
export const EnginePlugin: IPlugin = {
|
||||
descriptor,
|
||||
runtimeModule: new EngineRuntimeModule()
|
||||
};
|
||||
2
packages/engine-core/src/HierarchyComponent.ts
Normal file
2
packages/engine-core/src/HierarchyComponent.ts
Normal file
@@ -0,0 +1,2 @@
|
||||
// Re-export from ecs-framework
|
||||
export { HierarchyComponent } from '@esengine/ecs-framework';
|
||||
2
packages/engine-core/src/HierarchySystem.ts
Normal file
2
packages/engine-core/src/HierarchySystem.ts
Normal file
@@ -0,0 +1,2 @@
|
||||
// Re-export from ecs-framework
|
||||
export { HierarchySystem } from '@esengine/ecs-framework';
|
||||
110
packages/engine-core/src/TransformComponent.ts
Normal file
110
packages/engine-core/src/TransformComponent.ts
Normal file
@@ -0,0 +1,110 @@
|
||||
import { Component, ECSComponent, Serializable, Serialize, Property } from '@esengine/ecs-framework';
|
||||
|
||||
export interface Vector3 {
|
||||
x: number;
|
||||
y: number;
|
||||
z: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 3x3 矩阵（用于 2D 变换：旋转 + 缩放）
|
||||
* 实际存储为 [a, b, c, d, tx, ty] 形式的仿射变换
|
||||
*/
|
||||
export interface Matrix2D {
|
||||
a: number; // scaleX * cos(rotation)
|
||||
b: number; // scaleX * sin(rotation)
|
||||
c: number; // scaleY * -sin(rotation)
|
||||
d: number; // scaleY * cos(rotation)
|
||||
tx: number; // translateX
|
||||
ty: number; // translateY
|
||||
}
|
||||
|
||||
@ECSComponent('Transform')
|
||||
@Serializable({ version: 1, typeId: 'Transform' })
|
||||
export class TransformComponent extends Component {
|
||||
@Serialize()
|
||||
@Property({ type: 'vector3', label: 'Position' })
|
||||
position: Vector3 = { x: 0, y: 0, z: 0 };
|
||||
|
||||
/** 欧拉角，单位：度 */
|
||||
@Serialize()
|
||||
@Property({ type: 'vector3', label: 'Rotation' })
|
||||
rotation: Vector3 = { x: 0, y: 0, z: 0 };
|
||||
|
||||
@Serialize()
|
||||
@Property({ type: 'vector3', label: 'Scale' })
|
||||
scale: Vector3 = { x: 1, y: 1, z: 1 };
|
||||
|
||||
// ===== 世界变换（由 TransformSystem 计算）=====
|
||||
|
||||
/** 世界位置（只读，由 TransformSystem 计算） */
|
||||
worldPosition: Vector3 = { x: 0, y: 0, z: 0 };
|
||||
|
||||
/** 世界旋转（只读，由 TransformSystem 计算） */
|
||||
worldRotation: Vector3 = { x: 0, y: 0, z: 0 };
|
||||
|
||||
/** 世界缩放（只读，由 TransformSystem 计算） */
|
||||
worldScale: Vector3 = { x: 1, y: 1, z: 1 };
|
||||
|
||||
/** 本地到世界的 2D 变换矩阵（只读，由 TransformSystem 计算） */
|
||||
localToWorldMatrix: Matrix2D = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
|
||||
|
||||
/** 变换是否需要更新 */
|
||||
bDirty: boolean = true;
|
||||
|
||||
constructor(x: number = 0, y: number = 0, z: number = 0) {
|
||||
super();
|
||||
this.position = { x, y, z };
|
||||
// 初始化世界变换为本地变换值（在 TransformSystem 更新前使用）
|
||||
this.worldPosition = { x, y, z };
|
||||
}
|
||||
|
||||
setPosition(x: number, y: number, z: number = 0): this {
|
||||
this.position = { x, y, z };
|
||||
this.bDirty = true;
|
||||
return this;
|
||||
}
|
||||
|
||||
setRotation(x: number, y: number, z: number): this {
|
||||
this.rotation = { x, y, z };
|
||||
this.bDirty = true;
|
||||
return this;
|
||||
}
|
||||
|
||||
setScale(x: number, y: number, z: number = 1): this {
|
||||
this.scale = { x, y, z };
|
||||
this.bDirty = true;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 将本地坐标转换为世界坐标
|
||||
*/
|
||||
localToWorld(localX: number, localY: number): { x: number; y: number } {
|
||||
const m = this.localToWorldMatrix;
|
||||
return {
|
||||
x: m.a * localX + m.c * localY + m.tx,
|
||||
y: m.b * localX + m.d * localY + m.ty
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 将世界坐标转换为本地坐标
|
||||
*/
|
||||
worldToLocal(worldX: number, worldY: number): { x: number; y: number } {
|
||||
const m = this.localToWorldMatrix;
|
||||
const det = m.a * m.d - m.b * m.c;
|
||||
if (Math.abs(det) < 1e-10) {
|
||||
return { x: 0, y: 0 };
|
||||
}
|
||||
|
||||
const invDet = 1 / det;
|
||||
const dx = worldX - m.tx;
|
||||
const dy = worldY - m.ty;
|
||||
|
||||
return {
|
||||
x: (m.d * dx - m.c * dy) * invDet,
|
||||
y: (-m.b * dx + m.a * dy) * invDet
|
||||
};
|
||||
}
|
||||
}
|
||||
145
packages/engine-core/src/TransformSystem.ts
Normal file
145
packages/engine-core/src/TransformSystem.ts
Normal file
@@ -0,0 +1,145 @@
|
||||
import { EntitySystem, Matcher, Entity, ECSSystem, HierarchyComponent } from '@esengine/ecs-framework';
|
||||
import { TransformComponent, Matrix2D } from './TransformComponent';
|
||||
|
||||
const DEG_TO_RAD = Math.PI / 180;
|
||||
|
||||
/**
|
||||
* 变换系统
|
||||
* Transform System - Calculates world transforms based on hierarchy
|
||||
*
|
||||
* 根据实体层级关系计算世界变换矩阵。
|
||||
* 子实体的世界变换 = 父实体世界变换 * 子实体本地变换
|
||||
*/
|
||||
@ECSSystem('Transform', { updateOrder: -100 })
|
||||
export class TransformSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.empty().all(TransformComponent));
|
||||
}
|
||||
|
||||
protected override process(entities: readonly Entity[]): void {
|
||||
// 获取所有根实体（没有父级或父级没有 TransformComponent）
|
||||
const rootEntities = entities.filter(e => {
|
||||
const hierarchy = e.getComponent(HierarchyComponent);
|
||||
if (!hierarchy || hierarchy.parentId === null) {
|
||||
return true;
|
||||
}
|
||||
const parent = this.scene?.findEntityById(hierarchy.parentId);
|
||||
return !parent || !parent.hasComponent(TransformComponent);
|
||||
});
|
||||
|
||||
// 从根实体开始递归计算世界变换
|
||||
for (const entity of rootEntities) {
|
||||
this.updateWorldTransform(entity, null);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 递归更新实体及其子实体的世界变换
|
||||
*/
|
||||
private updateWorldTransform(entity: Entity, parentMatrix: Matrix2D | null): void {
|
||||
const transform = entity.getComponent(TransformComponent);
|
||||
if (!transform) return;
|
||||
|
||||
// 计算本地变换矩阵
|
||||
const localMatrix = this.calculateLocalMatrix(transform);
|
||||
|
||||
// 计算世界变换矩阵
|
||||
if (parentMatrix) {
|
||||
// 世界矩阵 = 父矩阵 * 本地矩阵
|
||||
transform.localToWorldMatrix = this.multiplyMatrices(parentMatrix, localMatrix);
|
||||
} else {
|
||||
// 没有父级，本地矩阵就是世界矩阵
|
||||
transform.localToWorldMatrix = localMatrix;
|
||||
}
|
||||
|
||||
// 从世界矩阵提取世界位置、旋转、缩放
|
||||
this.decomposeMatrix(transform);
|
||||
|
||||
transform.bDirty = false;
|
||||
|
||||
// 递归处理子实体
|
||||
const hierarchy = entity.getComponent(HierarchyComponent);
|
||||
if (hierarchy && hierarchy.childIds.length > 0) {
|
||||
for (const childId of hierarchy.childIds) {
|
||||
const child = this.scene?.findEntityById(childId);
|
||||
if (child) {
|
||||
this.updateWorldTransform(child, transform.localToWorldMatrix);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 计算本地变换矩阵
|
||||
*/
|
||||
private calculateLocalMatrix(transform: TransformComponent): Matrix2D {
|
||||
const { position, rotation, scale } = transform;
|
||||
|
||||
// 只使用 z 轴旋转（2D）
|
||||
const rad = rotation.z * DEG_TO_RAD;
|
||||
const cos = Math.cos(rad);
|
||||
const sin = Math.sin(rad);
|
||||
|
||||
// 构建仿射变换矩阵: Scale -> Rotate -> Translate
|
||||
// [a c tx] [sx 0 0] [cos -sin 0] [1 0 tx]
|
||||
// [b d ty] = [0 sy 0] * [sin cos 0] * [0 1 ty]
|
||||
// [0 0 1] [0 0 1] [0 0 1] [0 0 1]
|
||||
|
||||
return {
|
||||
a: scale.x * cos,
|
||||
b: scale.x * sin,
|
||||
c: scale.y * -sin,
|
||||
d: scale.y * cos,
|
||||
tx: position.x,
|
||||
ty: position.y
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 矩阵乘法: result = a * b
|
||||
*/
|
||||
private multiplyMatrices(a: Matrix2D, b: Matrix2D): Matrix2D {
|
||||
return {
|
||||
a: a.a * b.a + a.c * b.b,
|
||||
b: a.b * b.a + a.d * b.b,
|
||||
c: a.a * b.c + a.c * b.d,
|
||||
d: a.b * b.c + a.d * b.d,
|
||||
tx: a.a * b.tx + a.c * b.ty + a.tx,
|
||||
ty: a.b * b.tx + a.d * b.ty + a.ty
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 从世界矩阵分解出位置、旋转、缩放
|
||||
*/
|
||||
private decomposeMatrix(transform: TransformComponent): void {
|
||||
const m = transform.localToWorldMatrix;
|
||||
|
||||
// 位置直接从矩阵获取
|
||||
transform.worldPosition.x = m.tx;
|
||||
transform.worldPosition.y = m.ty;
|
||||
transform.worldPosition.z = transform.position.z;
|
||||
|
||||
// 计算缩放
|
||||
const scaleX = Math.sqrt(m.a * m.a + m.b * m.b);
|
||||
const scaleY = Math.sqrt(m.c * m.c + m.d * m.d);
|
||||
|
||||
// 检测负缩放（通过行列式符号）
|
||||
const det = m.a * m.d - m.b * m.c;
|
||||
const sign = det < 0 ? -1 : 1;
|
||||
|
||||
transform.worldScale.x = scaleX;
|
||||
transform.worldScale.y = scaleY * sign;
|
||||
transform.worldScale.z = transform.scale.z;
|
||||
|
||||
// 计算旋转（从归一化的矩阵）
|
||||
if (scaleX > 1e-10) {
|
||||
const rotation = Math.atan2(m.b / scaleX, m.a / scaleX);
|
||||
transform.worldRotation.z = rotation / DEG_TO_RAD;
|
||||
} else {
|
||||
transform.worldRotation.z = 0;
|
||||
}
|
||||
transform.worldRotation.x = transform.rotation.x;
|
||||
transform.worldRotation.y = transform.rotation.y;
|
||||
}
|
||||
}
|
||||
17
packages/engine-core/src/index.ts
Normal file
17
packages/engine-core/src/index.ts
Normal file
@@ -0,0 +1,17 @@
|
||||
export { TransformComponent, type Vector3, type Matrix2D } from './TransformComponent';
|
||||
export { TransformSystem } from './TransformSystem';
|
||||
export { HierarchyComponent } from './HierarchyComponent';
|
||||
export { HierarchySystem } from './HierarchySystem';
|
||||
export {
|
||||
EnginePlugin,
|
||||
// 类型导出
|
||||
type PluginCategory,
|
||||
type LoadingPhase,
|
||||
type ModuleType,
|
||||
type ModuleDescriptor,
|
||||
type PluginDependency,
|
||||
type PluginDescriptor,
|
||||
type SystemContext,
|
||||
type IRuntimeModule,
|
||||
type IPlugin
|
||||
} from './EnginePlugin';
|
||||
Reference in New Issue
Block a user