refactor: reorganize package structure and decouple framework packages (#338)

* refactor: reorganize package structure and decouple framework packages

## Package Structure Reorganization
- Reorganized 55 packages into categorized subdirectories:
  - packages/framework/ - Generic framework (Laya/Cocos compatible)
  - packages/engine/ - ESEngine core modules
  - packages/rendering/ - Rendering modules (WASM dependent)
  - packages/physics/ - Physics modules
  - packages/streaming/ - World streaming
  - packages/network-ext/ - Network extensions
  - packages/editor/ - Editor framework and plugins
  - packages/rust/ - Rust WASM engine
  - packages/tools/ - Build tools and SDK

## Framework Package Decoupling
- Decoupled behavior-tree and blueprint packages from ESEngine dependencies
- Created abstracted interfaces (IBTAssetManager, IBehaviorTreeAssetContent)
- ESEngine-specific code moved to esengine/ subpath exports
- Framework packages now usable with Cocos/Laya without ESEngine

## CI Configuration
- Updated CI to only type-check and lint framework packages
- Added type-check:framework and lint:framework scripts

## Breaking Changes
- Package import paths changed due to directory reorganization
- ESEngine integrations now use subpath imports (e.g., '@esengine/behavior-tree/esengine')

* fix: update es-engine file path after directory reorganization

* docs: update README to focus on framework over engine

* ci: only build framework packages, remove Rust/WASM dependencies

* fix: remove esengine subpath from behavior-tree and blueprint builds

ESEngine integration code will only be available in full engine builds.
Framework packages are now purely engine-agnostic.

* fix: move network-protocols to framework, build both in CI

* fix: update workflow paths from packages/core to packages/framework/core

* fix: exclude esengine folder from type-check in behavior-tree and blueprint

* fix: update network tsconfig references to new paths

* fix: add test:ci:framework to only test framework packages in CI

* fix: only build core and math npm packages in CI

* fix: exclude test files from CodeQL and fix string escaping security issue

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

@@ -0,0 +1,439 @@
+/**
+ * High-performance render batcher using Structure of Arrays (SoA) pattern.
+ * 使用结构数组 (SoA) 模式的高性能渲染批处理器。
+ *
+ * Optimizations:
+ * 优化：
+ * - Pre-allocated typed arrays to avoid per-frame GC
+ *   预分配类型数组以避免每帧 GC
+ * - SoA layout for cache-friendly access
+ *   SoA 布局提供缓存友好的访问
+ * - Object pool for SpriteRenderData when interface compatibility is needed
+ *   当需要接口兼容性时使用 SpriteRenderData 对象池
+ */
+
+import type { SpriteRenderData, MaterialOverrides } from '../types';
+
+/**
+ * Default maximum sprites per batch.
+ * 默认每批次最大精灵数。
+ */
+const DEFAULT_MAX_SPRITES = 10000;
+
+/**
+ * High-performance render batcher with SoA storage.
+ * 使用 SoA 存储的高性能渲染批处理器。
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RenderBatcher(10000);
+ *
+ * // Add sprites using SoA API (fastest) | 使用 SoA API 添加精灵（最快）
+ * batcher.addSpriteSoA(x, y, rot, sx, sy, ox, oy, texId, u0, v0, u1, v1, color, matId);
+ *
+ * // Or use object API for compatibility | 或使用对象 API 以保持兼容性
+ * batcher.addSprite(spriteData);
+ *
+ * // Get typed arrays for submission | 获取类型数组用于提交
+ * const { transforms, textureIds, uvs, colors, materialIds, count } = batcher.getBuffers();
+ *
+ * // At end of frame | 帧结束时
+ * batcher.clear();
+ * ```
+ */
+export class RenderBatcher {
+    // ===== SoA Buffers (pre-allocated) =====
+    // ===== SoA 缓冲区（预分配）=====
+
+    /** Transform data: [x, y, rotation, scaleX, scaleY, originX, originY] per sprite */
+    private _transforms: Float32Array;
+
+    /** Texture IDs | 纹理 ID */
+    private _textureIds: Uint32Array;
+
+    /** UV coordinates: [u0, v0, u1, v1] per sprite */
+    private _uvs: Float32Array;
+
+    /** Packed RGBA colors | 打包的 RGBA 颜色 */
+    private _colors: Uint32Array;
+
+    /** Material IDs | 材质 ID */
+    private _materialIds: Uint32Array;
+
+    /** Current sprite count | 当前精灵数量 */
+    private _count: number = 0;
+
+    /** Maximum sprites capacity | 最大精灵容量 */
+    private _capacity: number;
+
+    // ===== Object Pool for SpriteRenderData compatibility =====
+    // ===== SpriteRenderData 对象池用于兼容性 =====
+
+    /** Pool of reusable SpriteRenderData objects | 可复用的 SpriteRenderData 对象池 */
+    private _spritePool: SpriteRenderData[] = [];
+
+    /** Current pool index | 当前池索引 */
+    private _poolIndex: number = 0;
+
+    // ===== Material Overrides Storage =====
+    // ===== 材质覆盖存储 =====
+
+    /** Material overrides by sprite index | 按精灵索引存储的材质覆盖 */
+    private _materialOverrides: Map<number, MaterialOverrides> = new Map();
+
+    /** Clip rects by sprite index | 按精灵索引存储的裁剪矩形 */
+    private _clipRects: Map<number, { x: number; y: number; width: number; height: number }> = new Map();
+
+    /**
+     * Create a new render batcher with pre-allocated buffers.
+     * 创建具有预分配缓冲区的新渲染批处理器。
+     *
+     * @param capacity - Maximum sprites (default: 10000) | 最大精灵数（默认：10000）
+     */
+    constructor(capacity: number = DEFAULT_MAX_SPRITES) {
+        this._capacity = capacity;
+
+        // Pre-allocate all buffers | 预分配所有缓冲区
+        this._transforms = new Float32Array(capacity * 7);
+        this._textureIds = new Uint32Array(capacity);
+        this._uvs = new Float32Array(capacity * 4);
+        this._colors = new Uint32Array(capacity);
+        this._materialIds = new Uint32Array(capacity);
+
+        // Pre-populate object pool | 预填充对象池
+        this._initPool();
+    }
+
+    /**
+     * Initialize the object pool with reusable objects.
+     * 使用可复用对象初始化对象池。
+     */
+    private _initPool(): void {
+        // Create a smaller initial pool, expand on demand
+        // 创建较小的初始池，按需扩展
+        const initialPoolSize = Math.min(1000, this._capacity);
+        for (let i = 0; i < initialPoolSize; i++) {
+            this._spritePool.push(this._createSpriteData());
+        }
+    }
+
+    /**
+     * Create a new SpriteRenderData object.
+     * 创建新的 SpriteRenderData 对象。
+     */
+    private _createSpriteData(): SpriteRenderData {
+        return {
+            x: 0,
+            y: 0,
+            rotation: 0,
+            scaleX: 1,
+            scaleY: 1,
+            originX: 0.5,
+            originY: 0.5,
+            textureId: 0,
+            uv: [0, 0, 1, 1],
+            color: 0xFFFFFFFF,
+            materialId: 0
+        };
+    }
+
+    /**
+     * Get a SpriteRenderData object from pool.
+     * 从池中获取 SpriteRenderData 对象。
+     */
+    private _getFromPool(): SpriteRenderData {
+        if (this._poolIndex >= this._spritePool.length) {
+            // Expand pool | 扩展池
+            this._spritePool.push(this._createSpriteData());
+        }
+        return this._spritePool[this._poolIndex++];
+    }
+
+    // ===== High-Performance SoA API =====
+    // ===== 高性能 SoA API =====
+
+    /**
+     * Add a sprite using direct SoA parameters (fastest method).
+     * 使用直接 SoA 参数添加精灵（最快方法）。
+     *
+     * @returns Sprite index for additional data (overrides, clipRect) | 精灵索引用于附加数据
+     */
+    addSpriteSoA(
+        x: number,
+        y: number,
+        rotation: number,
+        scaleX: number,
+        scaleY: number,
+        originX: number,
+        originY: number,
+        textureId: number,
+        u0: number,
+        v0: number,
+        u1: number,
+        v1: number,
+        color: number,
+        materialId: number = 0
+    ): number {
+        if (this._count >= this._capacity) {
+            console.warn('RenderBatcher capacity exceeded | RenderBatcher 容量已满');
+            return -1;
+        }
+
+        const i = this._count;
+        const tOffset = i * 7;
+        const uvOffset = i * 4;
+
+        // Write transform data | 写入变换数据
+        this._transforms[tOffset] = x;
+        this._transforms[tOffset + 1] = y;
+        this._transforms[tOffset + 2] = rotation;
+        this._transforms[tOffset + 3] = scaleX;
+        this._transforms[tOffset + 4] = scaleY;
+        this._transforms[tOffset + 5] = originX;
+        this._transforms[tOffset + 6] = originY;
+
+        // Write texture ID | 写入纹理 ID
+        this._textureIds[i] = textureId;
+
+        // Write UV coordinates | 写入 UV 坐标
+        this._uvs[uvOffset] = u0;
+        this._uvs[uvOffset + 1] = v0;
+        this._uvs[uvOffset + 2] = u1;
+        this._uvs[uvOffset + 3] = v1;
+
+        // Write color and material | 写入颜色和材质
+        this._colors[i] = color;
+        this._materialIds[i] = materialId;
+
+        this._count++;
+        return i;
+    }
+
+    /**
+     * Set material overrides for a sprite.
+     * 为精灵设置材质覆盖。
+     *
+     * @param index - Sprite index from addSpriteSoA | 来自 addSpriteSoA 的精灵索引
+     * @param overrides - Material overrides | 材质覆盖
+     */
+    setMaterialOverrides(index: number, overrides: MaterialOverrides): void {
+        if (index >= 0 && index < this._count) {
+            this._materialOverrides.set(index, overrides);
+        }
+    }
+
+    /**
+     * Set clip rect for a sprite.
+     * 为精灵设置裁剪矩形。
+     *
+     * @param index - Sprite index from addSpriteSoA | 来自 addSpriteSoA 的精灵索引
+     * @param clipRect - Clip rectangle | 裁剪矩形
+     */
+    setClipRect(index: number, clipRect: { x: number; y: number; width: number; height: number }): void {
+        if (index >= 0 && index < this._count) {
+            this._clipRects.set(index, clipRect);
+        }
+    }
+
+    // ===== Object API (for compatibility) =====
+    // ===== 对象 API（用于兼容性）=====
+
+    /**
+     * Add a sprite using SpriteRenderData object.
+     * 使用 SpriteRenderData 对象添加精灵。
+     *
+     * This method is kept for backward compatibility but internally uses SoA storage.
+     * 此方法保留用于向后兼容，但内部使用 SoA 存储。
+     *
+     * @param sprite - Sprite render data | 精灵渲染数据
+     */
+    addSprite(sprite: SpriteRenderData): void {
+        const index = this.addSpriteSoA(
+            sprite.x,
+            sprite.y,
+            sprite.rotation,
+            sprite.scaleX,
+            sprite.scaleY,
+            sprite.originX,
+            sprite.originY,
+            sprite.textureId,
+            sprite.uv[0],
+            sprite.uv[1],
+            sprite.uv[2],
+            sprite.uv[3],
+            sprite.color,
+            sprite.materialId ?? 0
+        );
+
+        // Store optional data | 存储可选数据
+        if (index >= 0) {
+            if (sprite.materialOverrides) {
+                this._materialOverrides.set(index, sprite.materialOverrides);
+            }
+            if (sprite.clipRect) {
+                this._clipRects.set(index, sprite.clipRect);
+            }
+        }
+    }
+
+    /**
+     * Add multiple sprites.
+     * 添加多个精灵。
+     *
+     * @param sprites - Array of sprite render data | 精灵渲染数据数组
+     */
+    addSprites(sprites: SpriteRenderData[]): void {
+        for (let i = 0; i < sprites.length; i++) {
+            this.addSprite(sprites[i]);
+        }
+    }
+
+    // ===== Buffer Access =====
+    // ===== 缓冲区访问 =====
+
+    /**
+     * Get raw typed array buffers for direct submission to engine.
+     * 获取原始类型数组缓冲区以直接提交到引擎。
+     *
+     * Returns subarray views (zero-copy) for only the used portion.
+     * 返回仅已使用部分的 subarray 视图（零拷贝）。
+     */
+    getBuffers(): {
+        transforms: Float32Array;
+        textureIds: Uint32Array;
+        uvs: Float32Array;
+        colors: Uint32Array;
+        materialIds: Uint32Array;
+        count: number;
+    } {
+        return {
+            transforms: this._transforms.subarray(0, this._count * 7),
+            textureIds: this._textureIds.subarray(0, this._count),
+            uvs: this._uvs.subarray(0, this._count * 4),
+            colors: this._colors.subarray(0, this._count),
+            materialIds: this._materialIds.subarray(0, this._count),
+            count: this._count
+        };
+    }
+
+    /**
+     * Get sprites as SpriteRenderData array (for legacy compatibility).
+     * 获取精灵作为 SpriteRenderData 数组（用于旧版兼容性）。
+     *
+     * Uses object pool to avoid allocations.
+     * 使用对象池以避免分配。
+     *
+     * @returns Array of sprites from pool | 来自池的精灵数组
+     */
+    getSprites(): SpriteRenderData[] {
+        // Reset pool index to reuse objects | 重置池索引以复用对象
+        this._poolIndex = 0;
+
+        const result: SpriteRenderData[] = [];
+        for (let i = 0; i < this._count; i++) {
+            const sprite = this._getFromPool();
+            const tOffset = i * 7;
+            const uvOffset = i * 4;
+
+            // Fill from SoA buffers | 从 SoA 缓冲区填充
+            sprite.x = this._transforms[tOffset];
+            sprite.y = this._transforms[tOffset + 1];
+            sprite.rotation = this._transforms[tOffset + 2];
+            sprite.scaleX = this._transforms[tOffset + 3];
+            sprite.scaleY = this._transforms[tOffset + 4];
+            sprite.originX = this._transforms[tOffset + 5];
+            sprite.originY = this._transforms[tOffset + 6];
+
+            sprite.textureId = this._textureIds[i];
+
+            sprite.uv[0] = this._uvs[uvOffset];
+            sprite.uv[1] = this._uvs[uvOffset + 1];
+            sprite.uv[2] = this._uvs[uvOffset + 2];
+            sprite.uv[3] = this._uvs[uvOffset + 3];
+
+            sprite.color = this._colors[i];
+            sprite.materialId = this._materialIds[i];
+
+            // Attach optional data | 附加可选数据
+            sprite.materialOverrides = this._materialOverrides.get(i);
+            sprite.clipRect = this._clipRects.get(i);
+
+            result.push(sprite);
+        }
+
+        return result;
+    }
+
+    // ===== State =====
+    // ===== 状态 =====
+
+    /**
+     * Get sprite count.
+     * 获取精灵数量。
+     */
+    get count(): number {
+        return this._count;
+    }
+
+    /**
+     * Get capacity.
+     * 获取容量。
+     */
+    get capacity(): number {
+        return this._capacity;
+    }
+
+    /**
+     * Check if batch is empty.
+     * 检查批处理是否为空。
+     */
+    get isEmpty(): boolean {
+        return this._count === 0;
+    }
+
+    /**
+     * Clear all sprites from the batch.
+     * 清除批处理中的所有精灵。
+     *
+     * Does NOT deallocate buffers - they are reused next frame.
+     * 不会释放缓冲区 - 它们在下一帧被复用。
+     */
+    clear(): void {
+        this._count = 0;
+        this._poolIndex = 0;
+        this._materialOverrides.clear();
+        this._clipRects.clear();
+    }
+
+    /**
+     * Check if material overrides exist for any sprite.
+     * 检查是否有任何精灵存在材质覆盖。
+     */
+    hasMaterialOverrides(): boolean {
+        return this._materialOverrides.size > 0;
+    }
+
+    /**
+     * Get material overrides for a sprite index.
+     * 获取精灵索引的材质覆盖。
+     */
+    getMaterialOverrides(index: number): MaterialOverrides | undefined {
+        return this._materialOverrides.get(index);
+    }
+
+    /**
+     * Check if clip rects exist for any sprite.
+     * 检查是否有任何精灵存在裁剪矩形。
+     */
+    hasClipRects(): boolean {
+        return this._clipRects.size > 0;
+    }
+
+    /**
+     * Get clip rect for a sprite index.
+     * 获取精灵索引的裁剪矩形。
+     */
+    getClipRect(index: number): { x: number; y: number; width: number; height: number } | undefined {
+        return this._clipRects.get(index);
+    }
+}

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

@@ -0,0 +1,192 @@
+/**
+ * Sprite render helper utilities.
+ * 精灵渲染辅助工具。
+ */
+
+import { Entity, Component } from '@esengine/ecs-framework';
+import type { EngineBridge } from './EngineBridge';
+import { RenderBatcher } from './RenderBatcher';
+import { SpriteComponent } from '@esengine/sprite';
+import { getMaterialManager } from '@esengine/material-system';
+import type { SpriteRenderData } from '../types';
+
+/**
+ * Transform component interface.
+ * 变换组件接口。
+ *
+ * Your transform component should implement this interface.
+ * 你的变换组件应该实现此接口。
+ */
+export interface ITransformComponent {
+    position: { x: number; y: number; z?: number };
+    rotation: number | { x: number; y: number; z: number };
+    scale: { x: number; y: number; z?: number };
+    /** 世界位置（由 TransformSystem 计算，考虑父级变换） */
+    worldPosition?: { x: number; y: number; z?: number };
+    /** 世界旋转（由 TransformSystem 计算，考虑父级变换） */
+    worldRotation?: { x: number; y: number; z: number };
+    /** 世界缩放（由 TransformSystem 计算，考虑父级变换） */
+    worldScale?: { x: number; y: number; z?: number };
+}
+
+/**
+ * Helper class for rendering sprites (not an ECS System).
+ * 精灵渲染辅助类（非ECS系统）。
+ *
+ * Use this for manual control over rendering, or use EngineRenderSystem
+ * for automatic ECS integration.
+ * 用于手动控制渲染，或使用EngineRenderSystem进行自动ECS集成。
+ *
+ * @example
+ * ```typescript
+ * const bridge = new EngineBridge({ canvasId: 'canvas' });
+ * await bridge.initialize();
+ *
+ * const helper = new SpriteRenderHelper(bridge);
+ *
+ * // In game loop | 在游戏循环中
+ * helper.collectSprites(entities, Transform);
+ * helper.render();
+ * ```
+ */
+export class SpriteRenderHelper {
+    private bridge: EngineBridge;
+    private batcher: RenderBatcher;
+
+    /**
+     * Create a new sprite render helper.
+     * 创建新的精灵渲染辅助类。
+     *
+     * @param bridge - Engine bridge instance | 引擎桥接实例
+     */
+    constructor(bridge: EngineBridge) {
+        this.bridge = bridge;
+        this.batcher = new RenderBatcher();
+    }
+
+    /**
+     * Collect sprite data from entities.
+     * 从实体收集精灵数据。
+     *
+     * @param entities - Entities to process | 要处理的实体
+     * @param transformType - Transform component class | 变换组件类
+     */
+    collectSprites<T extends Component & ITransformComponent>(
+        entities: Entity[],
+        transformType: new () => T
+    ): void {
+        this.batcher.clear();
+
+        for (const entity of entities) {
+            const sprite = entity.getComponent(SpriteComponent);
+            const transform = entity.getComponent(transformType);
+
+            if (!sprite || !transform || !sprite.visible) {
+                continue;
+            }
+
+            // Calculate UV with flip | 计算带翻转的UV
+            let uv = sprite.uv;
+            if (sprite.flipX || sprite.flipY) {
+                uv = [...sprite.uv] as [number, number, number, number];
+                if (sprite.flipX) {
+                    const temp = uv[0];
+                    uv[0] = uv[2];
+                    uv[2] = temp;
+                }
+                if (sprite.flipY) {
+                    const temp = uv[1];
+                    uv[1] = uv[3];
+                    uv[3] = temp;
+                }
+            }
+
+            // Handle rotation as number or Vector3 (use z for 2D)
+            const rotation = typeof transform.rotation === 'number'
+                ? transform.rotation
+                : transform.rotation.z;
+
+            // Convert hex color string to packed RGBA
+            const color = this.hexToPackedColor(sprite.color, sprite.alpha);
+
+            // Get material ID from GUID (0 = default if not found or no GUID specified)
+            const materialId = sprite.materialGuid
+                ? getMaterialManager().getMaterialIdByPath(sprite.materialGuid)
+                : 0;
+
+            // Collect material overrides if any
+            const hasOverrides = sprite.hasOverrides();
+
+            const renderData: SpriteRenderData = {
+                x: transform.position.x,
+                y: transform.position.y,
+                rotation,
+                scaleX: transform.scale.x,
+                scaleY: transform.scale.y,
+                originX: sprite.originX,
+                originY: sprite.originY,
+                textureId: sprite.textureId,
+                uv,
+                color,
+                materialId,
+                // Only include overrides if there are any
+                ...(hasOverrides ? { materialOverrides: sprite.materialOverrides } : {})
+            };
+
+            this.batcher.addSprite(renderData);
+        }
+    }
+
+    /**
+     * Submit batched sprites and render.
+     * 提交批处理的精灵并渲染。
+     */
+    render(): void {
+        if (!this.batcher.isEmpty) {
+            const buffers = this.batcher.getBuffers();
+            this.bridge.submitSprites(
+                buffers.transforms, buffers.textureIds, buffers.uvs,
+                buffers.colors, buffers.materialIds, buffers.count
+            );
+        }
+        this.bridge.render();
+    }
+
+    /**
+     * Get the number of sprites to be rendered.
+     * 获取要渲染的精灵数量。
+     */
+    get spriteCount(): number {
+        return this.batcher.count;
+    }
+
+    /**
+     * Clear the current batch.
+     * 清除当前批处理。
+     */
+    clear(): void {
+        this.batcher.clear();
+    }
+
+    /**
+     * Convert hex color string to packed RGBA.
+     * 将十六进制颜色字符串转换为打包的RGBA。
+     */
+    private hexToPackedColor(hex: string, alpha: number): number {
+        let r = 255, g = 255, b = 255;
+        if (hex.startsWith('#')) {
+            const hexValue = hex.slice(1);
+            if (hexValue.length === 3) {
+                r = parseInt(hexValue[0] + hexValue[0], 16);
+                g = parseInt(hexValue[1] + hexValue[1], 16);
+                b = parseInt(hexValue[2] + hexValue[2], 16);
+            } else if (hexValue.length === 6) {
+                r = parseInt(hexValue.slice(0, 2), 16);
+                g = parseInt(hexValue.slice(2, 4), 16);
+                b = parseInt(hexValue.slice(4, 6), 16);
+            }
+        }
+        const a = Math.round(alpha * 255);
+        return ((a & 0xFF) << 24) | ((b & 0xFF) << 16) | ((g & 0xFF) << 8) | (r & 0xFF);
+    }
+}

packages/engine/ecs-engine-bindgen/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * ECS Engine Bindgen - Bridge layer between ECS Framework and Rust Engine.
+ * ECS引擎桥接层 - ECS框架与Rust引擎之间的桥接层。
+ *
+ * @packageDocumentation
+ */
+
+// Service tokens and interfaces (谁定义接口，谁导出 Token)
+export {
+    RenderSystemToken,
+    EngineIntegrationToken,
+    EngineBridgeToken,
+    // 新的单一职责服务令牌 | New single-responsibility service tokens
+    TextureServiceToken,
+    DynamicAtlasServiceToken,
+    CoordinateServiceToken,
+    RenderConfigServiceToken,
+    // 接口类型 | Interface types
+    type IRenderSystem,
+    type IEngineIntegration,
+    type IRenderDataProvider,
+    type ITextureService,
+    type IDynamicAtlasService,
+    type ICoordinateService,
+    type IRenderConfigService
+} from './tokens';
+
+export { EngineBridge } from './core/EngineBridge';
+export type { EngineBridgeConfig } from './core/EngineBridge';
+export { RenderBatcher } from './core/RenderBatcher';
+export { SpriteRenderHelper } from './core/SpriteRenderHelper';
+export type { ITransformComponent } from './core/SpriteRenderHelper';
+export { EngineRenderSystem, type TransformComponentType, type IUIRenderDataProvider, type GizmoDataProviderFn, type HasGizmoProviderFn, type ProviderRenderData, type AssetPathResolverFn } from './systems/EngineRenderSystem';
+export * from './types';

packages/engine/ecs-engine-bindgen/src/tokens.ts

@@ -0,0 +1,61 @@
+/**
+ * ecs-engine-bindgen 服务令牌
+ * ecs-engine-bindgen service tokens
+ */
+
+import { createServiceToken } from '@esengine/ecs-framework';
+import {
+    TextureServiceToken,
+    DynamicAtlasServiceToken,
+    CoordinateServiceToken,
+    RenderConfigServiceToken,
+    type ITextureService,
+    type IDynamicAtlasService,
+    type ICoordinateService,
+    type IRenderConfigService
+} from '@esengine/engine-core';
+import type { IRenderDataProvider as InternalIRenderDataProvider } from './systems/EngineRenderSystem';
+
+// 从 engine-core 重新导出 | Re-export from engine-core
+export {
+    TextureServiceToken,
+    DynamicAtlasServiceToken,
+    CoordinateServiceToken,
+    RenderConfigServiceToken
+};
+export type {
+    ITextureService,
+    IDynamicAtlasService,
+    ICoordinateService,
+    IRenderConfigService
+};
+
+export type IRenderDataProvider = InternalIRenderDataProvider;
+
+/**
+ * 渲染系统接口
+ * Render system interface
+ */
+export interface IRenderSystem {
+    addRenderDataProvider(provider: IRenderDataProvider): void;
+    removeRenderDataProvider(provider: IRenderDataProvider): void;
+}
+
+/**
+ * 引擎集成接口
+ * Engine integration interface
+ */
+export interface IEngineIntegration {
+    /** 通过相对路径加载纹理（用户脚本使用）| Load texture by relative path (for user scripts) */
+    loadTextureForComponent(texturePath: string): Promise<number>;
+    /** 通过 GUID 加载纹理（内部引用使用）| Load texture by GUID (for internal references) */
+    loadTextureByGuid(guid: string): Promise<number>;
+}
+
+export const RenderSystemToken = createServiceToken<IRenderSystem>('renderSystem');
+export const EngineIntegrationToken = createServiceToken<IEngineIntegration>('engineIntegration');
+
+// EngineBridge token - used by systems that need direct engine access
+// EngineBridge 令牌 - 供需要直接访问引擎的系统使用
+import type { EngineBridge } from './core/EngineBridge';
+export const EngineBridgeToken = createServiceToken<EngineBridge>('engineBridge');

packages/engine/ecs-engine-bindgen/src/types/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Type definitions for engine bridge.
+ * 引擎桥接层的类型定义。
+ */
+
+/**
+ * Material property override for rendering.
+ * 用于渲染的材质属性覆盖。
+ */
+export interface MaterialPropertyOverride {
+    /** Uniform type. | Uniform 类型。 */
+    type: 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int';
+    /** Uniform value. | Uniform 值。 */
+    value: number | number[];
+}
+
+/**
+ * Material overrides map.
+ * 材质覆盖映射。
+ */
+export type MaterialOverrides = Record<string, MaterialPropertyOverride>;
+
+/**
+ * Sprite render data for batch submission.
+ * 用于批量提交的精灵渲染数据。
+ */
+export interface SpriteRenderData {
+    /** Position X. | X位置。 */
+    x: number;
+    /** Position Y. | Y位置。 */
+    y: number;
+    /** Rotation in radians. | 旋转角度（弧度）。 */
+    rotation: number;
+    /** Scale X. | X缩放。 */
+    scaleX: number;
+    /** Scale Y. | Y缩放。 */
+    scaleY: number;
+    /** Origin X (0-1). | 原点X（0-1）。 */
+    originX: number;
+    /** Origin Y (0-1). | 原点Y（0-1）。 */
+    originY: number;
+    /** Texture ID. | 纹理ID。 */
+    textureId: number;
+    /** UV coordinates [u0, v0, u1, v1]. | UV坐标。 */
+    uv: [number, number, number, number];
+    /** Packed RGBA color. | 打包的RGBA颜色。 */
+    color: number;
+    /** Material ID (0 = default material). | 材质ID（0 = 默认材质）。 */
+    materialId?: number;
+    /**
+     * Material property overrides (instance level).
+     * 材质属性覆盖（实例级别）。
+     */
+    materialOverrides?: MaterialOverrides;
+    /**
+     * Clip rectangle for scissor test (screen coordinates).
+     * Content outside this rect will be clipped.
+     * 裁剪矩形用于 scissor test（屏幕坐标）。
+     * 此矩形外的内容将被裁剪。
+     */
+    clipRect?: { x: number; y: number; width: number; height: number };
+}
+
+/**
+ * Texture load request.
+ * 纹理加载请求。
+ */
+export interface TextureLoadRequest {
+    /** Unique texture ID. | 唯一纹理ID。 */
+    id: number;
+    /** Image URL. | 图片URL。 */
+    url: string;
+}
+
+/**
+ * Engine statistics.
+ * 引擎统计信息。
+ */
+export interface EngineStats {
+    /** Frames per second. | 每秒帧数。 */
+    fps: number;
+    /** Number of draw calls. | 绘制调用次数。 */
+    drawCalls: number;
+    /** Number of sprites rendered. | 渲染的精灵数量。 */
+    spriteCount: number;
+    /** Frame time in milliseconds. | 帧时间（毫秒）。 */
+    frameTime: number;
+}
+
+/**
+ * Camera configuration (2D).
+ * 相机配置（2D）。
+ */
+export interface CameraConfig {
+    /** Camera X position. | 相机X位置。 */
+    x: number;
+    /** Camera Y position. | 相机Y位置。 */
+    y: number;
+    /** Zoom level. | 缩放级别。 */
+    zoom: number;
+    /** Rotation in radians. | 旋转角度（弧度）。 */
+    rotation: number;
+}
+
+/**
+ * 3D Camera position.
+ * 3D 相机位置。
+ */
+export interface Camera3DPosition {
+    /** X coordinate. | X 坐标。 */
+    x: number;
+    /** Y coordinate. | Y 坐标。 */
+    y: number;
+    /** Z coordinate. | Z 坐标。 */
+    z: number;
+}
+
+/**
+ * 3D Camera rotation (Euler angles in degrees).
+ * 3D 相机旋转（欧拉角，角度制）。
+ */
+export interface Camera3DRotation {
+    /** Pitch angle in degrees. | 俯仰角（度）。 */
+    pitch: number;
+    /** Yaw angle in degrees. | 偏航角（度）。 */
+    yaw: number;
+    /** Roll angle in degrees. | 滚转角（度）。 */
+    roll: number;
+}
+
+/**
+ * Projection type for 3D camera.
+ * 3D 相机的投影类型。
+ */
+export enum ProjectionType {
+    /** Perspective projection. | 透视投影。 */
+    Perspective = 0,
+    /** Orthographic projection. | 正交投影。 */
+    Orthographic = 1,
+}
+
+/**
+ * Render mode.
+ * 渲染模式。
+ */
+export enum RenderMode {
+    /** 2D rendering mode. | 2D 渲染模式。 */
+    Mode2D = 0,
+    /** 3D rendering mode. | 3D 渲染模式。 */
+    Mode3D = 1,
+}

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

@@ -0,0 +1,816 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Initialize panic hook for better error messages in console.
+ * 初始化panic hook以在控制台显示更好的错误信息。
+ */
+export function init(): void;
+/**
+ * Render mode enumeration.
+ * 渲染模式枚举。
+ */
+export enum RenderMode {
+  /**
+   * 2D rendering mode (orthographic camera, no depth test).
+   * 2D渲染模式（正交相机，无深度测试）。
+   */
+  Mode2D = 0,
+  /**
+   * 3D rendering mode (perspective/orthographic camera, depth test enabled).
+   * 3D渲染模式（透视/正交相机，启用深度测试）。
+   */
+  Mode3D = 1,
+}
+/**
+ * Game engine main interface exposed to JavaScript.
+ * 暴露给JavaScript的游戏引擎主接口。
+ *
+ * This is the primary entry point for the engine from TypeScript/JavaScript.
+ * 这是从TypeScript/JavaScript访问引擎的主要入口点。
+ */
+export class GameEngine {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get camera state.
+   * 获取相机状态。
+   *
+   * # Returns | 返回
+   * Array of [x, y, zoom, rotation] | 数组 [x, y, zoom, rotation]
+   */
+  getCamera(): Float32Array;
+  /**
+   * Check if a shader exists.
+   * 检查着色器是否存在。
+   */
+  hasShader(shader_id: number): boolean;
+  /**
+   * Set camera position, zoom, and rotation.
+   * 设置相机位置、缩放和旋转。
+   *
+   * # Arguments | 参数
+   * * `x` - Camera X position | 相机X位置
+   * * `y` - Camera Y position | 相机Y位置
+   * * `zoom` - Zoom level | 缩放级别
+   * * `rotation` - Rotation in radians | 旋转角度（弧度）
+   */
+  setCamera(x: number, y: number, zoom: number, rotation: number): void;
+  /**
+   * Check if a key is currently pressed.
+   * 检查某个键是否当前被按下。
+   *
+   * # Arguments | 参数
+   * * `key_code` - The key code to check | 要检查的键码
+   */
+  isKeyDown(key_code: string): boolean;
+  /**
+   * Check if a material exists.
+   * 检查材质是否存在。
+   */
+  hasMaterial(material_id: number): boolean;
+  /**
+   * Load a texture from URL.
+   * 从URL加载纹理。
+   *
+   * # Arguments | 参数
+   * * `id` - Unique texture identifier | 唯一纹理标识符
+   * * `url` - Image URL to load | 要加载的图片URL
+   */
+  loadTexture(id: number, url: string): void;
+  /**
+   * Update input state. Should be called once per frame.
+   * 更新输入状态。应该每帧调用一次。
+   */
+  updateInput(): void;
+  /**
+   * Create a new game engine from external WebGL context.
+   * 从外部 WebGL 上下文创建引擎。
+   *
+   * This is designed for WeChat MiniGame and similar environments.
+   * 适用于微信小游戏等环境。
+   */
+  static fromExternal(gl_context: any, width: number, height: number): GameEngine;
+  /**
+   * Remove a shader.
+   * 移除着色器。
+   */
+  removeShader(shader_id: number): boolean;
+  /**
+   * Set grid visibility.
+   * 设置网格可见性。
+   */
+  setShowGrid(show: boolean): void;
+  /**
+   * Add a line gizmo.
+   * 添加线条Gizmo。
+   */
+  addGizmoLine(points: Float32Array, r: number, g: number, b: number, a: number, closed: boolean): void;
+  /**
+   * Add a rectangle gizmo outline.
+   * 添加矩形Gizmo边框。
+   *
+   * # Arguments | 参数
+   * * `x` - Center X position | 中心X位置
+   * * `y` - Center Y position | 中心Y位置
+   * * `width` - Rectangle width | 矩形宽度
+   * * `height` - Rectangle height | 矩形高度
+   * * `rotation` - Rotation in radians | 旋转角度（弧度）
+   * * `origin_x` - Origin X (0-1) | 原点X (0-1)
+   * * `origin_y` - Origin Y (0-1) | 原点Y (0-1)
+   * * `r`, `g`, `b`, `a` - Color (0.0-1.0) | 颜色
+   * * `show_handles` - Whether to show transform handles | 是否显示变换手柄
+   */
+  addGizmoRect(x: number, y: number, width: number, height: number, rotation: number, origin_x: number, origin_y: number, r: number, g: number, b: number, a: number, show_handles: boolean): void;
+  /**
+   * Compile and register a custom shader.
+   * 编译并注册自定义着色器。
+   *
+   * # Arguments | 参数
+   * * `vertex_source` - Vertex shader GLSL source | 顶点着色器GLSL源代码
+   * * `fragment_source` - Fragment shader GLSL source | 片段着色器GLSL源代码
+   *
+   * # Returns | 返回
+   * The shader ID for referencing this shader | 用于引用此着色器的ID
+   */
+  compileShader(vertex_source: string, fragment_source: string): number;
+  /**
+   * Get editor mode.
+   * 获取编辑器模式。
+   */
+  isEditorMode(): boolean;
+  /**
+   * Render sprites as overlay (without clearing screen).
+   * 渲染精灵作为叠加层（不清除屏幕）。
+   *
+   * This is used for UI rendering on top of the world content.
+   * 用于在世界内容上渲染 UI。
+   */
+  renderOverlay(): void;
+  /**
+   * Create and register a new material.
+   * 创建并注册新材质。
+   *
+   * # Arguments | 参数
+   * * `name` - Material name for debugging | 材质名称（用于调试）
+   * * `shader_id` - Shader ID to use | 使用的着色器ID
+   * * `blend_mode` - Blend mode: 0=None, 1=Alpha, 2=Additive, 3=Multiply, 4=Screen, 5=PremultipliedAlpha
+   *
+   * # Returns | 返回
+   * The material ID for referencing this material | 用于引用此材质的ID
+   */
+  createMaterial(name: string, shader_id: number, blend_mode: number): number;
+  /**
+   * Get current render mode.
+   * 获取当前渲染模式。
+   *
+   * Returns 0 for 2D mode, 1 for 3D mode.
+   * 返回 0 表示 2D 模式，1 表示 3D 模式。
+   */
+  getRenderMode(): number;
+  /**
+   * Check if 3D renderer is initialized.
+   * 检查 3D 渲染器是否已初始化。
+   */
+  has3DRenderer(): boolean;
+  /**
+   * Remove a material.
+   * 移除材质。
+   */
+  removeMaterial(material_id: number): boolean;
+  /**
+   * Render a 3D gizmo at the specified world position.
+   * 在指定的世界位置渲染 3D Gizmo。
+   *
+   * Only works in 3D render mode. The gizmo will be rendered
+   * with the current transform mode (move/rotate/scale).
+   * 仅在 3D 渲染模式下有效。Gizmo 将使用当前的变换模式渲染。
+   *
+   * # Arguments | 参数
+   * * `x`, `y`, `z` - World position | 世界位置
+   * * `scale` - Gizmo scale multiplier | Gizmo 缩放倍数
+   */
+  render3DGizmo(x: number, y: number, z: number, scale: number): void;
+  /**
+   * Resize a specific viewport.
+   * 调整特定视口大小。
+   */
+  resizeViewport(viewport_id: string, width: number, height: number): void;
+  /**
+   * Convert screen coordinates to world coordinates.
+   * 将屏幕坐标转换为世界坐标。
+   *
+   * # Arguments | 参数
+   * * `screen_x` - Screen X coordinate (0 = left edge of canvas)
+   * * `screen_y` - Screen Y coordinate (0 = top edge of canvas)
+   *
+   * # Returns | 返回
+   * Array of [world_x, world_y] | 数组 [world_x, world_y]
+   */
+  screenToWorld(screen_x: number, screen_y: number): Float32Array;
+  /**
+   * Set clear color (background color).
+   * 设置清除颜色（背景颜色）。
+   *
+   * # Arguments | 参数
+   * * `r`, `g`, `b`, `a` - Color components (0.0-1.0) | 颜色分量 (0.0-1.0)
+   */
+  setClearColor(r: number, g: number, b: number, a: number): void;
+  /**
+   * Set editor mode.
+   * 设置编辑器模式。
+   *
+   * When false (runtime mode), editor-only UI like grid, gizmos,
+   * and axis indicator are automatically hidden.
+   * 当为 false（运行时模式）时，编辑器专用 UI（如网格、gizmos、坐标轴指示器）会自动隐藏。
+   */
+  setEditorMode(is_editor: boolean): void;
+  /**
+   * Set render mode.
+   * 设置渲染模式。
+   *
+   * # Arguments | 参数
+   * * `mode` - 0 for 2D, 1 for 3D | 0 表示 2D，1 表示 3D
+   *
+   * When switching to 3D mode for the first time, the 3D renderer
+   * will be lazily initialized.
+   * 首次切换到 3D 模式时，3D 渲染器将被延迟初始化。
+   */
+  setRenderMode(mode: number): void;
+  /**
+   * Set gizmo visibility.
+   * 设置辅助工具可见性。
+   */
+  setShowGizmos(show: boolean): void;
+  /**
+   * Convert world coordinates to screen coordinates.
+   * 将世界坐标转换为屏幕坐标。
+   *
+   * # Arguments | 参数
+   * * `world_x` - World X coordinate
+   * * `world_y` - World Y coordinate
+   *
+   * # Returns | 返回
+   * Array of [screen_x, screen_y] | 数组 [screen_x, screen_y]
+   */
+  worldToScreen(world_x: number, world_y: number): Float32Array;
+  /**
+   * Add a circle gizmo outline.
+   * 添加圆形Gizmo边框。
+   */
+  addGizmoCircle(x: number, y: number, radius: number, r: number, g: number, b: number, a: number): void;
+  /**
+   * Get the graphics backend name (e.g., "WebGL2").
+   * 获取图形后端名称（如 "WebGL2"）。
+   */
+  getBackendName(): string;
+  /**
+   * Get all registered viewport IDs.
+   * 获取所有已注册的视口ID。
+   */
+  getViewportIds(): string[];
+  /**
+   * 检查纹理是否已就绪
+   * Check if texture is ready to use
+   *
+   * # Arguments | 参数
+   * * `id` - Texture ID | 纹理ID
+   */
+  isTextureReady(id: number): boolean;
+  /**
+   * Set scissor rect for clipping (screen coordinates, Y-down).
+   * 设置裁剪矩形（屏幕坐标，Y 轴向下）。
+   *
+   * Content outside this rect will be clipped.
+   * 此矩形外的内容将被裁剪。
+   *
+   * # Arguments | 参数
+   * * `x` - Left edge in screen coordinates | 屏幕坐标中的左边缘
+   * * `y` - Top edge in screen coordinates (Y-down) | 屏幕坐标中的上边缘（Y 向下）
+   * * `width` - Rect width | 矩形宽度
+   * * `height` - Rect height | 矩形高度
+   */
+  setScissorRect(x: number, y: number, width: number, height: number): void;
+  /**
+   * 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;
+  /**
+   * Make 3D camera look at a target position.
+   * 使 3D 相机朝向目标位置。
+   */
+  camera3DLookAt(target_x: number, target_y: number, target_z: number): void;
+  /**
+   * Get 3D camera field of view (in degrees).
+   * 获取 3D 相机视野角（角度制）。
+   */
+  getCamera3DFov(): number | undefined;
+  /**
+   * 获取纹理加载状态
+   * 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.
+   * 注册新视口。
+   *
+   * # Arguments | 参数
+   * * `id` - Unique viewport identifier | 唯一视口标识符
+   * * `canvas_id` - HTML canvas element ID | HTML canvas元素ID
+   */
+  registerViewport(id: string, canvas_id: string): void;
+  /**
+   * Set 3D camera field of view (in degrees).
+   * 设置 3D 相机视野角（角度制）。
+   *
+   * Only affects perspective projection mode.
+   * 仅影响透视投影模式。
+   */
+  setCamera3DFov(fov_degrees: number): void;
+  /**
+   * Set a material's vec2 uniform.
+   * 设置材质的vec2 uniform。
+   */
+  setMaterialVec2(material_id: number, name: string, x: number, y: number): boolean;
+  /**
+   * Set a material's vec3 uniform.
+   * 设置材质的vec3 uniform。
+   */
+  setMaterialVec3(material_id: number, name: string, x: number, y: number, z: number): boolean;
+  /**
+   * Set a material's vec4 uniform (also used for colors).
+   * 设置材质的vec4 uniform（也用于颜色）。
+   */
+  setMaterialVec4(material_id: number, name: string, x: number, y: number, z: number, w: number): boolean;
+  /**
+   * Submit mesh batch for rendering arbitrary 2D geometry.
+   * 提交网格批次进行任意 2D 几何体渲染。
+   *
+   * Used for rendering ellipses, polygons, and other complex shapes.
+   * 用于渲染椭圆、多边形和其他复杂形状。
+   *
+   * # Arguments | 参数
+   * * `positions` - Float32Array [x, y, ...] for each vertex
+   * * `uvs` - Float32Array [u, v, ...] for each vertex
+   * * `colors` - Uint32Array of packed RGBA colors (one per vertex)
+   * * `indices` - Uint16Array of triangle indices
+   * * `texture_id` - Texture ID to use (0 for white pixel)
+   */
+  submitMeshBatch(positions: Float32Array, uvs: Float32Array, colors: Uint32Array, indices: Uint16Array, texture_id: number): void;
+  /**
+   * Submit MSDF text batch for rendering.
+   * 提交 MSDF 文本批次进行渲染。
+   *
+   * # Arguments | 参数
+   * * `positions` - Float32Array [x, y, ...] for each vertex (4 per glyph)
+   * * `tex_coords` - Float32Array [u, v, ...] for each vertex
+   * * `colors` - Float32Array [r, g, b, a, ...] for each vertex
+   * * `outline_colors` - Float32Array [r, g, b, a, ...] for each vertex
+   * * `outline_widths` - Float32Array [width, ...] for each vertex
+   * * `texture_id` - Font atlas texture ID
+   * * `px_range` - Pixel range for MSDF shader
+   */
+  submitTextBatch(positions: Float32Array, tex_coords: Float32Array, colors: Float32Array, outline_colors: Float32Array, outline_widths: Float32Array, texture_id: number, px_range: number): void;
+  /**
+   * Clear all textures and reset state.
+   * 清除所有纹理并重置状态。
+   *
+   * This removes all loaded textures from GPU memory and resets
+   * the ID counter. Use with caution as all texture references
+   * will become invalid.
+   * 这会从GPU内存中移除所有已加载的纹理并重置ID计数器。
+   * 请谨慎使用，因为所有纹理引用都将变得无效。
+   */
+  clearAllTextures(): void;
+  /**
+   * Clear scissor rect (disable clipping).
+   * 清除裁剪矩形（禁用裁剪）。
+   */
+  clearScissorRect(): void;
+  /**
+   * Render to a specific viewport.
+   * 渲染到特定视口。
+   */
+  renderToViewport(viewport_id: string): void;
+  /**
+   * Set a material's color uniform (RGBA, 0.0-1.0).
+   * 设置材质的颜色uniform（RGBA，0.0-1.0）。
+   */
+  setMaterialColor(material_id: number, name: string, r: number, g: number, b: number, a: number): boolean;
+  /**
+   * Set a material's float uniform.
+   * 设置材质的浮点uniform。
+   */
+  setMaterialFloat(material_id: number, name: string, value: number): boolean;
+  /**
+   * Set transform tool mode.
+   * 设置变换工具模式。
+   *
+   * # Arguments | 参数
+   * * `mode` - 0=Select, 1=Move, 2=Rotate, 3=Scale
+   */
+  setTransformMode(mode: number): void;
+  /**
+   * Get the graphics backend version string.
+   * 获取图形后端版本字符串。
+   */
+  getBackendVersion(): string;
+  /**
+   * Get or load texture by path.
+   * 按路径获取或加载纹理。
+   *
+   * # Arguments | 参数
+   * * `path` - Image path/URL | 图片路径/URL
+   */
+  getOrLoadTextureByPath(path: string): number;
+  /**
+   * Get camera for a specific viewport.
+   * 获取特定视口的相机。
+   */
+  getViewportCamera(viewport_id: string): Float32Array | undefined;
+  /**
+   * Set the active viewport.
+   * 设置活动视口。
+   */
+  setActiveViewport(id: string): boolean;
+  /**
+   * Set camera for a specific viewport.
+   * 为特定视口设置相机。
+   */
+  setViewportCamera(viewport_id: string, x: number, y: number, zoom: number, rotation: number): void;
+  /**
+   * Set viewport configuration.
+   * 设置视口配置。
+   */
+  setViewportConfig(viewport_id: string, show_grid: boolean, show_gizmos: boolean): void;
+  /**
+   * Submit sprite batch data for rendering.
+   * 提交精灵批次数据进行渲染。
+   *
+   * # Arguments | 参数
+   * * `transforms` - Float32Array [x, y, rotation, scaleX, scaleY, originX, originY] per sprite
+   *                  每个精灵的变换数据
+   * * `texture_ids` - Uint32Array of texture IDs | 纹理ID数组
+   * * `uvs` - Float32Array [u0, v0, u1, v1] per sprite | 每个精灵的UV坐标
+   * * `colors` - Uint32Array of packed RGBA colors | 打包的RGBA颜色数组
+   * * `material_ids` - Uint32Array of material IDs (0 = default) | 材质ID数组（0 = 默认）
+   */
+  submitSpriteBatch(transforms: Float32Array, texture_ids: Uint32Array, uvs: Float32Array, colors: Uint32Array, material_ids: Uint32Array): void;
+  /**
+   * Unregister a viewport.
+   * 注销视口。
+   */
+  unregisterViewport(id: string): void;
+  /**
+   * Create a blank texture for dynamic atlas.
+   * 为动态图集创建空白纹理。
+   *
+   * This creates a texture that can be filled later using `updateTextureRegion`.
+   * Used for runtime atlas generation to batch UI elements with different textures.
+   * 创建一个可以稍后使用 `updateTextureRegion` 填充的纹理。
+   * 用于运行时图集生成，以批处理使用不同纹理的 UI 元素。
+   *
+   * # Arguments | 参数
+   * * `width` - Texture width in pixels (recommended: 2048) | 纹理宽度（推荐：2048）
+   * * `height` - Texture height in pixels (recommended: 2048) | 纹理高度（推荐：2048）
+   *
+   * # Returns | 返回
+   * The texture ID for the created blank texture | 创建的空白纹理ID
+   */
+  createBlankTexture(width: number, height: number): number;
+  /**
+   * Get maximum texture size supported by the backend.
+   * 获取后端支持的最大纹理尺寸。
+   */
+  getMaxTextureSize(): number;
+  /**
+   * Load texture by path, returning texture ID.
+   * 按路径加载纹理，返回纹理ID。
+   *
+   * # Arguments | 参数
+   * * `path` - Image path/URL to load | 要加载的图片路径/URL
+   */
+  loadTextureByPath(path: string): number;
+  /**
+   * Update a region of an existing texture with pixel data.
+   * 使用像素数据更新现有纹理的区域。
+   *
+   * This is used for dynamic atlas to copy individual textures into the atlas.
+   * 用于动态图集将单个纹理复制到图集纹理中。
+   *
+   * # Arguments | 参数
+   * * `id` - The texture ID to update | 要更新的纹理ID
+   * * `x` - X offset in the texture | 纹理中的X偏移
+   * * `y` - Y offset in the texture | 纹理中的Y偏移
+   * * `width` - Width of the region to update | 要更新的区域宽度
+   * * `height` - Height of the region to update | 要更新的区域高度
+   * * `pixels` - RGBA pixel data (Uint8Array, 4 bytes per pixel) | RGBA像素数据（每像素4字节）
+   */
+  updateTextureRegion(id: number, x: number, y: number, width: number, height: number, pixels: Uint8Array): void;
+  /**
+   * Compile a shader with a specific ID.
+   * 使用特定ID编译着色器。
+   */
+  compileShaderWithId(shader_id: number, vertex_source: string, fragment_source: string): void;
+  /**
+   * Get 3D camera position.
+   * 获取 3D 相机位置。
+   *
+   * Returns [x, y, z] or null if 3D renderer is not initialized.
+   * 返回 [x, y, z]，如果 3D 渲染器未初始化则返回 null。
+   */
+  getCamera3DPosition(): Float32Array | undefined;
+  /**
+   * Get 3D camera rotation as Euler angles (in degrees).
+   * 获取 3D 相机旋转的欧拉角（角度制）。
+   *
+   * Returns [pitch, yaw, roll] or null if 3D renderer is not initialized.
+   * 返回 [pitch, yaw, roll]，如果 3D 渲染器未初始化则返回 null。
+   */
+  getCamera3DRotation(): Float32Array | undefined;
+  /**
+   * Get texture ID by path.
+   * 按路径获取纹理ID。
+   *
+   * # Arguments | 参数
+   * * `path` - Image path to lookup | 要查找的图片路径
+   */
+  getTextureIdByPath(path: string): number | undefined;
+  /**
+   * Set 3D camera position.
+   * 设置 3D 相机位置。
+   */
+  setCamera3DPosition(x: number, y: number, z: number): void;
+  /**
+   * Set 3D camera rotation using Euler angles (in degrees).
+   * 使用欧拉角设置 3D 相机旋转（角度制）。
+   *
+   * # Arguments | 参数
+   * * `pitch` - Rotation around X axis (degrees) | X 轴旋转（角度）
+   * * `yaw` - Rotation around Y axis (degrees) | Y 轴旋转（角度）
+   * * `roll` - Rotation around Z axis (degrees) | Z 轴旋转（角度）
+   */
+  setCamera3DRotation(pitch: number, yaw: number, roll: number): void;
+  /**
+   * Create a material with a specific ID.
+   * 使用特定ID创建材质。
+   */
+  createMaterialWithId(material_id: number, name: string, shader_id: number, blend_mode: number): void;
+  /**
+   * Set a material's blend mode.
+   * 设置材质的混合模式。
+   *
+   * # Arguments | 参数
+   * * `blend_mode` - 0=None, 1=Alpha, 2=Additive, 3=Multiply, 4=Screen, 5=PremultipliedAlpha
+   */
+  setMaterialBlendMode(material_id: number, blend_mode: number): boolean;
+  /**
+   * Clear the texture path cache.
+   * 清除纹理路径缓存。
+   *
+   * This should be called when restoring scene snapshots to ensure
+   * textures are reloaded with correct IDs.
+   * 在恢复场景快照时应调用此方法，以确保纹理使用正确的ID重新加载。
+   */
+  clearTexturePathCache(): void;
+  /**
+   * Get texture size by path.
+   * 按路径获取纹理尺寸。
+   *
+   * Returns an array [width, height] or null if not found.
+   * 返回数组 [width, height]，如果未找到则返回 null。
+   *
+   * # Arguments | 参数
+   * * `path` - Image path to lookup | 要查找的图片路径
+   */
+  getTextureSizeByPath(path: string): Float32Array | undefined;
+  /**
+   * Set 3D camera projection type.
+   * 设置 3D 相机投影类型。
+   *
+   * # Arguments | 参数
+   * * `projection_type` - 0 for Perspective, 1 for Orthographic
+   * * `ortho_size` - Half-height of orthographic view (only used when projection_type = 1)
+   */
+  setCamera3DProjection(projection_type: number, ortho_size: number): void;
+  /**
+   * 获取正在加载中的纹理数量
+   * Get the number of textures currently loading
+   */
+  getTextureLoadingCount(): number;
+  /**
+   * Set 3D camera near and far clip planes.
+   * 设置 3D 相机近裁剪面和远裁剪面。
+   */
+  setCamera3DClipPlanes(near: number, far: number): void;
+  /**
+   * Create a new game engine instance.
+   * 创建新的游戏引擎实例。
+   *
+   * # Arguments | 参数
+   * * `canvas_id` - The HTML canvas element ID | HTML canvas元素ID
+   *
+   * # Returns | 返回
+   * A new GameEngine instance or an error | 新的GameEngine实例或错误
+   */
+  constructor(canvas_id: string);
+  /**
+   * Clear the screen with specified color.
+   * 使用指定颜色清除屏幕。
+   *
+   * # Arguments | 参数
+   * * `r` - Red component (0.0-1.0) | 红色分量
+   * * `g` - Green component (0.0-1.0) | 绿色分量
+   * * `b` - Blue component (0.0-1.0) | 蓝色分量
+   * * `a` - Alpha component (0.0-1.0) | 透明度分量
+   */
+  clear(r: number, g: number, b: number, a: number): void;
+  /**
+   * Render the current frame.
+   * 渲染当前帧。
+   */
+  render(): void;
+  /**
+   * Resize viewport.
+   * 调整视口大小。
+   *
+   * # Arguments | 参数
+   * * `width` - New viewport width | 新视口宽度
+   * * `height` - New viewport height | 新视口高度
+   */
+  resize(width: number, height: number): void;
+  /**
+   * Render 3D content.
+   * 渲染 3D 内容。
+   *
+   * Should be called after submitting 3D meshes.
+   * 应在提交 3D 网格后调用。
+   */
+  render3D(): void;
+  /**
+   * Resize 3D renderer viewport.
+   * 调整 3D 渲染器视口大小。
+   */
+  resize3D(width: number, height: number): void;
+  /**
+   * Get canvas width.
+   * 获取画布宽度。
+   */
+  readonly width: number;
+  /**
+   * Get canvas height.
+   * 获取画布高度。
+   */
+  readonly height: number;
+  /**
+   * Submit a 3D mesh for rendering.
+   * 提交 3D 网格进行渲染。
+   *
+   * @param vertices - Interleaved vertex data [x,y,z, u,v, r,g,b,a, nx,ny,nz] * count
+   * @param indices - Triangle indices
+   * @param transform - 4x4 transformation matrix (column-major)
+   * @param material_id - Material ID
+   * @param texture_id - Texture ID
+   */
+  submitMesh3D(vertices: Float32Array, indices: Uint32Array, transform: Float32Array, material_id: number, texture_id: number): void;
+  /**
+   * Submit a simple 3D mesh for rendering (without normals).
+   * 提交简单 3D 网格进行渲染（不含法线）。
+   *
+   * @param vertices - Interleaved vertex data [x,y,z, u,v, r,g,b,a] * count
+   * @param indices - Triangle indices
+   * @param transform - 4x4 transformation matrix (column-major)
+   * @param material_id - Material ID
+   * @param texture_id - Texture ID
+   */
+  submitSimpleMesh3D(vertices: Float32Array, indices: Uint32Array, transform: Float32Array, material_id: number, texture_id: number): void;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_gameengine_free: (a: number, b: number) => void;
+  readonly gameengine_addGizmoCapsule: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+  readonly gameengine_addGizmoCircle: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+  readonly gameengine_addGizmoLine: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+  readonly gameengine_addGizmoRect: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => void;
+  readonly gameengine_camera3DLookAt: (a: number, b: number, c: number, d: number) => void;
+  readonly gameengine_clear: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_clearAllTextures: (a: number) => void;
+  readonly gameengine_clearScissorRect: (a: number) => void;
+  readonly gameengine_clearTexturePathCache: (a: number) => void;
+  readonly gameengine_compileShader: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+  readonly gameengine_compileShaderWithId: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+  readonly gameengine_createBlankTexture: (a: number, b: number, c: number) => [number, number, number];
+  readonly gameengine_createMaterial: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly gameengine_createMaterialWithId: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly gameengine_fromExternal: (a: any, b: number, c: number) => [number, number, number];
+  readonly gameengine_getBackendName: (a: number) => [number, number];
+  readonly gameengine_getBackendVersion: (a: number) => [number, number];
+  readonly gameengine_getCamera: (a: number) => [number, number];
+  readonly gameengine_getCamera3DFov: (a: number) => number;
+  readonly gameengine_getCamera3DPosition: (a: number) => [number, number];
+  readonly gameengine_getCamera3DRotation: (a: number) => [number, number];
+  readonly gameengine_getMaxTextureSize: (a: number) => number;
+  readonly gameengine_getOrLoadTextureByPath: (a: number, b: number, c: number) => [number, number, number];
+  readonly gameengine_getRenderMode: (a: number) => number;
+  readonly gameengine_getTextureIdByPath: (a: number, b: number, c: number) => number;
+  readonly gameengine_getTextureLoadingCount: (a: number) => number;
+  readonly gameengine_getTextureSizeByPath: (a: number, b: number, c: number) => any;
+  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_has3DRenderer: (a: number) => number;
+  readonly gameengine_hasMaterial: (a: number, b: number) => number;
+  readonly gameengine_hasShader: (a: number, b: number) => number;
+  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];
+  readonly gameengine_registerViewport: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+  readonly gameengine_removeMaterial: (a: number, b: number) => number;
+  readonly gameengine_removeShader: (a: number, b: number) => number;
+  readonly gameengine_render: (a: number) => [number, number];
+  readonly gameengine_render3D: (a: number) => [number, number];
+  readonly gameengine_render3DGizmo: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_renderOverlay: (a: number) => [number, number];
+  readonly gameengine_renderToViewport: (a: number, b: number, c: number) => [number, number];
+  readonly gameengine_resize: (a: number, b: number, c: number) => void;
+  readonly gameengine_resize3D: (a: number, b: number, c: number) => void;
+  readonly gameengine_resizeViewport: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_screenToWorld: (a: number, b: number, c: number) => [number, number];
+  readonly gameengine_setActiveViewport: (a: number, b: number, c: number) => number;
+  readonly gameengine_setCamera: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_setCamera3DClipPlanes: (a: number, b: number, c: number) => void;
+  readonly gameengine_setCamera3DFov: (a: number, b: number) => void;
+  readonly gameengine_setCamera3DPosition: (a: number, b: number, c: number, d: number) => void;
+  readonly gameengine_setCamera3DProjection: (a: number, b: number, c: number) => void;
+  readonly gameengine_setCamera3DRotation: (a: number, b: number, c: number, d: number) => void;
+  readonly gameengine_setClearColor: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_setEditorMode: (a: number, b: number) => void;
+  readonly gameengine_setMaterialBlendMode: (a: number, b: number, c: number) => number;
+  readonly gameengine_setMaterialColor: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+  readonly gameengine_setMaterialFloat: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly gameengine_setMaterialVec2: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
+  readonly gameengine_setMaterialVec3: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
+  readonly gameengine_setMaterialVec4: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+  readonly gameengine_setRenderMode: (a: number, b: number) => [number, number];
+  readonly gameengine_setScissorRect: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_setShowGizmos: (a: number, b: number) => void;
+  readonly gameengine_setShowGrid: (a: number, b: number) => void;
+  readonly gameengine_setTransformMode: (a: number, b: number) => void;
+  readonly gameengine_setViewportCamera: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+  readonly gameengine_setViewportConfig: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly gameengine_submitMeshBatch: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number];
+  readonly gameengine_submitSpriteBatch: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
+  readonly gameengine_submitTextBatch: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => [number, number];
+  readonly gameengine_unregisterViewport: (a: number, b: number, c: number) => void;
+  readonly gameengine_updateInput: (a: number) => void;
+  readonly gameengine_updateTextureRegion: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+  readonly gameengine_width: (a: number) => number;
+  readonly gameengine_worldToScreen: (a: number, b: number, c: number) => [number, number];
+  readonly init: () => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h256074d77f4ce876: (a: number, b: number) => void;
+  readonly wasm_bindgen__closure__destroy__h14ac3db10f717d1a: (a: number, b: number) => void;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_externrefs: WebAssembly.Table;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __externref_table_dealloc: (a: number) => void;
+  readonly __externref_drop_slice: (a: number, b: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;