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/asset-system/src/core/AssetDatabase.ts

@@ -10,6 +10,47 @@ import {
     IAssetCatalogEntry
 } from '../types/AssetTypes';
 
+/**
+ * 纹理 Sprite 信息（从 meta 文件的 importSettings 读取）
+ * Texture sprite info (read from meta file's importSettings)
+ */
+export interface ITextureSpriteInfo {
+    /**
+     * 九宫格切片边距 [top, right, bottom, left]
+     * Nine-patch slice border
+     */
+    sliceBorder?: [number, number, number, number];
+    /**
+     * Sprite 锚点 [x, y]（0-1 归一化）
+     * Sprite pivot point (0-1 normalized)
+     */
+    pivot?: [number, number];
+    /**
+     * 纹理宽度（可选，需要纹理已加载）
+     * Texture width (optional, requires texture to be loaded)
+     */
+    width?: number;
+    /**
+     * 纹理高度（可选，需要纹理已加载）
+     * Texture height (optional, requires texture to be loaded)
+     */
+    height?: number;
+}
+
+/**
+ * Sprite settings in import settings
+ * 导入设置中的 Sprite 设置
+ */
+interface ISpriteSettings {
+    sliceBorder?: [number, number, number, number];
+    pivot?: [number, number];
+    pixelsPerUnit?: number;
+    /** Texture width (from import settings) | 纹理宽度（来自导入设置） */
+    width?: number;
+    /** Texture height (from import settings) | 纹理高度（来自导入设置） */
+    height?: number;
+}
+
 /**
  * Asset database implementation
  * 资产数据库实现
@@ -212,6 +253,41 @@ export class AssetDatabase {
         return guid ? this._metadata.get(guid) : undefined;
     }
 
+    /**
+     * Get texture sprite info from metadata
+     * 从元数据获取纹理 Sprite 信息
+     *
+     * Extracts spriteSettings from importSettings if available.
+     * 如果可用，从 importSettings 提取 spriteSettings。
+     *
+     * @param guid - Texture asset GUID | 纹理资产 GUID
+     * @returns Sprite info or undefined if not found/not a texture | Sprite 信息或未找到/非纹理则为 undefined
+     */
+    getTextureSpriteInfo(guid: AssetGUID): ITextureSpriteInfo | undefined {
+        const metadata = this._metadata.get(guid);
+        if (!metadata) return undefined;
+
+        // Check if it's a texture asset
+        // 检查是否是纹理资产
+        if (metadata.type !== AssetType.Texture) return undefined;
+
+        // Extract spriteSettings from importSettings
+        // 从 importSettings 提取 spriteSettings
+        const importSettings = metadata.importSettings as Record<string, unknown> | undefined;
+        const spriteSettings = importSettings?.spriteSettings as ISpriteSettings | undefined;
+
+        if (!spriteSettings) return undefined;
+
+        return {
+            sliceBorder: spriteSettings.sliceBorder,
+            pivot: spriteSettings.pivot,
+            // Include dimensions from import settings if available
+            // 如果可用，包含来自导入设置的尺寸
+            width: spriteSettings.width,
+            height: spriteSettings.height
+        };
+    }
+
     /**
      * Find assets by type
      * 按类型查找资产

packages/asset-system/src/core/AssetManager.ts

@@ -132,7 +132,10 @@ export class AssetManager implements IAssetManager {
                 labels: [],
                 tags: new Map(),
                 lastModified: Date.now(),
-                version: 1
+                version: 1,
+                // Include importSettings for sprite slicing (nine-patch), etc.
+                // 包含 importSettings 以支持精灵切片（九宫格）等功能
+                importSettings: entry.importSettings
             };
 
             this._database.addAsset(metadata);

packages/asset-system/src/index.ts

@@ -36,6 +36,7 @@ export { RuntimeCatalog, runtimeCatalog } from './runtime/RuntimeCatalog';
 export * from './interfaces/IAssetLoader';
 export * from './interfaces/IAssetManager';
 export * from './interfaces/IAssetReader';
+export * from './interfaces/IAssetFileLoader';
 export * from './interfaces/IResourceComponent';
 
 // Core
@@ -58,13 +59,24 @@ export { PrefabLoader } from './loaders/PrefabLoader';
 
 // Integration
 export { EngineIntegration } from './integration/EngineIntegration';
-export type { ITextureEngineBridge } from './integration/EngineIntegration';
+export type { ITextureEngineBridge, TextureLoadCallback } from './integration/EngineIntegration';
 
 // Services
 export { SceneResourceManager } from './services/SceneResourceManager';
 export type { IResourceLoader } from './services/SceneResourceManager';
 export { PathResolutionService } from './services/PathResolutionService';
 
+// Asset Metadata Service (primary API for sprite info)
+// 资产元数据服务（sprite 信息的主要 API）
+export {
+    setGlobalAssetDatabase,
+    getGlobalAssetDatabase,
+    setGlobalEngineBridge,
+    getGlobalEngineBridge,
+    getTextureSpriteInfo
+} from './services/AssetMetadataService';
+export type { ITextureSpriteInfo } from './core/AssetDatabase';
+
 // Utils
 export { UVHelper } from './utils/UVHelper';
 export {

packages/asset-system/src/integration/EngineIntegration.ts

@@ -31,12 +31,6 @@ export interface ITextureEngineBridge {
      */
     unloadTexture(id: number): void;
 
