refactor(ui): UI 系统架构重构 (#309)

* feat(ui): 动态图集系统与渲染调试增强

## 核心功能

### 动态图集系统 (Dynamic Atlas)
- 新增 DynamicAtlasManager：运行时纹理打包，支持 MaxRects 算法
- 新增 DynamicAtlasService：自动纹理加载与图集管理
- 新增 BinPacker：高效矩形打包算法
- 支持动态/固定两种扩展策略
- 自动 UV 重映射，实现 UI 元素合批渲染

### Frame Debugger 增强
- 新增合批分析面板，显示批次中断原因
- 新增 UI 元素层级信息（depth, worldOrderInLayer）
- 新增实体高亮功能，点击可在场景中定位
- 新增动态图集可视化面板
- 改进渲染原语详情展示

### 闪光效果 (Shiny Effect)
- 新增 UIShinyEffectComponent：UI 闪光参数配置
- 新增 UIShinyEffectSystem：材质覆盖驱动的闪光动画
- 新增 ShinyEffectComponent/System（Sprite 版本）

## 引擎层改进

### Rust 纹理管理扩展
- create_blank_texture：创建空白 GPU 纹理
- update_texture_region：局部纹理更新
- 支持动态图集的 GPU 端操作

### 材质系统
- 新增 effects/ 目录：ShinyEffect 等效果实现
- 新增 interfaces/ 目录：IMaterial 等接口定义
- 新增 mixins/ 目录：可组合的材质功能

### EngineBridge 扩展
- 新增 createBlankTexture/updateTextureRegion 方法
- 改进纹理加载回调机制

## UI 渲染改进
- UIRenderCollector：支持合批调试信息
- 稳定排序：addIndex 保证渲染顺序一致性
- 九宫格渲染优化
- 材质覆盖支持

## 其他改进
- 国际化：新增 Frame Debugger 相关翻译
- 编辑器：新增渲染调试入口
- 文档：新增架构设计文档目录

* refactor(ui): 引入新基础组件架构与渲染工具函数

Phase 1 重构 - 组件职责分离与代码复用：

新增基础组件层：
- UIGraphicComponent: 所有可视 UI 元素的基类（颜色、透明度、raycast）
- UIImageComponent: 纹理显示组件（支持简单、切片、平铺、填充模式）
- UISelectableComponent: 可交互元素的基类（状态管理、颜色过渡）

新增渲染工具：
- UIRenderUtils: 提取共享的坐标计算、边框渲染、阴影渲染等工具函数
- getUIRenderTransform: 统一的变换数据提取
- renderBorder/renderShadow: 复用的边框和阴影渲染逻辑

新增渲染系统：
- UIGraphicRenderSystem: 处理新基础组件的统一渲染器

重构现有系统：
- UIRectRenderSystem: 使用新工具函数，移除重复代码
- UIButtonRenderSystem: 使用新工具函数，移除重复代码

这些改动为后续统一渲染系统奠定基础。

* refactor(ui): UIProgressBarRenderSystem 使用渲染工具函数

- 使用 getUIRenderTransform 替代手动变换计算
- 使用 renderBorder 工具函数替代重复的边框渲染
- 使用 lerpColor 工具函数替代重复的颜色插值
- 简化方法签名，使用 UIRenderTransform 类型
- 移除约 135 行重复代码

* refactor(ui): Slider 和 ScrollView 渲染系统使用工具函数

- UISliderRenderSystem: 使用 getUIRenderTransform，简化方法签名
- UIScrollViewRenderSystem: 使用 getUIRenderTransform，简化方法签名
- 统一使用 UIRenderTransform 类型减少参数传递
- 消除重复的变换计算代码

* refactor(ui): 使用 UIWidgetMarker 消除硬编码组件依赖

- 新增 UIWidgetMarker 标记组件
- UIRectRenderSystem 改为检查标记而非硬编码4种组件类型
- 各 Widget 渲染系统自动添加标记组件
- 减少模块间耦合，提高可扩展性

* feat(ui): 实现 Canvas 隔离机制

- 新增 UICanvasComponent 定义 Canvas 渲染组
- UITransformComponent 添加 Canvas 相关字段：canvasEntityId, worldSortingLayer, pixelPerfect
- UILayoutSystem 传播 Canvas 设置给子元素
- UIRenderUtils 使用 Canvas 继承的排序层
- 支持嵌套 Canvas 和不同渲染模式

* refactor(ui): 统一纹理管理工具函数

Phase 4: 纹理管理统一

新增:
- UITextureUtils.ts: 统一的纹理描述符接口和验证函数
  - UITextureDescriptor: 支持 GUID/textureId/path 多种纹理源
  - isValidTextureGuid: GUID 验证
  - getTextureKey: 获取用于合批的纹理键
  - normalizeTextureDescriptor: 规范化各种输入格式
- utils/index.ts: 工具函数导出

修改:
- UIGraphicRenderSystem: 使用新的纹理工具函数
- index.ts: 导出纹理工具类型和函数

* refactor(ui): 实现统一的脏标记机制

Phase 5: Dirty 标记机制

新增:
- UIDirtyFlags.ts: 位标记枚举和追踪工具
  - UIDirtyFlags: Visual/Layout/Transform/Material/Text 标记
  - IDirtyTrackable: 脏追踪接口
  - DirtyTracker: 辅助工具类
  - 帧级别脏状态追踪 (markFrameDirty, isFrameDirty)

修改:
- UIGraphicComponent: 实现 IDirtyTrackable
  - 属性 setter 自动设置脏标记
  - 保留 setDirty/clearDirty 向后兼容
- UIImageComponent: 所有属性支持脏追踪
  - textureGuid/imageType/fillAmount 等变化自动标记
- UIGraphicRenderSystem: 使用 clearDirtyFlags()

导出:
- UIDirtyFlags, IDirtyTrackable, DirtyTracker
- markFrameDirty, isFrameDirty, clearFrameDirty

* refactor(ui): 移除过时的 dirty flag API

移除 UIGraphicComponent 中的兼容性 API:
- 移除 _isDirty getter/setter
- 移除 setDirty() 方法
- 移除 clearDirty() 方法

现在统一使用新的 dirty flag 系统:
- isDirty() / hasDirtyFlag(flags)
- markDirty(flags) / clearDirtyFlags()

* fix(ui): 修复两个 TODO 功能

1. 滑块手柄命中测试 (UIInputSystem)
   - UISliderComponent 添加 getHandleBounds() 计算手柄边界
   - UISliderComponent 添加 isPointInHandle() 精确命中测试
   - UIInputSystem.handleSlider() 使用精确测试更新悬停状态

2. 径向填充渲染 (UIGraphicRenderSystem)
   - 实现 renderRadialFill() 方法
   - 支持 radial90/radial180/radial360 三种模式
   - 支持 fillOrigin (top/right/bottom/left) 和 fillClockwise
   - 使用多段矩形近似饼形填充效果

* feat(ui): 完善 UI 系统架构和九宫格渲染

* fix(ui): 修复文本渲染层级问题并清理调试代码

- 修复纹理就绪后调用 invalidateUIRenderCaches() 导致的无限循环
- 移除 UITextRenderSystem、UIButtonRenderSystem、UIRectRenderSystem 中的首帧调试输出
- 移除 UILayoutSystem 中的布局调试日志
- 清理所有 __UI_RENDER_DEBUG__ 条件日志

* refactor(ui): 优化渲染批处理和输入框组件

渲染系统:
- 修复 RenderBatcher 保持渲染顺序
- 优化 Rust SpriteBatch 避免合并非连续精灵
- 增强 EngineRenderSystem 纹理就绪检测

输入框组件:
- 增强 UIInputFieldComponent 功能
- 改进 UIInputSystem 输入处理
- 新增 TextMeasureService 文本测量服务

* fix(ui): 修复九宫格首帧渲染和InputField输入问题

- 修复九宫格首帧 size=0x0 问题：
  - Viewport.tsx: 预览模式读取图片尺寸存储到 importSettings
  - AssetDatabase: ISpriteSettings 添加 width/height 字段
  - AssetMetadataService: getTextureSpriteInfo 使用元数据尺寸作为后备
  - UIRectRenderSystem: 当 atlasEntry 不存在时使用 spriteInfo 尺寸
  - WebBuildPipeline: 构建时包含 importSettings
  - AssetManager: 从 catalog 初始化时复制 importSettings
  - AssetTypes: IAssetCatalogEntry 添加 importSettings 字段

- 修复 InputField 无法输入问题：
  - UIRuntimeModule: manifest 添加 pluginExport: 'UIPlugin'
  - 确保预览模式正确加载 UI 插件并绑定 UIInputSystem

- 添加调试日志用于排查纹理加载问题

* fix(sprite): 修复类型导出错误

MaterialPropertyOverride 和 MaterialOverrides 应从 @esengine/material-system 导出

* fix(ui-editor): 补充 AnchorPreset 拉伸预设的映射

添加 StretchTop, StretchMiddle, StretchBottom, StretchLeft, StretchCenter, StretchRight 的位置和锚点值映射

packages/core/src/ECS/Decorators/PropertyDecorator.ts

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 
-export type PropertyType = 'number' | 'integer' | 'string' | 'boolean' | 'color' | 'vector2' | 'vector3' | 'vector4' | 'enum' | 'asset' | 'array' | 'animationClips' | 'collisionLayer' | 'collisionMask';
+export type PropertyType = 'number' | 'integer' | 'string' | 'boolean' | 'color' | 'vector2' | 'vector3' | 'vector4' | 'enum' | 'asset' | 'array' | 'animationClips' | 'collisionLayer' | 'collisionMask' | 'entityRef';
 
 /**
  * 属性资源类型
@@ -52,6 +52,16 @@ interface PropertyOptionsBase {
     label?: string;
     /** 是否只读 | Read-only flag */
     readOnly?: boolean;
+    /**
+     * 是否在 Inspector 中隐藏
+     * Whether to hide this property in Inspector
+     *
+     * Hidden properties are still serialized but not shown in the default PropertyInspector.
+     * Useful when a custom Inspector handles the property.
+     * 隐藏的属性仍然会被序列化，但不会在默认的 PropertyInspector 中显示。
+     * 适用于自定义 Inspector 处理该属性的情况。
+     */
+    hidden?: boolean;
     /** Action buttons | 操作按钮 */
     actions?: PropertyAction[];
     /** 此属性控制的其他组件属性 | Properties this field controls */
@@ -193,6 +203,17 @@ interface CollisionMaskPropertyOptions extends PropertyOptionsBase {
     type: 'collisionMask';
 }
 
+/**
+ * 实体引用属性选项
+ * Entity reference property options
+ *
+ * Used for properties that store entity IDs and support drag-and-drop from SceneHierarchy.
+ * 用于存储实体 ID 的属性，支持从场景层级面板拖放。
+ */
+interface EntityRefPropertyOptions extends PropertyOptionsBase {
+    type: 'entityRef';
+}
+
 /**
  * 属性选项联合类型
  * Property options union type
@@ -208,7 +229,8 @@ export type PropertyOptions =
     | ArrayPropertyOptions
     | AnimationClipsPropertyOptions
     | CollisionLayerPropertyOptions
-    | CollisionMaskPropertyOptions;
+    | CollisionMaskPropertyOptions
+    | EntityRefPropertyOptions;
 
 // 使用 Symbol.for 创建全局 Symbol，确保跨包共享元数据
 // Use Symbol.for to create a global Symbol to ensure metadata sharing across packages

packages/core/src/ECS/Decorators/TypeDecorators.ts

@@ -112,6 +112,21 @@ export interface SystemMetadata {
      * Whether enabled by default (default true)
      */
     enabled?: boolean;
+
+    /**
+     * 是否在编辑模式下运行（默认 true）
+     * Whether to run in edit mode (default true)
+     *
+     * 默认情况下，所有系统在编辑模式下都会运行。
+     * 当设置为 false 时，此系统在编辑模式（非 Play 状态）下不会执行。
+     * 适用于物理系统、AI 系统等只应在游戏运行时执行的系统。
+     *
+     * By default, all systems run in edit mode.
+     * When set to false, this system will NOT execute during edit mode
+     * (when not playing). Useful for physics, AI, and other systems
+     * that should only run during gameplay.
+     */
+    runInEditMode?: boolean;
 }
 
 /**
@@ -166,6 +181,17 @@ export function getSystemMetadata(systemType: new (...args: any[]) => EntitySyst
     return (systemType as any).__systemMetadata__;
 }
 
+/**
+ * 从系统实例获取元数据
+ * Get metadata from system instance
+ *
+ * @param system 系统实例 | System instance
+ * @returns 系统元数据 | System metadata
+ */
+export function getSystemInstanceMetadata(system: EntitySystem): SystemMetadata | undefined {
+    return getSystemMetadata(system.constructor as new (...args: any[]) => EntitySystem);
+}
+
 /**
  * 获取系统类型的名称，优先使用装饰器指定的名称
  * Get system type name, preferring decorator-specified name

packages/core/src/ECS/Decorators/index.ts

@@ -28,6 +28,7 @@ export {
     getSystemTypeName,
     getSystemInstanceTypeName,
     getSystemMetadata,
+    getSystemInstanceMetadata,
     SYSTEM_TYPE_NAME
 } from './TypeDecorators';
 

packages/core/src/ECS/Scene.ts

@@ -13,7 +13,7 @@ import { QuerySystem } from './Core/QuerySystem';
 import { TypeSafeEventSystem } from './Core/EventSystem';
 import { ReferenceTracker } from './Core/ReferenceTracker';
 import { IScene, ISceneConfig } from './IScene';
-import { getComponentInstanceTypeName, getSystemInstanceTypeName, getSystemMetadata } from './Decorators';
+import { getComponentInstanceTypeName, getSystemInstanceTypeName, getSystemMetadata, getSystemInstanceMetadata } from './Decorators';
 import { TypedQueryBuilder } from './Core/Query/TypedQuery';
 import {
     SceneSerializer,
@@ -558,7 +558,7 @@ export class Scene implements IScene {
             const updateHandle = ProfilerSDK.beginSample('Systems.update', ProfileCategory.ECS);
             try {
                 for (const system of systems) {
-                    if (system.enabled) {
+                    if (this._shouldSystemRun(system)) {
                         const systemHandle = ProfilerSDK.beginSample(system.systemName, ProfileCategory.ECS);
                         try {
                             system.update();
@@ -577,7 +577,7 @@ export class Scene implements IScene {
             const lateUpdateHandle = ProfilerSDK.beginSample('Systems.lateUpdate', ProfileCategory.ECS);
             try {
                 for (const system of systems) {
-                    if (system.enabled) {
+                    if (this._shouldSystemRun(system)) {
                         const systemHandle = ProfilerSDK.beginSample(`${system.systemName}.late`, ProfileCategory.ECS);
                         try {
                             system.lateUpdate();
@@ -602,6 +602,34 @@ export class Scene implements IScene {
         }
     }
 
+    /**
+     * 检查系统是否应该运行
+     * Check if a system should run
+     *
+     * @param system 要检查的系统 | System to check
+     * @returns 是否应该运行 | Whether it should run
+     */
+    private _shouldSystemRun(system: EntitySystem): boolean {
+        // 系统必须启用
+        // System must be enabled
+        if (!system.enabled) {
+            return false;
+        }
+
+        // 非编辑模式下，所有启用的系统都运行
+        // In non-edit mode, all enabled systems run
+        if (!this.isEditorMode) {
+            return true;
+        }
+
+        // 编辑模式下，默认所有系统都运行
+        // 只有明确标记 runInEditMode: false 的系统不运行
+        // In edit mode, all systems run by default
+        // Only systems explicitly marked runInEditMode: false are skipped
+        const metadata = getSystemInstanceMetadata(system);
+        return metadata?.runInEditMode !== false;
+    }
+
     /**
      * 执行所有系统的延迟命令
      * Flush all systems' deferred commands