feat(engine): 改进 Rust 纹理管理器

- 支持任意 ID 的纹理加载（非递增）
- 添加纹理状态追踪 API
- 优化纹理缓存清理机制
- 更新 TypeScript 绑定

packages/ecs-engine-bindgen/src/core/EngineBridge.ts

@@ -883,6 +883,133 @@ export class EngineBridge implements ITextureEngineBridge {
         this.getEngine().clearAllTextures();
     }
 
+    // ===== Texture State API =====
+    // ===== 纹理状态 API =====
+
+    /**
+     * Get texture loading state.
+     * 获取纹理加载状态。
+     *
+     * @param id - Texture ID | 纹理ID
+     * @returns State string: 'loading', 'ready', or 'failed:reason'
+     *          状态字符串：'loading'、'ready' 或 'failed:reason'
+     */
+    getTextureState(id: number): string {
+        if (!this.initialized) return 'loading';
+        return this.getEngine().getTextureState(id);
+    }
+
+    /**
+     * Check if texture is ready for rendering.
+     * 检查纹理是否已就绪可渲染。
+     *
+     * @param id - Texture ID | 纹理ID
+     * @returns true if texture data is fully loaded | 纹理数据完全加载则返回true
+     */
+    isTextureReady(id: number): boolean {
+        if (!this.initialized) return false;
+        return this.getEngine().isTextureReady(id);
+    }
+
+    /**
+     * Get count of textures currently loading.
+     * 获取当前正在加载的纹理数量。
+     *
+     * @returns Number of textures in 'loading' state | 处于加载状态的纹理数量
+     */
+    getTextureLoadingCount(): number {
+        if (!this.initialized) return 0;
+        return this.getEngine().getTextureLoadingCount();
+    }
+
+    /**
+     * Load texture asynchronously with Promise.
+     * 使用Promise异步加载纹理。
+     *
+     * Unlike loadTexture which returns immediately with a placeholder,
+     * this method waits until the texture is actually loaded and ready.
+     * 与loadTexture立即返回占位符不同，此方法会等待纹理实际加载完成。
+     *
+     * @param id - Texture ID | 纹理ID
+     * @param url - Image URL | 图片URL
+     * @returns Promise that resolves when texture is ready, rejects on failure
+     *          纹理就绪时解析的Promise，失败时拒绝
+     */
+    loadTextureAsync(id: number, url: string): Promise<void> {
+        return new Promise((resolve, reject) => {
+            if (!this.initialized) {
+                reject(new Error('Engine not initialized'));
+                return;
+            }
+
+            // Start loading the texture
+            // 开始加载纹理
+            this.getEngine().loadTexture(id, url);
+
+            // Poll for state changes
+            // 轮询状态变化
+            const checkInterval = 16; // ~60fps
+            const maxWaitTime = 30000; // 30 seconds timeout
+            let elapsed = 0;
+
+            const checkState = () => {
+                const state = this.getTextureState(id);
+
+                if (state === 'ready') {
+                    resolve();
+                } else if (state.startsWith('failed:')) {
+                    const reason = state.substring(7);
+                    reject(new Error(`Texture load failed: ${reason}`));
+                } else if (elapsed >= maxWaitTime) {
+                    reject(new Error(`Texture load timeout after ${maxWaitTime}ms`));
+                } else {
+                    elapsed += checkInterval;
+                    setTimeout(checkState, checkInterval);
+                }
+            };
+
+            // Start checking after a small delay to allow initial state setup
+            // 稍后开始检查，允许初始状态设置
+            setTimeout(checkState, checkInterval);
+        });
+    }
+
+    /**
+     * Wait for all loading textures to complete.
+     * 等待所有加载中的纹理完成。
+     *
+     * @param timeout - Maximum wait time in ms (default: 30000)
+     *                  最大等待时间（毫秒，默认30000）
+     * @returns Promise that resolves when all textures are loaded
+     *          所有纹理加载完成时解析的Promise
+     */
+    waitForAllTextures(timeout: number = 30000): Promise<void> {
+        return new Promise((resolve, reject) => {
+            if (!this.initialized) {
+                reject(new Error('Engine not initialized'));
+                return;
+            }
+
+            const checkInterval = 16;
+            let elapsed = 0;
+
+            const checkLoading = () => {
+                const loadingCount = this.getTextureLoadingCount();
+
+                if (loadingCount === 0) {
+                    resolve();
+                } else if (elapsed >= timeout) {
+                    reject(new Error(`Timeout waiting for ${loadingCount} textures to load`));
+                } else {
+                    elapsed += checkInterval;
+                    setTimeout(checkLoading, checkInterval);
+                }
+            };
+
+            checkLoading();
+        });
+    }
+
     /**
      * Dispose the bridge and release resources.
      * 销毁桥接并释放资源。

packages/ecs-engine-bindgen/src/systems/EngineRenderSystem.ts

@@ -3,16 +3,16 @@
  * 用于ECS的引擎渲染系统。
  */
 
