feat(asset): 统一资产引用使用 GUID 替代路径 (#287)

* feat(world-streaming): 添加世界流式加载系统实现基于区块的世界流式加载系统，支持开放世界游戏：运行时包 (@esengine/world-streaming): - ChunkComponent: 区块实体组件，包含坐标、边界、状态 - StreamingAnchorComponent: 流式锚点组件（玩家/摄像机） - ChunkLoaderComponent: 流式加载配置组件 - ChunkStreamingSystem: 区块加载/卸载调度系统 - ChunkCullingSystem: 区块可见性剔除系统 - ChunkManager: 区块生命周期管理服务 - SpatialHashGrid: 空间哈希网格 - ChunkSerializer: 区块序列化编辑器包 (@esengine/world-streaming-editor): - ChunkVisualizer: 区块可视化覆盖层 - ChunkLoaderInspectorProvider: 区块加载器检视器 - StreamingAnchorInspectorProvider: 流式锚点检视器 - WorldStreamingPlugin: 完整插件导出 * feat(asset): 统一资产引用使用 GUID 替代路径将所有组件的资产引用字段从路径改为 GUID： - SpriteComponent: texture -> textureGuid, material -> materialGuid - SpriteAnimatorComponent: AnimationFrame.texture -> textureGuid - UIRenderComponent: texture -> textureGuid - UIButtonComponent: normalTexture -> normalTextureGuid 等 - AudioSourceComponent: clip -> clipGuid - ParticleSystemComponent: 已使用 textureGuid 修复 AssetRegistryService 注册问题和路径规范化，添加渲染系统的 GUID 解析支持。 * fix(sprite-editor): 更新 material 为 materialGuid * fix(editor-app): 更新 AnimationFrame.texture 为 textureGuid
2025-12-06 14:08:48 +08:00
parent 0c03b13d74
commit 3617f40309
25 changed files with 443 additions and 152 deletions
--- a/packages/ui/src/UIBuilder.ts
+++ b/packages/ui/src/UIBuilder.ts
@@ -61,7 +61,8 @@ export interface UITextConfig extends UIBaseConfig {
 * Image configuration
 */
 export interface UIImageConfig extends UIBaseConfig {
-    texture: string | number;
+    /** 纹理资产 GUID 或运行时 ID | Texture asset GUID or runtime ID */
+    textureGuid: string | number;
    tint?: number;
 }

@@ -236,7 +237,7 @@ export class UIBuilder {

        const render = entity.addComponent(new UIRenderComponent());
        render.type = UIRenderType.Image;
-        render.texture = config.texture;
+        render.textureGuid = config.textureGuid;
        render.textureTint = config.tint ?? 0xFFFFFF;

        return entity;
--- a/packages/ui/src/components/UIRenderComponent.ts
+++ b/packages/ui/src/components/UIRenderComponent.ts
@@ -96,12 +96,12 @@ export class UIRenderComponent extends Component {
    // ===== 纹理 Texture =====

    /**
-     * 纹理路径或 ID
-     * Texture path or runtime ID
+     * 纹理资产 GUID 或运行时 ID
+     * Texture asset GUID or runtime ID
     */
    @Serialize()
    @Property({ type: 'asset', label: 'Texture', assetType: 'texture' })
-    public texture: string | number | null = null;
+    public textureGuid: string | number | null = null;

    /**
     * 纹理 UV 坐标 (用于图集)
@@ -230,20 +230,25 @@ export class UIRenderComponent extends Component {
    /**
     * 设置图片
     * Set image texture
+     *
+     * @param textureGuid - 纹理资产 GUID | Texture asset GUID
     */
-    public setImage(texture: string | number): this {
+    public setImage(textureGuid: string | number): this {
        this.type = UIRenderType.Image;
-        this.texture = texture;
+        this.textureGuid = textureGuid;
        return this;
    }

    /**
     * 设置九宫格
     * Set nine-patch image
+     *
+     * @param textureGuid - 纹理资产 GUID | Texture asset GUID
+     * @param margins - 九宫格边距 | Nine-patch margins
     */
-    public setNinePatch(texture: string | number, margins: [number, number, number, number]): this {
+    public setNinePatch(textureGuid: string | number, margins: [number, number, number, number]): this {
        this.type = UIRenderType.NinePatch;
-        this.texture = texture;
+        this.textureGuid = textureGuid;
        this.ninePatchMargins = margins;
        return this;
    }
--- a/packages/ui/src/components/widgets/UIButtonComponent.ts
+++ b/packages/ui/src/components/widgets/UIButtonComponent.ts
@@ -10,7 +10,8 @@ export interface UIButtonStyle {
    textColor: number;
    borderColor: number;
    borderWidth: number;
-    texture?: string;
+    /** 纹理资产 GUID | Texture asset GUID */
+    textureGuid?: string;
 }

 /**
@@ -51,36 +52,36 @@ export class UIButtonComponent extends Component {
    // ===== 状态纹理 State Textures =====

    /**
-     * 正常状态纹理
-     * Normal state texture
+     * 正常状态纹理 GUID
+     * Normal state texture GUID
     */
    @Serialize()
    @Property({ type: 'asset', label: 'Normal Texture', assetType: 'texture' })
-    public normalTexture: string = '';
+    public normalTextureGuid: string = '';

    /**
-     * 悬停状态纹理
-     * Hover state texture
+     * 悬停状态纹理 GUID
+     * Hover state texture GUID
     */
    @Serialize()
    @Property({ type: 'asset', label: 'Hover Texture', assetType: 'texture' })
-    public hoverTexture: string = '';
+    public hoverTextureGuid: string = '';

    /**
-     * 按下状态纹理
-     * Pressed state texture
+     * 按下状态纹理 GUID
+     * Pressed state texture GUID
     */
    @Serialize()
    @Property({ type: 'asset', label: 'Pressed Texture', assetType: 'texture' })
-    public pressedTexture: string = '';
+    public pressedTextureGuid: string = '';

    /**
-     * 禁用状态纹理
-     * Disabled state texture
+     * 禁用状态纹理 GUID
+     * Disabled state texture GUID
     */
    @Serialize()
    @Property({ type: 'asset', label: 'Disabled Texture', assetType: 'texture' })
-    public disabledTexture: string = '';
+    public disabledTextureGuid: string = '';

    // ===== 状态样式 State Styles =====

@@ -245,16 +246,16 @@ export class UIButtonComponent extends Component {
    }

    /**
-     * 获取当前应该显示的纹理
-     * Get the texture that should be displayed based on state
+     * 获取当前应该显示的纹理 GUID
+     * Get the texture GUID that should be displayed based on state
     */
-    public getStateTexture(state: 'disabled' | 'pressed' | 'hovered' | 'focused' | 'normal'): string {
-        if (this.disabled && this.disabledTexture) return this.disabledTexture;
+    public getStateTextureGuid(state: 'disabled' | 'pressed' | 'hovered' | 'focused' | 'normal'): string {
+        if (this.disabled && this.disabledTextureGuid) return this.disabledTextureGuid;
        switch (state) {
-            case 'pressed': return this.pressedTexture || this.normalTexture;
-            case 'hovered': return this.hoverTexture || this.normalTexture;
-            case 'focused': return this.normalTexture;
-            default: return this.normalTexture;
+            case 'pressed': return this.pressedTextureGuid || this.normalTextureGuid;
+            case 'hovered': return this.hoverTextureGuid || this.normalTextureGuid;
+            case 'focused': return this.normalTextureGuid;
+            default: return this.normalTextureGuid;
        }
    }

@@ -263,7 +264,7 @@ export class UIButtonComponent extends Component {
     * Whether to use texture for rendering
     */
    public useTexture(): boolean {
-        return (this.displayMode === 'texture' || this.displayMode === 'both') && !!this.normalTexture;
+        return (this.displayMode === 'texture' || this.displayMode === 'both') && !!this.normalTextureGuid;
    }

    /**
@@ -297,14 +298,14 @@ export class UIButtonComponent extends Component {
    }

    /**
-     * 设置纹理
-     * Set textures for different states
+     * 设置纹理 GUID
+     * Set texture GUIDs for different states
     */
-    public setTextures(normal: string, hover?: string, pressed?: string, disabled?: string): this {
-        this.normalTexture = normal;
-        if (hover) this.hoverTexture = hover;
-        if (pressed) this.pressedTexture = pressed;
-        if (disabled) this.disabledTexture = disabled;
+    public setTextureGuids(normalGuid: string, hoverGuid?: string, pressedGuid?: string, disabledGuid?: string): this {
+        this.normalTextureGuid = normalGuid;
+        if (hoverGuid) this.hoverTextureGuid = hoverGuid;
+        if (pressedGuid) this.pressedTextureGuid = pressedGuid;
+        if (disabledGuid) this.disabledTextureGuid = disabledGuid;
        this.displayMode = 'texture';
        return this;
    }
--- a/packages/ui/src/systems/render/UIButtonRenderSystem.ts
+++ b/packages/ui/src/systems/render/UIButtonRenderSystem.ts
@@ -66,8 +66,8 @@ export class UIButtonRenderSystem extends EntitySystem {
            // Render texture if in texture or both mode
            // 如果在纹理或两者模式下，渲染纹理
            if (button.useTexture()) {
-                const texture = button.getStateTexture('normal');
-                if (texture) {
+                const textureGuid = button.getStateTextureGuid('normal');
+                if (textureGuid) {
                    collector.addRect(
                        renderX, renderY,
                        width, height,
@@ -78,7 +78,7 @@ export class UIButtonRenderSystem extends EntitySystem {
                            rotation,
                            pivotX,
                            pivotY,
-                            texturePath: texture
+                            texturePath: textureGuid
                        }
                    );
                }
--- a/packages/ui/src/systems/render/UIRectRenderSystem.ts
+++ b/packages/ui/src/systems/render/UIRectRenderSystem.ts
@@ -96,9 +96,9 @@ export class UIRectRenderSystem extends EntitySystem {

            // Render texture if present
            // 如果有纹理，渲染纹理
-            if (render.texture) {
-                const texturePath = typeof render.texture === 'string' ? render.texture : undefined;
-                const textureId = typeof render.texture === 'number' ? render.texture : undefined;
+            if (render.textureGuid) {
+                const texturePath = typeof render.textureGuid === 'string' ? render.textureGuid : undefined;
+                const textureId = typeof render.textureGuid === 'number' ? render.textureGuid : undefined;

                collector.addRect(
                    renderX, renderY,