feat: 预制体系统与架构改进 (#303)

* feat(prefab): 实现预制体系统和编辑器 UX 改进

## 预制体系统
- 新增 PrefabSerializer: 预制体序列化/反序列化
- 新增 PrefabInstanceComponent: 追踪预制体实例来源和修改
- 新增 PrefabService: 预制体核心服务
- 新增 PrefabLoader: 预制体资产加载器
- 新增预制体命令: Create/Instantiate/Apply/Revert/BreakLink

## 预制体编辑模式
- 支持双击 .prefab 文件进入编辑模式
- 预制体编辑模式工具栏 (保存/退出)
- 预制体实例指示器和操作菜单

## 编辑器 UX 改进
- SceneHierarchy 快捷键: F2 重命名, Ctrl+D 复制, ↑↓ 导航
- 支持双击实体名称内联编辑
- 删除实体时显示子节点数量警告
- 右键菜单添加重命名/复制选项及快捷键提示
- 布局持久化和重置功能

## Bug 修复
- 修复 editor-runtime 组件类重复导致的 TransformComponent 不识别问题
- 修复 .prefab-name 样式覆盖导致预制体工具栏文字不可见
- 修复 Inspector 资源字段高度不正确问题

* feat(editor): 改进编辑器 UX 交互体验

- ContentBrowser: 加载动画 spinner、搜索高亮、改进空状态设计
- SceneHierarchy: 选中项自动滚动到视图、搜索清除按钮
- PropertyInspector: 输入框本地状态管理、Enter/Escape 键处理
- EntityInspector: 组件折叠状态持久化、属性搜索清除按钮
- Viewport: 变换操作实时数值显示
- 国际化: 添加相关文本 (en/zh)

* fix(build): 修复 Web 构建资产加载和编辑器 UX 改进

构建系统修复:
- 修复 asset-catalog.json 字段名不匹配 (entries vs assets)
- 修复 BrowserFileSystemService 支持两种目录格式
- 修复 bundle 策略检测逻辑 (空对象判断)
- 修复 module.json 中 assetExtensions 声明和类型推断

行为树修复:
- 修复 BehaviorTreeExecutionSystem 使用 loadAsset 替代 loadAssetByPath
- 修复 BehaviorTreeAssetType 常量与 module.json 类型名一致 (behavior-tree)

编辑器 UX 改进:
- 构建完成对话框添加"打开文件夹"按钮
- 构建完成对话框样式优化 (圆形图标背景、按钮布局)
- SceneHierarchy 响应式布局 (窄窗口自动隐藏 Type 列)
- SceneHierarchy 隐藏滚动条

错误追踪:
- 添加全局错误处理器写入日志文件 (%TEMP%/esengine-editor-crash.log)
- 添加 append_to_log Tauri 命令

* feat(render): 修复 UI 渲染和点击特效系统

## UI 渲染修复
- 修复 GUID 验证 bug,使用统一的 isValidGUID() 函数
- 修复 UI 渲染顺序随机问题,Rust 端使用 IndexMap 替代 HashMap
- Web 运行时添加 assetPathResolver 支持 GUID 解析
- UIInteractableComponent.blockEvents 默认值改为 false

## 点击特效系统
- 新增 ClickFxComponent 和 ClickFxSystem
- 支持在点击位置播放粒子效果
- 支持多种触发模式和粒子轮换

## Camera 系统重构
- CameraSystem 从 ecs-engine-bindgen 移至 camera 包
- 新增 CameraManager 统一管理相机

## 编辑器改进
- 改进属性面板 UI 交互
- 粒子编辑器面板优化
- Transform 命令系统

* feat(render): 实现 Sorting Layer 系统和 Overlay 渲染层

- 新增 SortingLayerManager 管理排序层级 (Background, Default, Foreground, UI, Overlay)
- 实现 ISortable 接口,统一 Sprite、UI、Particle 的排序属性
- 修复粒子 Overlay 层被 UI 遮挡问题:添加独立的 Overlay Pass 在 UI 之后渲染
- 更新粒子资产格式:从 sortingOrder 改为 sortingLayer + orderInLayer
- 更新粒子编辑器面板支持新的排序属性
- 优化 UI 渲染系统使用新的排序层级

* feat(ci): 集成 SignPath 代码签名服务

- 添加 SignPath 自动签名工作流(Windows)
- 配置 release-editor.yml 支持代码签名
- 将构建改为草稿模式,等待签名完成后发布
- 添加证书文件到 .gitignore 防止泄露

* fix(asset): 修复 Web 构建资产路径解析和全局单例移除

## 资产路径修复
- 修复 Tauri 本地服务器 `/asset?path=...` 路径解析,正确与 root 目录连接
- BrowserPathResolver 支持两种模式:
  - 'proxy': 使用 /asset?path=... 格式(编辑器 Run in Browser)
  - 'direct': 使用直接路径 /assets/path.png(独立 Web 构建)
- BrowserRuntime 使用 'direct' 模式,无需 Tauri 代理

## 架构改进 - 移除全局单例
- 移除 globalAssetManager 导出,改用 AssetManagerToken 依赖注入
- 移除 globalPathResolver 导出,改用 PathResolutionService
- 移除 globalPathResolutionService 导出
- ParticleUpdateSystem/ClickFxSystem 通过 setAssetManager() 注入依赖
- EngineService 使用 new AssetManager() 替代全局实例

## 新增服务
- PathResolutionService: 统一路径解析接口
- RuntimeModeService: 运行时模式查询服务
- SerializationContext: EntityRef 序列化上下文

## 其他改进
- 完善 ServiceToken 注释说明本地定义的意图
- 导出 BrowserPathResolveMode 类型

* fix(build): 添加 world-streaming composite 设置修复类型检查

* fix(build): 移除 world-streaming 引用避免 composite 冲突

* fix(build): 将 const enum 改为 enum 兼容 isolatedModules

* fix(build): 添加缺失的 IAssetManager 导入
This commit is contained in:
YHH
2025-12-13 19:44:08 +08:00
committed by GitHub
parent a716d8006c
commit beaa1d09de
258 changed files with 17725 additions and 3030 deletions

View File

@@ -1,6 +1,7 @@
{
"id": "camera",
"name": "@esengine/camera",
"globalKey": "camera",
"displayName": "Camera",
"description": "Camera and viewport management | 相机和视口管理",
"version": "1.0.0",

View File

@@ -29,6 +29,7 @@
},
"devDependencies": {
"@esengine/ecs-framework": "workspace:*",
"@esengine/ecs-framework-math": "workspace:*",
"@esengine/engine-core": "workspace:*",
"@esengine/build-config": "workspace:*",
"rimraf": "^5.0.5",

View File

@@ -0,0 +1,320 @@
/**
* 相机管理器 - 提供相机相关的全局服务
* Camera Manager - Provides global camera services
*
* 主要功能:
* - 管理主相机
* - 屏幕坐标与世界坐标转换
*
* Main features:
* - Manage main camera
* - Screen to world coordinate conversion
*/
import type { Entity, IScene } from '@esengine/ecs-framework';
import type { IVector2 } from '@esengine/ecs-framework-math';
import { TransformComponent } from '@esengine/engine-core';
import { CameraComponent, ECameraProjection } from './CameraComponent';
/**
* 相机管理器接口
* Camera manager interface
*/
export interface ICameraManager {
/**
* 设置场景引用
* Set scene reference
*/
setScene(scene: IScene | null): void;
/**
* 设置视口尺寸
* Set viewport size
*/
setViewportSize(width: number, height: number): void;
/**
* 获取主相机实体
* Get main camera entity
*/
getMainCamera(): Entity | null;
/**
* 获取主相机组件
* Get main camera component
*/
getMainCameraComponent(): CameraComponent | null;
/**
* 屏幕坐标转世界坐标
* Convert screen coordinates to world coordinates
*
* @param screenX 屏幕 X 坐标 | Screen X coordinate
* @param screenY 屏幕 Y 坐标 | Screen Y coordinate
* @returns 世界坐标 | World coordinates
*/
screenToWorld(screenX: number, screenY: number): IVector2;
/**
* 世界坐标转屏幕坐标
* Convert world coordinates to screen coordinates
*
* @param worldX 世界 X 坐标 | World X coordinate
* @param worldY 世界 Y 坐标 | World Y coordinate
* @returns 屏幕坐标 | Screen coordinates
*/
worldToScreen(worldX: number, worldY: number): IVector2;
}
/**
* 相机管理器实现
* Camera manager implementation
*
* @example
* ```typescript
* // 获取全局实例
* import { CameraManager } from '@esengine/camera';
*
* // 设置场景和视口
* CameraManager.setScene(scene);
* CameraManager.setViewportSize(800, 600);
*
* // 屏幕坐标转世界坐标
* const worldPos = CameraManager.screenToWorld(mouseX, mouseY);
* console.log(`World position: ${worldPos.x}, ${worldPos.y}`);
* ```
*/
export class CameraManagerImpl implements ICameraManager {
private _scene: IScene | null = null;
private _viewportWidth: number = 800;
private _viewportHeight: number = 600;
private _mainCameraEntity: Entity | null = null;
private _mainCameraEntityDirty: boolean = true;
/**
* 设置场景引用
* Set scene reference
*/
setScene(scene: IScene | null): void {
this._scene = scene;
this._mainCameraEntityDirty = true;
this._mainCameraEntity = null;
}
/**
* 设置视口尺寸
* Set viewport size
*/
setViewportSize(width: number, height: number): void {
this._viewportWidth = Math.max(1, width);
this._viewportHeight = Math.max(1, height);
}
/**
* 获取视口宽度
* Get viewport width
*/
get viewportWidth(): number {
return this._viewportWidth;
}
/**
* 获取视口高度
* Get viewport height
*/
get viewportHeight(): number {
return this._viewportHeight;
}
/**
* 获取视口宽高比
* Get viewport aspect ratio
*/
get aspectRatio(): number {
return this._viewportWidth / this._viewportHeight;
}
/**
* 标记主相机需要重新查找
* Mark main camera as dirty (needs re-lookup)
*/
invalidateMainCamera(): void {
this._mainCameraEntityDirty = true;
}
/**
* 获取主相机实体
* Get main camera entity
*/
getMainCamera(): Entity | null {
if (this._mainCameraEntityDirty || !this._mainCameraEntity) {
this._mainCameraEntity = this._findMainCamera();
this._mainCameraEntityDirty = false;
}
return this._mainCameraEntity;
}
/**
* 获取主相机组件
* Get main camera component
*/
getMainCameraComponent(): CameraComponent | null {
const entity = this.getMainCamera();
return entity?.getComponent(CameraComponent) ?? null;
}
/**
* 查找主相机depth 最小的相机)
* Find main camera (camera with lowest depth)
*/
private _findMainCamera(): Entity | null {
if (!this._scene) return null;
let mainCamera: Entity | null = null;
let lowestDepth = Infinity;
// 使用 entities.buffer 遍历实体列表
// Use entities.buffer to iterate entity list
const entities = this._scene.entities.buffer;
for (let i = 0; i < entities.length; i++) {
const entity = entities[i];
if (!entity.enabled) continue;
const camera = entity.getComponent(CameraComponent);
if (camera && camera.depth < lowestDepth) {
lowestDepth = camera.depth;
mainCamera = entity;
}
}
return mainCamera;
}
/**
* 屏幕坐标转世界坐标
* Convert screen coordinates to world coordinates
*
* 对于正交相机:
* - 屏幕坐标 (0, 0) 在左上角
* - orthographicSize 是可见区域的半高度
*
* For orthographic camera:
* - Screen coordinates (0, 0) at top-left
* - orthographicSize is half-height of visible area
*/
screenToWorld(screenX: number, screenY: number): IVector2 {
const camera = this.getMainCameraComponent();
const cameraEntity = this.getMainCamera();
if (!camera || !cameraEntity) {
// 没有相机时,返回简单的偏移 | No camera, return simple offset
return {
x: screenX - this._viewportWidth / 2,
y: screenY - this._viewportHeight / 2
};
}
// 获取相机位置 | Get camera position
const transform = cameraEntity.getComponent(TransformComponent);
const cameraX = transform?.worldPosition.x ?? 0;
const cameraY = transform?.worldPosition.y ?? 0;
if (camera.projection === ECameraProjection.Orthographic) {
return this._screenToWorldOrthographic(screenX, screenY, camera, cameraX, cameraY);
} else {
// 透视相机暂不支持,返回正交结果
// Perspective camera not supported yet, return orthographic result
return this._screenToWorldOrthographic(screenX, screenY, camera, cameraX, cameraY);
}
}
/**
* 正交相机的屏幕到世界转换
* Screen to world conversion for orthographic camera
*/
private _screenToWorldOrthographic(
screenX: number,
screenY: number,
camera: CameraComponent,
cameraX: number,
cameraY: number
): IVector2 {
const orthoSize = camera.orthographicSize;
const aspect = this.aspectRatio;
// 归一化设备坐标 (NDC) [-1, 1]
// Normalized Device Coordinates (NDC) [-1, 1]
const ndcX = (screenX / this._viewportWidth) * 2 - 1;
const ndcY = 1 - (screenY / this._viewportHeight) * 2; // Y 轴翻转 | Flip Y axis
// 世界坐标 | World coordinates
const worldX = cameraX + ndcX * orthoSize * aspect;
const worldY = cameraY + ndcY * orthoSize;
return { x: worldX, y: worldY };
}
/**
* 世界坐标转屏幕坐标
* Convert world coordinates to screen coordinates
*/
worldToScreen(worldX: number, worldY: number): IVector2 {
const camera = this.getMainCameraComponent();
const cameraEntity = this.getMainCamera();
if (!camera || !cameraEntity) {
// 没有相机时,返回简单的偏移 | No camera, return simple offset
return {
x: worldX + this._viewportWidth / 2,
y: worldY + this._viewportHeight / 2
};
}
// 获取相机位置 | Get camera position
const transform = cameraEntity.getComponent(TransformComponent);
const cameraX = transform?.worldPosition.x ?? 0;
const cameraY = transform?.worldPosition.y ?? 0;
if (camera.projection === ECameraProjection.Orthographic) {
return this._worldToScreenOrthographic(worldX, worldY, camera, cameraX, cameraY);
} else {
// 透视相机暂不支持 | Perspective camera not supported yet
return this._worldToScreenOrthographic(worldX, worldY, camera, cameraX, cameraY);
}
}
/**
* 正交相机的世界到屏幕转换
* World to screen conversion for orthographic camera
*/
private _worldToScreenOrthographic(
worldX: number,
worldY: number,
camera: CameraComponent,
cameraX: number,
cameraY: number
): IVector2 {
const orthoSize = camera.orthographicSize;
const aspect = this.aspectRatio;
// 相对于相机的偏移 | Offset relative to camera
const offsetX = worldX - cameraX;
const offsetY = worldY - cameraY;
// NDC 坐标 | NDC coordinates
const ndcX = offsetX / (orthoSize * aspect);
const ndcY = offsetY / orthoSize;
// 屏幕坐标 | Screen coordinates
const screenX = (ndcX + 1) * 0.5 * this._viewportWidth;
const screenY = (1 - ndcY) * 0.5 * this._viewportHeight; // Y 轴翻转 | Flip Y axis
return { x: screenX, y: screenY };
}
}
/**
* 全局相机管理器实例
* Global camera manager instance
*/
export const CameraManager = new CameraManagerImpl();

View File

@@ -1,11 +1,26 @@
import type { ComponentRegistry as ComponentRegistryType } from '@esengine/ecs-framework';
import type { IRuntimeModule, IPlugin, ModuleManifest } from '@esengine/engine-core';
import type { ComponentRegistry as ComponentRegistryType, IScene } from '@esengine/ecs-framework';
import type { IRuntimeModule, IRuntimePlugin, ModuleManifest, SystemContext } from '@esengine/engine-core';
import { EngineBridgeToken } from '@esengine/engine-core';
import { CameraComponent } from './CameraComponent';
import { CameraSystem } from './CameraSystem';
class CameraRuntimeModule implements IRuntimeModule {
registerComponents(registry: typeof ComponentRegistryType): void {
registry.register(CameraComponent);
}
createSystems(scene: IScene, context: SystemContext): void {
// 从服务注册表获取 EngineBridge | Get EngineBridge from service registry
const bridge = context.services.get(EngineBridgeToken);
if (!bridge) {
console.warn('[CameraPlugin] EngineBridge not found, CameraSystem will not be created');
return;
}
// 创建并添加 CameraSystem | Create and add CameraSystem
const cameraSystem = new CameraSystem(bridge);
scene.addSystem(cameraSystem);
}
}
const manifest: ModuleManifest = {
@@ -22,7 +37,7 @@ const manifest: ModuleManifest = {
exports: { components: ['CameraComponent'] }
};
export const CameraPlugin: IPlugin = {
export const CameraPlugin: IRuntimePlugin = {
manifest,
runtimeModule: new CameraRuntimeModule()
};

View File

@@ -0,0 +1,52 @@
/**
* Camera System
* 相机系统
*/
import { EntitySystem, Matcher, Entity, ECSSystem } from '@esengine/ecs-framework';
import type { IEngineBridge } from '@esengine/engine-core';
import { CameraComponent } from './CameraComponent';
@ECSSystem('Camera', { updateOrder: -100 })
export class CameraSystem extends EntitySystem {
private bridge: IEngineBridge;
private lastAppliedCameraId: number | null = null;
constructor(bridge: IEngineBridge) {
// Match entities with CameraComponent
super(Matcher.empty().all(CameraComponent));
this.bridge = bridge;
}
protected override onBegin(): void {
// Will process cameras in process()
}
protected override process(entities: readonly Entity[]): void {
// Use first enabled camera
for (const entity of entities) {
if (!entity.enabled) continue;
const camera = entity.getComponent(CameraComponent);
if (!camera) continue;
// Only apply if camera changed
if (this.lastAppliedCameraId !== entity.id) {
this.applyCamera(camera);
this.lastAppliedCameraId = entity.id;
}
// Only use first active camera
break;
}
}
private applyCamera(camera: CameraComponent): void {
// Apply background color
const bgColor = camera.backgroundColor || '#000000';
const r = parseInt(bgColor.slice(1, 3), 16) / 255;
const g = parseInt(bgColor.slice(3, 5), 16) / 255;
const b = parseInt(bgColor.slice(5, 7), 16) / 255;
this.bridge.setClearColor(r, g, b, 1.0);
}
}

View File

@@ -1,6 +1,8 @@
export { CameraComponent, ECameraProjection, CameraProjection } from './CameraComponent';
export { CameraSystem } from './CameraSystem';
export { CameraPlugin } from './CameraPlugin';
export { CameraManager, CameraManagerImpl, type ICameraManager } from './CameraManager';
// Service Tokens (reserved for future use)
// 服务令牌(预留用于未来扩展)
// export { CameraManagerToken, type ICameraManager } from './tokens';
// Service Tokens
// 服务令牌
export { CameraManagerToken } from './tokens';

View File

@@ -4,28 +4,17 @@
*
* 遵循"谁定义接口,谁导出 Token"原则。
* Following "who defines interface, who exports Token" principle.
*
* 当前模块仅提供组件,暂无服务定义。
* 此文件预留用于未来可能添加的 CameraManager 服务。
*
* Currently this module only provides components, no services defined yet.
* This file is reserved for potential future CameraManager service.
*/
// import { createServiceToken } from '@esengine/engine-core';
import { createServiceToken } from '@esengine/ecs-framework';
import type { ICameraManager } from './CameraManager';
// ============================================================================
// Reserved for future service tokens
// 预留用于未来的服务令牌
// ============================================================================
// Re-export interface for consumers
// 重新导出接口供消费者使用
export type { ICameraManager };
// export interface ICameraManager {
// // 获取主相机 | Get main camera
// getMainCamera(): CameraComponent | null;
// // 设置主相机 | Set main camera
// setMainCamera(camera: CameraComponent): void;
// // 屏幕坐标转世界坐标 | Screen to world coordinates
// screenToWorld(screenX: number, screenY: number): { x: number; y: number };
// }
// export const CameraManagerToken = createServiceToken<ICameraManager>('cameraManager');
/**
* 相机管理器服务令牌
* Camera manager service token
*/
export const CameraManagerToken = createServiceToken<ICameraManager>('cameraManager');