-import { EntitySystem, Matcher, Entity, ComponentType, ECSSystem, Component, Core } from '@esengine/ecs-framework';
-import { TransformComponent, sortingLayerManager } from '@esengine/engine-core';
-import { Color } from '@esengine/ecs-framework-math';
-import { SpriteComponent } from '@esengine/sprite';
 import { CameraComponent } from '@esengine/camera';
+import { Component, ComponentType, Core, ECSSystem, Entity, EntitySystem, Matcher } from '@esengine/ecs-framework';
+import { Color } from '@esengine/ecs-framework-math';
+import { TransformComponent, sortingLayerManager } from '@esengine/engine-core';
 import { getMaterialManager } from '@esengine/material-system';
+import { SpriteComponent } from '@esengine/sprite';
 import type { EngineBridge } from '../core/EngineBridge';
 import { RenderBatcher } from '../core/RenderBatcher';
-import type { SpriteRenderData } from '../types';
 import type { ITransformComponent } from '../core/SpriteRenderHelper';
+import type { SpriteRenderData } from '../types';
 
 /**
  * Render data from a provider
@@ -339,14 +339,12 @@ export class EngineRenderSystem extends EntitySystem {
             }
 
             // Calculate UV with flip | 计算带翻转的 UV
-            const uv: [number, number, number, number] = [0, 0, 1, 1];
-            if (sprite.flipX || sprite.flipY) {
-                if (sprite.flipX) {
-                    [uv[0], uv[2]] = [uv[2], uv[0]];
-                }
-                if (sprite.flipY) {
-                    [uv[1], uv[3]] = [uv[3], uv[1]];
-                }
+            const uv: [number, number, number, number] = [...sprite.uv];
+            if (sprite.flipX) {
+                [uv[0], uv[2]] = [uv[2], uv[0]];
+            }
+            if (sprite.flipY) {
+                [uv[1], uv[3]] = [uv[3], uv[1]];
             }
 
             // 使用世界变换（由 TransformSystem 计算，考虑父级变换），回退到本地变换
@@ -569,6 +567,13 @@ export class EngineRenderSystem extends EntitySystem {
             const tOffset = i * 7;
             const uvOffset = i * 4;
 
+            const uv: [number, number, number, number] = [
+                data.uvs[uvOffset],
+                data.uvs[uvOffset + 1],
+                data.uvs[uvOffset + 2],
+                data.uvs[uvOffset + 3]
+            ];
+
             const renderData: SpriteRenderData = {
                 x: data.transforms[tOffset],
                 y: data.transforms[tOffset + 1],
@@ -578,7 +583,7 @@ export class EngineRenderSystem extends EntitySystem {
                 originX: data.transforms[tOffset + 5],
                 originY: data.transforms[tOffset + 6],
                 textureId,
-                uv: [data.uvs[uvOffset], data.uvs[uvOffset + 1], data.uvs[uvOffset + 2], data.uvs[uvOffset + 3]],
+                uv,
                 color: data.colors[i]
             };
 

packages/ecs-engine-bindgen/src/wasm/es_engine.d.ts

@@ -209,11 +209,31 @@ export class GameEngine {
    * 获取所有已注册的视口ID。
    */
   getViewportIds(): string[];
+  /**
+   * 检查纹理是否已就绪
+   * Check if texture is ready to use
+   *
+   * # Arguments | 参数
+   * * `id` - Texture ID | 纹理ID
+   */
+  isTextureReady(id: number): boolean;
   /**
    * Add a capsule gizmo outline.
    * 添加胶囊Gizmo边框。
    */
   addGizmoCapsule(x: number, y: number, radius: number, half_height: number, rotation: number, r: number, g: number, b: number, a: number): void;
+  /**
+   * 获取纹理加载状态
+   * Get texture loading state
+   *
+   * # Arguments | 参数
+   * * `id` - Texture ID | 纹理ID
+   *
+   * # Returns | 返回
+   * State string: "loading", "ready", or "failed:reason"
+   * 状态字符串："loading"、"ready" 或 "failed:原因"
+   */
+  getTextureState(id: number): string;
   /**
    * Register a new viewport.
    * 注册新视口。
@@ -361,6 +381,11 @@ export class GameEngine {
    * 在恢复场景快照时应调用此方法，以确保纹理使用正确的ID重新加载。
    */
   clearTexturePathCache(): void;