-    /**
-     * Get texture info
-     * 获取纹理信息
-     */
-    getTextureInfo(id: number): { width: number; height: number } | null;
-
     /**
      * Get or load texture by path.
      * 按路径获取或加载纹理。
@@ -109,6 +103,20 @@ export interface ITextureEngineBridge {
      * @returns Promise that resolves when texture is ready | 纹理就绪时解析的 Promise
      */
     loadTextureAsync?(id: number, url: string): Promise<void>;
+
+    /**
+     * Get texture info by path.
+     * 通过路径获取纹理信息。
+     *
+     * This is the primary API for getting texture dimensions.
+     * The Rust engine is the single source of truth for texture dimensions.
+     * 这是获取纹理尺寸的主要 API。
+     * Rust 引擎是纹理尺寸的唯一事实来源。
+     *
+     * @param path Image path/URL | 图片路径/URL
+     * @returns Texture info or null if not loaded | 纹理信息或未加载则为 null
+     */
+    getTextureInfoByPath?(path: string): { width: number; height: number } | null;
 }
 
 /**
@@ -131,10 +139,43 @@ interface DataAssetEntry {
     path: string;
 }
 
+/**
+ * Texture load callback type
+ * 纹理加载回调类型
+ */
+export type TextureLoadCallback = (guid: string, path: string, textureId: number) => void;
+
 /**
  * Asset system engine integration
  * 资产系统引擎集成
  */