+  /**
+   * 获取正在加载中的纹理数量
+   * Get the number of textures currently loading
+   */
+  getTextureLoadingCount(): number;
   /**
    * Create a new game engine instance.
    * 创建新的游戏引擎实例。
@@ -429,6 +454,8 @@ export interface InitOutput {
   readonly gameengine_getCamera: (a: number) => [number, number];
   readonly gameengine_getOrLoadTextureByPath: (a: number, b: number, c: number) => [number, number, number];
   readonly gameengine_getTextureIdByPath: (a: number, b: number, c: number) => number;
+  readonly gameengine_getTextureLoadingCount: (a: number) => number;
+  readonly gameengine_getTextureState: (a: number, b: number) => [number, number];
   readonly gameengine_getViewportCamera: (a: number, b: number, c: number) => [number, number];
   readonly gameengine_getViewportIds: (a: number) => [number, number];
   readonly gameengine_hasMaterial: (a: number, b: number) => number;
@@ -436,6 +463,7 @@ export interface InitOutput {
   readonly gameengine_height: (a: number) => number;
   readonly gameengine_isEditorMode: (a: number) => number;
   readonly gameengine_isKeyDown: (a: number, b: number, c: number) => number;
+  readonly gameengine_isTextureReady: (a: number, b: number) => number;
   readonly gameengine_loadTexture: (a: number, b: number, c: number, d: number) => [number, number];
   readonly gameengine_loadTextureByPath: (a: number, b: number, c: number) => [number, number, number];
   readonly gameengine_new: (a: number, b: number) => [number, number, number];

packages/engine/src/core/engine.rs

@@ -197,14 +197,6 @@ impl Engine {
         colors: &[u32],
         material_ids: &[u32],
     ) -> Result<()> {
-        // Debug: log once
-        use std::sync::atomic::{AtomicBool, Ordering};
-        static LOGGED: AtomicBool = AtomicBool::new(false);
-        if !LOGGED.swap(true, Ordering::Relaxed) {
-            let sprite_count = texture_ids.len();
-            log::info!("Engine submit_sprite_batch: {} sprites, texture_ids: {:?}", sprite_count, texture_ids);
-        }
-
         self.renderer.submit_batch(
             transforms,
             texture_ids,
@@ -382,6 +374,24 @@ impl Engine {
         self.texture_manager.clear_all();
     }
 
+    /// 获取纹理加载状态
+    /// Get texture loading state
+    pub fn get_texture_state(&self, id: u32) -> crate::renderer::texture::TextureState {
+        self.texture_manager.get_texture_state(id)
+    }
+
+    /// 检查纹理是否已就绪
+    /// Check if texture is ready to use
+    pub fn is_texture_ready(&self, id: u32) -> bool {
+        self.texture_manager.is_texture_ready(id)
+    }
+
+    /// 获取正在加载中的纹理数量
+    /// Get the number of textures currently loading
+    pub fn get_texture_loading_count(&self) -> u32 {
+        self.texture_manager.get_loading_count()
+    }
+
     /// Check if a key is currently pressed.
     /// 检查某个键是否当前被按下。
     pub fn is_key_down(&self, key_code: &str) -> bool {

packages/engine/src/lib.rs

@@ -224,6 +224,42 @@ impl GameEngine {
             .map_err(|e| JsValue::from_str(&e.to_string()))
     }
 
+    /// 获取纹理加载状态
+    /// Get texture loading state
+    ///
+    /// # Arguments | 参数
+    /// * `id` - Texture ID | 纹理ID
+    ///
+    /// # Returns | 返回
+    /// State string: "loading", "ready", or "failed:reason"
+    /// 状态字符串："loading"、"ready" 或 "failed:原因"
+    #[wasm_bindgen(js_name = getTextureState)]
+    pub fn get_texture_state(&self, id: u32) -> String {
+        use crate::renderer::texture::TextureState;
+        match self.engine.get_texture_state(id) {
+            TextureState::Loading => "loading".to_string(),
+            TextureState::Ready => "ready".to_string(),
+            TextureState::Failed(reason) => format!("failed:{}", reason),
+        }
+    }
+
+    /// 检查纹理是否已就绪
+    /// Check if texture is ready to use
+    ///
+    /// # Arguments | 参数
+    /// * `id` - Texture ID | 纹理ID
+    #[wasm_bindgen(js_name = isTextureReady)]
+    pub fn is_texture_ready(&self, id: u32) -> bool {
+        self.engine.is_texture_ready(id)
+    }
+
+    /// 获取正在加载中的纹理数量
+    /// Get the number of textures currently loading
+    #[wasm_bindgen(js_name = getTextureLoadingCount)]
+    pub fn get_texture_loading_count(&self) -> u32 {
+        self.engine.get_texture_loading_count()
+    }
+
     /// Check if a key is currently pressed.
     /// 检查某个键是否当前被按下。
     ///

packages/engine/src/renderer/texture/mod.rs

@@ -5,4 +5,4 @@ mod texture;
 mod texture_manager;
 
 pub use texture::Texture;
-pub use texture_manager::TextureManager;
+pub use texture_manager::{TextureManager, TextureState};

packages/engine/src/renderer/texture/texture_manager.rs

@@ -1,7 +1,9 @@
 //! Texture loading and management.
 //! 纹理加载和管理。
 
+use std::cell::RefCell;
 use std::collections::HashMap;
+use std::rc::Rc;
 use wasm_bindgen::prelude::*;
 use wasm_bindgen::JsCast;
 use web_sys::{HtmlImageElement, WebGl2RenderingContext, WebGlTexture};
@@ -9,6 +11,21 @@ use web_sys::{HtmlImageElement, WebGl2RenderingContext, WebGlTexture};
 use crate::core::error::{EngineError, Result};
 use super::Texture;
 
+/// 纹理加载状态
+/// Texture loading state
+#[derive(Debug, Clone, PartialEq)]
+pub enum TextureState {
+    /// 正在加载中
+    /// Loading in progress
+    Loading,
+    /// 加载完成，可以使用
+    /// Loaded and ready to use
+    Ready,
+    /// 加载失败
+    /// Load failed
+    Failed(String),
+}
+
 /// Texture manager for loading and caching textures.
 /// 用于加载和缓存纹理的纹理管理器。
 pub struct TextureManager {
@@ -31,6 +48,10 @@ pub struct TextureManager {
     /// Default white texture for untextured rendering.
     /// 用于无纹理渲染的默认白色纹理。
     default_texture: Option<WebGlTexture>,
+
+    /// 纹理加载状态（使用 Rc<RefCell<>> 以便闭包可以修改）
+    /// Texture loading states (using Rc<RefCell<>> so closures can modify)
+    texture_states: Rc<RefCell<HashMap<u32, TextureState>>>,
 }
 
 impl TextureManager {
@@ -43,6 +64,7 @@ impl TextureManager {
             path_to_id: HashMap::new(),
             next_id: 1, // Start from 1, 0 is reserved for default
             default_texture: None,
+            texture_states: Rc::new(RefCell::new(HashMap::new())),
         };
 
         // Create default white texture | 创建默认白色纹理
@@ -90,17 +112,22 @@ impl TextureManager {
     /// 从URL加载纹理。
     ///
     /// Note: This is an async operation. The texture will be available
-    /// after the image loads.
-    /// 注意：这是一个异步操作。纹理在图片加载后可用。
+    /// after the image loads. Use `get_texture_state` to check loading status.
+    /// 注意：这是一个异步操作。纹理在图片加载后可用。使用 `get_texture_state` 检查加载状态。
     pub fn load_texture(&mut self, id: u32, url: &str) -> Result<()> {
+        // 设置初始状态为 Loading | Set initial state to Loading
+        self.texture_states.borrow_mut().insert(id, TextureState::Loading);
+
         // Create placeholder texture | 创建占位纹理
         let texture = self.gl
             .create_texture()
             .ok_or_else(|| EngineError::TextureLoadFailed("Failed to create texture".into()))?;
 
-        // Set up temporary 1x1 texture | 设置临时1x1纹理
+        // Set up temporary 1x1 transparent texture | 设置临时1x1透明纹理
+        // 使用透明而非灰色，这样未加载完成时不会显示奇怪的颜色
+        // Use transparent instead of gray, so incomplete textures don't show strange colors
         self.gl.bind_texture(WebGl2RenderingContext::TEXTURE_2D, Some(&texture));
-        let placeholder: [u8; 4] = [128, 128, 128, 255];
+        let placeholder: [u8; 4] = [0, 0, 0, 0];
         let _ = self.gl.tex_image_2d_with_i32_and_i32_and_i32_and_format_and_type_and_opt_u8_array(
             WebGl2RenderingContext::TEXTURE_2D,
             0,
@@ -119,6 +146,10 @@ impl TextureManager {
         // Store texture with placeholder size | 存储带占位符尺寸的纹理
         self.textures.insert(id, Texture::new(texture, 1, 1));
 
+        // Clone state map for closures | 克隆状态映射用于闭包
+        let states_for_onload = Rc::clone(&self.texture_states);
+        let states_for_onerror = Rc::clone(&self.texture_states);
+
         // Load actual image asynchronously | 异步加载实际图片
         let gl = self.gl.clone();
 
@@ -130,6 +161,7 @@ impl TextureManager {
 
         // Clone image for use in closure | 克隆图片用于闭包
         let image_clone = image.clone();
+        let texture_id = id;
 
         // Set up load callback | 设置加载回调
         let onload = Closure::wrap(Box::new(move || {
@@ -146,7 +178,9 @@ impl TextureManager {
             );
 
             if let Err(e) = result {
-                log::error!("Failed to upload texture: {:?} | 纹理上传失败: {:?}", e, e);
+                log::error!("Failed to upload texture {}: {:?} | 纹理 {} 上传失败: {:?}", texture_id, e, texture_id, e);
+                states_for_onload.borrow_mut().insert(texture_id, TextureState::Failed(format!("{:?}", e)));
+                return;
             }
 
             // Set texture parameters | 设置纹理参数
@@ -171,10 +205,22 @@ impl TextureManager {
                 WebGl2RenderingContext::LINEAR as i32,
             );
 
+            // 标记为就绪 | Mark as ready
+            states_for_onload.borrow_mut().insert(texture_id, TextureState::Ready);
+
+        }) as Box<dyn Fn()>);
+
+        // Set up error callback | 设置错误回调
+        let url_for_error = url.to_string();
+        let onerror = Closure::wrap(Box::new(move || {
+            let error_msg = format!("Failed to load image: {}", url_for_error);
+            states_for_onerror.borrow_mut().insert(texture_id, TextureState::Failed(error_msg));
         }) as Box<dyn Fn()>);
 
         image.set_onload(Some(onload.as_ref().unchecked_ref()));
+        image.set_onerror(Some(onerror.as_ref().unchecked_ref()));
         onload.forget(); // Prevent closure from being dropped | 防止闭包被销毁
+        onerror.forget();
 
         image.set_src(url);
 
@@ -223,6 +269,56 @@ impl TextureManager {
         self.textures.contains_key(&id)
     }
 
+    /// 获取纹理加载状态
+    /// Get texture loading state
+    ///
+    /// 返回纹理的当前加载状态：Loading、Ready 或 Failed。
+    /// Returns the current loading state of the texture: Loading, Ready, or Failed.
+    #[inline]
+    pub fn get_texture_state(&self, id: u32) -> TextureState {
+        // ID 0 是默认纹理，始终就绪
+        // ID 0 is default texture, always ready
+        if id == 0 {
+            return TextureState::Ready;
+        }
+
+        self.texture_states
+            .borrow()
+            .get(&id)
+            .cloned()
+            .unwrap_or(TextureState::Failed("Texture not found".to_string()))
+    }
+
+    /// 检查纹理是否已就绪可用
+    /// Check if texture is ready to use
+    ///
+    /// 这是 `get_texture_state() == TextureState::Ready` 的便捷方法。
+    /// This is a convenience method for `get_texture_state() == TextureState::Ready`.
+    #[inline]
+    pub fn is_texture_ready(&self, id: u32) -> bool {
+        // ID 0 是默认纹理，始终就绪
+        // ID 0 is default texture, always ready
+        if id == 0 {
+            return true;
+        }
+
+        matches!(
+            self.texture_states.borrow().get(&id),
+            Some(TextureState::Ready)
+        )
+    }
+
+    /// 获取正在加载中的纹理数量
+    /// Get the number of textures currently loading
+    #[inline]
+    pub fn get_loading_count(&self) -> u32 {
+        self.texture_states
+            .borrow()
+            .values()
+            .filter(|s| matches!(s, TextureState::Loading))
+            .count() as u32
+    }
+
     /// Remove texture.
     /// 移除纹理。
     pub fn remove_texture(&mut self, id: u32) {
@@ -231,6 +327,8 @@ impl TextureManager {
         }
         // Also remove from path mapping | 同时从路径映射中移除
         self.path_to_id.retain(|_, &mut v| v != id);
+        // Remove state | 移除状态
+        self.texture_states.borrow_mut().remove(&id);
     }
 
     /// Load texture by path, returning texture ID.
@@ -308,6 +406,9 @@ impl TextureManager {
         // Clear path mapping | 清除路径映射
         self.path_to_id.clear();
 
+        // Clear texture states | 清除纹理状态
+        self.texture_states.borrow_mut().clear();
+
         // Reset ID counter (1 is reserved for first texture, 0 for default)
         // 重置ID计数器（1保留给第一个纹理，0给默认纹理）
         self.next_id = 1;