+/**
+ * Texture sprite info (nine-patch border, pivot, etc.)
+ * 纹理 Sprite 信息（九宫格边距、锚点等）
+ */
+export interface ITextureSpriteInfo {
+    /**
+     * 九宫格切片边距 [top, right, bottom, left]
+     * Nine-patch slice border
+     */
+    sliceBorder?: [number, number, number, number];
+    /**
+     * Sprite 锚点 [x, y]（0-1 归一化）
+     * Sprite pivot point (0-1 normalized)
+     */
+    pivot?: [number, number];
+    /**
+     * 纹理宽度
+     * Texture width
+     */
+    width: number;
+    /**
+     * 纹理高度
+     * Texture height
+     */
+    height: number;
+}
+
 export class EngineIntegration {
     private _assetManager: AssetManager;
     private _engineBridge?: ITextureEngineBridge;
@@ -146,6 +187,54 @@ export class EngineIntegration {
     // Path-stable ID cache (persists across Play/Stop cycles)
     private static _pathIdCache = new Map<string, number>();
 
+    // 纹理 Sprite 信息缓存（全局静态，可供渲染系统访问）
+    // Texture sprite info cache (global static, accessible by render systems)
+    private static _textureSpriteInfoCache = new Map<AssetGUID, ITextureSpriteInfo>();
+
+    // 纹理加载回调（用于动态图集集成等）
+    // Texture load callback (for dynamic atlas integration, etc.)
+    private static _textureLoadCallbacks: TextureLoadCallback[] = [];
+
+    /**
+     * Register a callback to be called when textures are loaded
+     * 注册纹理加载时调用的回调
+     *
+     * This can be used for dynamic atlas integration.
+     * 可用于动态图集集成。
+     *
+     * @param callback - Callback function | 回调函数
+     */
+    static onTextureLoad(callback: TextureLoadCallback): void {
+        if (!EngineIntegration._textureLoadCallbacks.includes(callback)) {
+            EngineIntegration._textureLoadCallbacks.push(callback);
+        }
+    }
+
+    /**
+     * Remove a texture load callback
+     * 移除纹理加载回调
+     */
+    static removeTextureLoadCallback(callback: TextureLoadCallback): void {
+        const index = EngineIntegration._textureLoadCallbacks.indexOf(callback);
+        if (index >= 0) {
+            EngineIntegration._textureLoadCallbacks.splice(index, 1);
+        }
+    }
+
+    /**
+     * Notify all callbacks of a texture load
+     * 通知所有回调纹理已加载
+     */
+    private static notifyTextureLoad(guid: string, path: string, textureId: number): void {
+        for (const callback of EngineIntegration._textureLoadCallbacks) {
+            try {
+                callback(guid, path, textureId);
+            } catch (e) {
+                console.error('[EngineIntegration] Error in texture load callback:', e);
+            }
+        }
+    }
+
     // Audio resource mappings | 音频资源映射
     private _audioIdMap = new Map<AssetGUID, number>();
     private _pathToAudioId = new Map<string, number>();
@@ -279,6 +368,16 @@ export class EngineIntegration {
         const result = await this._assetManager.loadAsset<ITextureAsset>(guid);
         const metadata = result.metadata;
         const assetPath = metadata.path;
+        const textureAsset = result.asset;
+
+        // 缓存 sprite 信息（九宫格边距等）到静态缓存
+        // Cache sprite info (slice border, etc.) to static cache
+        EngineIntegration._textureSpriteInfoCache.set(guid, {
+            sliceBorder: textureAsset.sliceBorder,
+            pivot: textureAsset.pivot,
+            width: textureAsset.width,
+            height: textureAsset.height
+        });
 
         // 生成路径稳定 ID
         // Generate path-stable ID
@@ -309,9 +408,37 @@ export class EngineIntegration {
         this._textureIdMap.set(guid, stableId);
         this._pathToTextureId.set(assetPath, stableId);
 
+        // 通知回调（用于动态图集等）
+        // Notify callbacks (for dynamic atlas, etc.)
+        EngineIntegration.notifyTextureLoad(guid, engineUrl, stableId);
+
         return stableId;
     }
 
+    /**
+     * Get texture sprite info by GUID (static method for render system access)
+     * 通过 GUID 获取纹理 Sprite 信息（静态方法，供渲染系统访问）
+     *
+     * Returns cached sprite info including nine-patch slice border.
+     * Must call loadTextureByGuid first to populate the cache.
+     * 返回缓存的 sprite 信息，包括九宫格边距。
+     * 必须先调用 loadTextureByGuid 来填充缓存。
+     *
+     * @param guid - Texture asset GUID | 纹理资产 GUID
+     * @returns Sprite info or undefined if not loaded | Sprite 信息或未加载则为 undefined
+     */
+    static getTextureSpriteInfo(guid: AssetGUID): ITextureSpriteInfo | undefined {
+        return EngineIntegration._textureSpriteInfoCache.get(guid);
+    }
+
+    /**
+     * Clear texture sprite info cache
+     * 清除纹理 Sprite 信息缓存
+     */
+    static clearTextureSpriteInfoCache(): void {
+        EngineIntegration._textureSpriteInfoCache.clear();
+    }
+
     /**
      * Batch load textures
      * 批量加载纹理

packages/asset-system/src/interfaces/IAssetFileLoader.ts

@@ -0,0 +1,103 @@
+/**
+ * Asset File Loader Interface
+ * 资产文件加载器接口
+ *
+ * High-level file loading abstraction that combines path resolution
+ * with platform-specific file reading.
+ * 高级文件加载抽象，结合路径解析和平台特定的文件读取。
+ *
+ * This is the unified entry point for all file loading in the engine.
+ * Different from IAssetLoader (which parses content), this interface
+ * handles the actual file fetching from asset paths.
+ * 这是引擎中所有文件加载的统一入口。
+ * 与 IAssetLoader（解析内容）不同，此接口处理从资产路径获取文件。
+ */
+
+/**
+ * Asset file loader interface.
+ * 资产文件加载器接口。
+ *
+ * Provides a unified API for loading files from asset paths (relative to project).
+ * Different platforms provide their own implementations.
+ * 提供从资产路径（相对于项目）加载文件的统一 API。
+ * 不同平台提供各自的实现。
+ *
+ * @example
+ * ```typescript
+ * // Get global loader
+ * const loader = getGlobalAssetFileLoader();
+ *
+ * // Load image from asset path (relative to project)
+ * const image = await loader.loadImage('assets/demo/button.png');
+ *
+ * // Load text content
+ * const json = await loader.loadText('assets/config.json');
+ * ```
+ */
+export interface IAssetFileLoader {
+    /**
+     * Load image from asset path.
+     * 从资产路径加载图片。
+     *
+     * @param assetPath - Asset path relative to project (e.g., "assets/demo/button.png").
+     *                    相对于项目的资产路径。
+     * @returns Promise resolving to HTMLImageElement. | 返回 HTMLImageElement 的 Promise。
+     */
+    loadImage(assetPath: string): Promise<HTMLImageElement>;
+
+    /**
+     * Load text content from asset path.
+     * 从资产路径加载文本内容。
+     *
+     * @param assetPath - Asset path relative to project. | 相对于项目的资产路径。
+     * @returns Promise resolving to text content. | 返回文本内容的 Promise。
+     */
+    loadText(assetPath: string): Promise<string>;
+
+    /**
+     * Load binary data from asset path.
+     * 从资产路径加载二进制数据。
+     *
+     * @param assetPath - Asset path relative to project. | 相对于项目的资产路径。
+     * @returns Promise resolving to ArrayBuffer. | 返回 ArrayBuffer 的 Promise。
+     */
+    loadBinary(assetPath: string): Promise<ArrayBuffer>;
+
+    /**
+     * Check if asset file exists.
+     * 检查资产文件是否存在。
+     *
+     * @param assetPath - Asset path relative to project. | 相对于项目的资产路径。
+     * @returns Promise resolving to boolean. | 返回布尔值的 Promise。
+     */
+    exists(assetPath: string): Promise<boolean>;
+}
+
+/**
+ * Global asset file loader instance.
+ * 全局资产文件加载器实例。
+ */
+let globalAssetFileLoader: IAssetFileLoader | null = null;
+
+/**
+ * Set the global asset file loader.
+ * 设置全局资产文件加载器。
+ *
+ * Should be called during engine initialization with platform-specific implementation.
+ * 应在引擎初始化期间使用平台特定的实现调用。
+ *
+ * @param loader - Asset file loader instance or null. | 资产文件加载器实例或 null。
+ */
+export function setGlobalAssetFileLoader(loader: IAssetFileLoader | null): void {
+    globalAssetFileLoader = loader;
+}
+
+/**
+ * Get the global asset file loader.
+ * 获取全局资产文件加载器。
+ *
+ * @returns Asset file loader instance or null. | 资产文件加载器实例或 null。
+ */
+export function getGlobalAssetFileLoader(): IAssetFileLoader | null {
+    return globalAssetFileLoader;
+}

packages/asset-system/src/interfaces/IAssetLoader.ts

@@ -144,6 +144,24 @@ export interface ITextureAsset {
     hasMipmaps: boolean;
     /** 原始数据（如果可用） / Raw image data if available */
     data?: ImageData | HTMLImageElement;
+
+    // ===== Sprite Settings =====
+    // ===== Sprite 设置 =====
+
+    /**
+     * 九宫格切片边距 [top, right, bottom, left]
+     * Nine-patch slice border
+     *
+     * Defines the non-stretchable borders for nine-patch rendering.
+     * 定义九宫格渲染时不可拉伸的边框区域。
+     */
+    sliceBorder?: [number, number, number, number];
+
+    /**
+     * Sprite 锚点 [x, y]（0-1 归一化）
+     * Sprite pivot point (0-1 normalized)
+     */
+    pivot?: [number, number];
 }
 
 /**
@@ -183,24 +201,109 @@ export interface IAudioAsset {
     channels: number;
 }
 
+/**
+ * Shader property type
+ * 着色器属性类型
+ */
+export type ShaderPropertyType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'int' | 'sampler2D' | 'mat3' | 'mat4';
+
+/**
+ * Shader property definition
+ * 着色器属性定义
+ */
+export interface IShaderProperty {
+    /** 属性名称（uniform 名） / Property name (uniform name) */
+    name: string;
+    /** 属性类型 / Property type */
+    type: ShaderPropertyType;
+    /** 默认值 / Default value */
+    default: number | number[];
+    /** 显示名称（编辑器用） / Display name for editor */
+    displayName?: string;
+    /** 值范围（用于 float/int） / Value range for float/int */
+    range?: [number, number];
+    /** 是否隐藏（内部使用） / Hidden from inspector */
+    hidden?: boolean;
+}
+
+/**
+ * Shader asset interface
+ * 着色器资产接口
+ *
+ * Shader assets contain GLSL source code and property definitions.
+ * 着色器资产包含 GLSL 源代码和属性定义。
+ */
+export interface IShaderAsset {
+    /** 着色器名称 / Shader name (e.g., "UI/Shiny") */
+    name: string;
+    /** 顶点着色器源代码 / Vertex shader GLSL source */
+    vertex: string;
+    /** 片段着色器源代码 / Fragment shader GLSL source */
+    fragment: string;
+    /** 属性定义列表 / Property definitions */
+    properties: IShaderProperty[];
+    /** 编译后的着色器 ID（运行时填充） / Compiled shader ID (runtime) */
+    shaderId?: number;
+}
+
+/**
+ * Material property value
+ * 材质属性值
+ */
+export type MaterialPropertyValue = number | number[] | string;
+
+/**
+ * Material animator configuration
+ * 材质动画器配置
+ */
+export interface IMaterialAnimator {
+    /** 要动画的属性名 / Property to animate */
+    property: string;
+    /** 起始值 / Start value */
+    from: number;
+    /** 结束值 / End value */
+    to: number;
+    /** 持续时间（秒） / Duration in seconds */
+    duration: number;
+    /** 是否循环 / Loop animation */
+    loop?: boolean;
+    /** 循环间隔（秒） / Delay between loops */
+    loopDelay?: number;
+    /** 缓动函数 / Easing function */
+    easing?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+    /** 是否自动播放 / Auto play on start */
+    autoPlay?: boolean;
+}
+
 /**
  * Material asset interface
  * 材质资产接口
+ *
+ * Material assets reference a shader and define property values.
+ * 材质资产引用着色器并定义属性值。
  */
 export interface IMaterialAsset {
-    /** 着色器名称 / Shader name */
+    /** 材质名称 / Material name */
+    name: string;
+    /** 着色器 GUID 或内置路径 / Shader GUID or built-in path (e.g., "builtin://shaders/Shiny") */
     shader: string;
-    /** 材质属性 / Material properties */
-    properties: Map<string, unknown>;
-    /** 纹理映射 / Texture slot mappings */
-    textures: Map<string, AssetGUID>;
+    /** 材质属性值 / Material property values */
+    properties: Record<string, MaterialPropertyValue>;
+    /** 纹理映射 / Texture slot mappings (property name -> texture GUID) */
+    textures?: Record<string, AssetGUID>;
     /** 渲染状态 / Render states */
-    renderStates: {
+    renderStates?: {
         cullMode?: 'none' | 'front' | 'back';
-        blendMode?: 'none' | 'alpha' | 'additive' | 'multiply';
+        blendMode?: 'none' | 'alpha' | 'additive' | 'multiply' | 'screen';
         depthTest?: boolean;
         depthWrite?: boolean;
     };
+    /** 动画器配置（可选） / Animator configuration (optional) */
+    animator?: IMaterialAnimator;
+    /** 运行时：编译后的着色器 ID / Runtime: compiled shader ID */
+    _shaderId?: number;
+    /** 运行时：引擎材质 ID / Runtime: engine material ID */
+    _materialId?: number;
 }
 
 // 预制体资产接口从专用文件导出 | Prefab asset interface exported from dedicated file

packages/asset-system/src/loaders/AssetLoaderFactory.ts

@@ -46,6 +46,9 @@ export class AssetLoaderFactory implements IAssetLoaderFactory {
 
         // 预制体加载器 / Prefab loader
         this._loaders.set(AssetType.Prefab, new PrefabLoader());
+
+        // 注：Shader 和 Material 加载器由 material-system 模块注册
+        // Note: Shader and Material loaders are registered by material-system module
     }
 
     /**

packages/asset-system/src/loaders/TextureLoader.ts

@@ -16,6 +16,16 @@ interface IEngineBridgeGlobal {
     unloadTexture?(textureId: number): void;
 }
 
+/**
+ * Sprite settings from texture meta
+ * 纹理 meta 中的 Sprite 设置
+ */
+interface ISpriteSettings {
+    sliceBorder?: [number, number, number, number];
+    pivot?: [number, number];
+    pixelsPerUnit?: number;
+}
+
 /**
  * 获取全局引擎桥接
  * Get global engine bridge
@@ -61,13 +71,22 @@ export class TextureLoader implements IAssetLoader<ITextureAsset> {
 
         const image = content.image;
 
+        // Read sprite settings from import settings
+        // 从导入设置读取 sprite 设置
+        const importSettings = context.metadata.importSettings as Record<string, unknown> | undefined;
+        const spriteSettings = importSettings?.spriteSettings as ISpriteSettings | undefined;
+
         const textureAsset: ITextureAsset = {
             textureId: TextureLoader._nextTextureId++,
             width: image.width,
             height: image.height,
             format: 'rgba',
             hasMipmaps: false,
-            data: image
+            data: image,
+            // Include sprite settings if available
+            // 如果有则包含 sprite 设置
+            sliceBorder: spriteSettings?.sliceBorder,
+            pivot: spriteSettings?.pivot
         };
 
         // Upload to GPU if bridge exists.

packages/asset-system/src/services/AssetMetadataService.ts

@@ -0,0 +1,139 @@
+/**
+ * Asset Metadata Service
+ * 资产元数据服务
+ *
+ * Provides global access to asset metadata without requiring asset loading.
+ * This service is independent of the texture loading path, allowing
+ * render systems to query sprite info regardless of how textures are loaded.
+ *
+ * 提供对资产元数据的全局访问，无需加载资产。
+ * 此服务独立于纹理加载路径，允许渲染系统查询 sprite 信息，
+ * 无论纹理是如何加载的。
+ */
+
+import { AssetDatabase, ITextureSpriteInfo } from '../core/AssetDatabase';
+import type { AssetGUID } from '../types/AssetTypes';
+import type { ITextureEngineBridge } from '../integration/EngineIntegration';
+
+/**
+ * Global asset database instance
+ * 全局资产数据库实例
+ */
+let globalAssetDatabase: AssetDatabase | null = null;
+
+/**
+ * Global engine bridge instance
+ * 全局引擎桥实例
+ *
+ * Used to query texture dimensions from Rust engine (single source of truth).
+ * 用于从 Rust 引擎查询纹理尺寸（唯一事实来源）。
+ */
+let globalEngineBridge: ITextureEngineBridge | null = null;
+
+/**
+ * Set the global asset database
+ * 设置全局资产数据库
+ *
+ * Should be called during engine initialization.
+ * 应在引擎初始化期间调用。
+ *
+ * @param database - AssetDatabase instance | AssetDatabase 实例
+ */
+export function setGlobalAssetDatabase(database: AssetDatabase | null): void {
+    globalAssetDatabase = database;
+}
+
+/**
+ * Get the global asset database
+ * 获取全局资产数据库
+ *
+ * @returns AssetDatabase instance or null | AssetDatabase 实例或 null
+ */
+export function getGlobalAssetDatabase(): AssetDatabase | null {
+    return globalAssetDatabase;
+}
+
+/**
+ * Set the global engine bridge
+ * 设置全局引擎桥
+ *
+ * The engine bridge is used to query texture dimensions directly from Rust engine.
+ * This is the single source of truth for texture dimensions.
+ * 引擎桥用于直接从 Rust 引擎查询纹理尺寸。
+ * 这是纹理尺寸的唯一事实来源。
+ *
+ * @param bridge - ITextureEngineBridge instance | ITextureEngineBridge 实例
+ */
+export function setGlobalEngineBridge(bridge: ITextureEngineBridge | null): void {
+    globalEngineBridge = bridge;
+}
+
+/**
+ * Get the global engine bridge
+ * 获取全局引擎桥
+ *
+ * @returns ITextureEngineBridge instance or null | ITextureEngineBridge 实例或 null
+ */
+export function getGlobalEngineBridge(): ITextureEngineBridge | null {
+    return globalEngineBridge;
+}
+
+/**
+ * Get texture sprite info by GUID
+ * 通过 GUID 获取纹理 Sprite 信息
+ *
+ * This is the primary API for render systems to query nine-patch/sprite info.
+ * It combines data from:
+ * - Asset metadata (sliceBorder, pivot) from AssetDatabase
+ * - Texture dimensions (width, height) from Rust engine (single source of truth)
+ *
+ * 这是渲染系统查询九宫格/sprite 信息的主要 API。
+ * 它合并来自：
+ * - AssetDatabase 的资产元数据（sliceBorder, pivot）
+ * - Rust 引擎的纹理尺寸（width, height）（唯一事实来源）
+ *
+ * @param guid - Texture asset GUID | 纹理资产 GUID
+ * @returns Sprite info or undefined | Sprite 信息或 undefined
+ */
+export function getTextureSpriteInfo(guid: AssetGUID): ITextureSpriteInfo | undefined {
+    // Get sprite settings from metadata
+    // 从元数据获取 sprite 设置
+    const metadataInfo = globalAssetDatabase?.getTextureSpriteInfo(guid);
+
+    // Get texture dimensions from Rust engine (single source of truth)
+    // 从 Rust 引擎获取纹理尺寸（唯一事实来源）
+    let dimensions: { width: number; height: number } | undefined;
+
+    if (globalEngineBridge?.getTextureInfoByPath && globalAssetDatabase) {
+        // Get asset path from database
+        // 从数据库获取资产路径
+        const metadata = globalAssetDatabase.getMetadata(guid);
+        if (metadata?.path) {
+            const engineInfo = globalEngineBridge.getTextureInfoByPath(metadata.path);
+            if (engineInfo) {
+                dimensions = engineInfo;
+            }
+        }
+    }
+
+    // If no metadata and no dimensions, return undefined
+    // 如果没有元数据也没有尺寸，返回 undefined
+    if (!metadataInfo && !dimensions) {
+        return undefined;
+    }
+
+    // Merge the two sources
+    // 合并两个数据源
+    // Prefer engine dimensions (runtime loaded), fallback to metadata dimensions (catalog stored)
+    // 优先使用引擎尺寸（运行时加载），后备使用元数据尺寸（目录存储）
+    return {
+        sliceBorder: metadataInfo?.sliceBorder,
+        pivot: metadataInfo?.pivot,
+        width: dimensions?.width ?? metadataInfo?.width,
+        height: dimensions?.height ?? metadataInfo?.height
+    };
+}
+
+// Re-export type for convenience
+// 为方便起见重新导出类型
+export type { ITextureSpriteInfo };

packages/asset-system/src/types/AssetTypes.ts

@@ -406,6 +406,12 @@ export interface IAssetCatalogEntry {
 
     /** 可用变体 / Available variants (platform/quality specific) */
     variants?: IAssetVariant[];
+
+    /**
+     * Import settings (e.g., sprite slicing for nine-patch)
+     * 导入设置（如九宫格切片信息）
+     */
+    importSettings?: Record<string, unknown>;
 }
 
 /**