feat: 添加跨平台运行时、资产系统和UI适配功能 (#256)

* feat(platform-common): 添加WASM加载器和环境检测API * feat(rapier2d): 新增Rapier2D WASM绑定包 * feat(physics-rapier2d): 添加跨平台WASM加载器 * feat(asset-system): 添加运行时资产目录和bundle格式 * feat(asset-system-editor): 新增编辑器资产管理包 * feat(editor-core): 添加构建系统和模块管理 * feat(editor-app): 重构浏览器预览使用import maps * feat(platform-web): 添加BrowserRuntime和资产读取 * feat(engine): 添加材质系统和着色器管理 * feat(material): 新增材质系统和着色器编辑器 * feat(tilemap): 增强tilemap编辑器和动画系统 * feat(modules): 添加module.json配置 * feat(core): 添加module.json和类型定义更新 * chore: 更新依赖和构建配置 * refactor(plugins): 更新插件模板使用ModuleManifest * chore: 添加第三方依赖库 * chore: 移除BehaviourTree-ai和ecs-astar子模块 * docs: 更新README和文档主题样式 * fix: 修复Rust文档测试和添加rapier2d WASM绑定 * fix(tilemap-editor): 修复画布高DPI屏幕分辨率适配问题 * feat(ui): 添加UI屏幕适配系统(CanvasScaler/SafeArea) * fix(ecs-engine-bindgen): 添加缺失的ecs-framework-math依赖 * fix: 添加缺失的包依赖修复CI构建 * fix: 修复CodeQL检测到的代码问题 * fix: 修复构建错误和缺失依赖 * fix: 修复类型检查错误 * fix(material-system): 修复tsconfig配置支持TypeScript项目引用 * fix(editor-core): 修复Rollup构建配置添加tauri external * fix: 修复CodeQL检测到的代码问题 * fix: 修复CodeQL检测到的代码问题
2025-12-03 22:15:22 +08:00
parent caf7622aa0
commit 63f006ab62
496 changed files with 77601 additions and 4067 deletions
--- a/packages/ecs-engine-bindgen/module.json
+++ b/packages/ecs-engine-bindgen/module.json
@@ -0,0 +1,21 @@
+{
+  "id": "ecs-engine-bindgen",
+  "name": "@esengine/ecs-engine-bindgen",
+  "displayName": "Engine Bindgen",
+  "description": "Bridge between ECS and Rust Engine | ECS 与 Rust 引擎之间的桥接层",
+  "version": "0.1.0",
+  "category": "Core",
+  "icon": "Link",
+  "tags": ["engine", "bindgen", "wasm", "rendering"],
+  "isCore": true,
+  "defaultEnabled": true,
+  "isEngineModule": true,
+  "canContainContent": false,
+  "platforms": ["web", "desktop"],
+  "dependencies": ["core", "math"],
+  "exports": {
+    "other": ["EngineBridge", "EngineRenderSystem", "CameraSystem"]
+  },
+  "requiresWasm": true,
+  "outputPath": "dist/index.js"
+}
--- a/packages/ecs-engine-bindgen/package.json
+++ b/packages/ecs-engine-bindgen/package.json
@@ -39,10 +39,12 @@
    },
    "devDependencies": {
        "@esengine/ecs-framework": "workspace:*",
+        "@esengine/ecs-framework-math": "workspace:*",
        "@esengine/engine-core": "workspace:*",
        "@esengine/sprite": "workspace:*",
        "@esengine/camera": "workspace:*",
        "@esengine/asset-system": "workspace:*",
+        "@esengine/material-system": "workspace:*",
        "tsup": "^8.5.1",
        "typescript": "^5.8.0",
        "rimraf": "^5.0.0"
--- a/packages/ecs-engine-bindgen/src/core/EngineBridge.ts
+++ b/packages/ecs-engine-bindgen/src/core/EngineBridge.ts
@@ -58,6 +58,7 @@ export class EngineBridge implements IEngineBridge {
    private textureIdBuffer: Uint32Array;
    private uvBuffer: Float32Array;
    private colorBuffer: Uint32Array;
+    private materialIdBuffer: Uint32Array;

    // Statistics | 统计信息
    private stats: EngineStats = {
@@ -92,6 +93,7 @@ export class EngineBridge implements IEngineBridge {
        this.textureIdBuffer = new Uint32Array(maxSprites);
        this.uvBuffer = new Float32Array(maxSprites * 4); // u0, v0, u1, v1
        this.colorBuffer = new Uint32Array(maxSprites);
+        this.materialIdBuffer = new Uint32Array(maxSprites);
    }

    /**
@@ -235,6 +237,9 @@ export class EngineBridge implements IEngineBridge {

            // Color | 颜色
            this.colorBuffer[i] = sprite.color;
+
+            // Material ID (0 = default) | 材质ID（0 = 默认）
+            this.materialIdBuffer[i] = sprite.materialId ?? 0;
        }

        // Submit to engine (single WASM call) | 提交到引擎（单次WASM调用）
@@ -242,7 +247,8 @@ export class EngineBridge implements IEngineBridge {
            this.transformBuffer.subarray(0, count * 7),
            this.textureIdBuffer.subarray(0, count),
            this.uvBuffer.subarray(0, count * 4),
-            this.colorBuffer.subarray(0, count)
+            this.colorBuffer.subarray(0, count),
+            this.materialIdBuffer.subarray(0, count)
        );

        this.stats.spriteCount = count;
--- a/packages/ecs-engine-bindgen/src/core/RenderBatcher.ts
+++ b/packages/ecs-engine-bindgen/src/core/RenderBatcher.ts
@@ -74,10 +74,14 @@ export class RenderBatcher {
     * @returns Sorted array of sprites | 排序后的精灵数组
     */
    getSprites(): SpriteRenderData[] {
-        // Sort by texture ID for better batching (fewer texture switches)
-        // 按纹理ID排序以获得更好的批处理效果（减少纹理切换）
+        // Sort by material ID first, then texture ID for better batching
+        // 先按材质ID排序，再按纹理ID排序以获得更好的批处理效果
        if (!this.sortByZ) {
-            this.sprites.sort((a, b) => a.textureId - b.textureId);
+            this.sprites.sort((a, b) => {
+                const materialDiff = (a.materialId || 0) - (b.materialId || 0);
+                if (materialDiff !== 0) return materialDiff;
+                return a.textureId - b.textureId;
+            });
        }
        return this.sprites;
    }
--- a/packages/ecs-engine-bindgen/src/core/SpriteRenderHelper.ts
+++ b/packages/ecs-engine-bindgen/src/core/SpriteRenderHelper.ts
@@ -7,6 +7,7 @@ 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';

 /**
@@ -108,6 +109,14 @@ export class SpriteRenderHelper {
            // Convert hex color string to packed RGBA
            const color = this.hexToPackedColor(sprite.color, sprite.alpha);

+            // Get material ID from path (0 = default if not found or no path specified)
+            const materialId = sprite.material
+                ? getMaterialManager().getMaterialIdByPath(sprite.material)
+                : 0;
+
+            // Collect material overrides if any
+            const hasOverrides = sprite.hasOverrides();
+
            const renderData: SpriteRenderData = {
                x: transform.position.x,
                y: transform.position.y,
@@ -118,7 +127,10 @@ export class SpriteRenderHelper {
                originY: sprite.originY,
                textureId: sprite.textureId,
                uv,
-                color
+                color,
+                materialId,
+                // Only include overrides if there are any
+                ...(hasOverrides ? { materialOverrides: sprite.materialOverrides } : {})
            };

            this.batcher.addSprite(renderData);
--- a/packages/ecs-engine-bindgen/src/systems/EngineRenderSystem.ts
+++ b/packages/ecs-engine-bindgen/src/systems/EngineRenderSystem.ts
@@ -5,8 +5,10 @@

 import { EntitySystem, Matcher, Entity, ComponentType, ECSSystem, Component, Core } from '@esengine/ecs-framework';
 import { TransformComponent } from '@esengine/engine-core';
+import { Color } from '@esengine/ecs-framework-math';
 import { SpriteComponent } from '@esengine/sprite';
 import { CameraComponent } from '@esengine/camera';
+import { getMaterialManager } from '@esengine/material-system';
 import type { EngineBridge } from '../core/EngineBridge';
 import { RenderBatcher } from '../core/RenderBatcher';
 import type { SpriteRenderData } from '../types';
@@ -279,7 +281,7 @@ export class EngineRenderSystem extends EntitySystem {
                : (typeof transform.rotation === 'number' ? transform.rotation : transform.rotation.z);

            // Convert hex color string to packed RGBA | 将十六进制颜色字符串转换为打包的RGBA
-            const color = this.hexToPackedColor(sprite.color, sprite.alpha);
+            const color = Color.packHexAlpha(sprite.color, sprite.alpha);

            // Get texture ID from sprite component
            // 从精灵组件获取纹理ID
@@ -290,6 +292,16 @@ export class EngineRenderSystem extends EntitySystem {
                textureId = this.bridge.getOrLoadTextureByPath(sprite.texture);
            }

+            // Get material ID from path (0 = default if not found or no path specified)
+            // 从路径获取材质 ID（0 = 默认，如果未找到或未指定路径）
+            const materialId = sprite.material
+                ? getMaterialManager().getMaterialIdByPath(sprite.material)
+                : 0;
+
+            // Collect material overrides if any
+            // 收集材质覆盖（如果有）
+            const hasOverrides = sprite.hasOverrides();
+
            // Pass actual display dimensions (sprite size * world transform scale)
            // 传递实际显示尺寸（sprite尺寸 * 世界变换缩放）
            const renderData: SpriteRenderData = {
@@ -302,7 +314,11 @@ export class EngineRenderSystem extends EntitySystem {
                originY: sprite.anchorY,
                textureId,
                uv,
-                color
+                color,
+                materialId,
+                // Only include overrides if there are any
+                // 仅在有覆盖时包含
+                ...(hasOverrides ? { materialOverrides: sprite.materialOverrides } : {})
            };

            renderItems.push({ sortingOrder: sprite.sortingOrder, sprites: [renderData] });
@@ -1054,32 +1070,6 @@ export class EngineRenderSystem extends EntitySystem {
        return this.transformMode;
    }

-    /**
-     * Convert hex color string to packed RGBA.
-     * 将十六进制颜色字符串转换为打包的RGBA。
-     */
-    private hexToPackedColor(hex: string, alpha: number): number {
-        let r = 255, g = 255, b = 255;
-
-        if (typeof hex === 'string' && 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);
-        // Pack as 0xAABBGGRR for WebGL
-        return ((a & 0xFF) << 24) | ((b & 0xFF) << 16) | ((g & 0xFF) << 8) | (r & 0xFF);
-    }
-
-
    /**
     * Register a render data provider.
     * 注册渲染数据提供者。
--- a/packages/ecs-engine-bindgen/src/types/index.ts
+++ b/packages/ecs-engine-bindgen/src/types/index.ts
@@ -3,6 +3,23 @@
 * 引擎桥接层的类型定义。
 */

+/**
+ * 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.
 * 用于批量提交的精灵渲染数据。
@@ -28,6 +45,13 @@ export interface SpriteRenderData {
    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;
 }

 /**
--- a/packages/ecs-engine-bindgen/src/wasm/es_engine.d.ts
+++ b/packages/ecs-engine-bindgen/src/wasm/es_engine.d.ts
@@ -23,6 +23,11 @@ export class GameEngine {
   * 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.
   * 设置相机位置、缩放和旋转。
@@ -42,6 +47,11 @@ export class GameEngine {
   * * `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加载纹理。
@@ -64,6 +74,11 @@ export class GameEngine {
   * 适用于微信小游戏等环境。
   */
  static fromExternal(gl_context: any, width: number, height: number): GameEngine;
+  /**
+   * Remove a shader.
+   * 移除着色器。
+   */
+  removeShader(shader_id: number): boolean;
  /**
   * Set grid visibility.
   * 设置网格可见性。
@@ -90,6 +105,18 @@ export class GameEngine {
   * * `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;
  /**
   * Render sprites as overlay (without clearing screen).
   * 渲染精灵作为叠加层（不清除屏幕）。
@@ -98,6 +125,24 @@ export class GameEngine {
   * 用于在世界内容上渲染 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;
+  /**
+   * Remove a material.
+   * 移除材质。
+   */
+  removeMaterial(material_id: number): boolean;
  /**
   * Resize a specific viewport.
   * 调整特定视口大小。
@@ -140,11 +185,36 @@ export class GameEngine {
   * * `canvas_id` - HTML canvas element ID | HTML canvas元素ID
   */
  registerViewport(id: string, canvas_id: string): 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;
  /**
   * 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.
   * 设置变换工具模式。
@@ -191,8 +261,9 @@ export class GameEngine {
   * * `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): void;
+  submitSpriteBatch(transforms: Float32Array, texture_ids: Uint32Array, uvs: Float32Array, colors: Uint32Array, material_ids: Uint32Array): void;
  /**
   * Unregister a viewport.
   * 注销视口。
@@ -206,6 +277,11 @@ export class GameEngine {
   * * `path` - Image path/URL to load | 要加载的图片路径/URL
   */
  loadTextureByPath(path: string): number;
+  /**
+   * Compile a shader with a specific ID.
+   * 使用特定ID编译着色器。
+   */
+  compileShaderWithId(shader_id: number, vertex_source: string, fragment_source: string): void;
  /**
   * Get texture ID by path.
   * 按路径获取纹理ID。
@@ -214,6 +290,19 @@ export class GameEngine {
   * * `path` - Image path to lookup | 要查找的图片路径
   */
  getTextureIdByPath(path: string): number | undefined;
+  /**
+   * 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;
  /**
   * Create a new game engine instance.
   * 创建新的游戏引擎实例。
@@ -272,18 +361,26 @@ export interface InitOutput {
  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_clear: (a: number, b: number, c: number, d: number, e: 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_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_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_getViewportCamera: (a: number, b: number, c: number) => [number, number];
  readonly gameengine_getViewportIds: (a: number) => [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_isKeyDown: (a: number, b: number, c: 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_renderOverlay: (a: number) => [number, number];
  readonly gameengine_renderToViewport: (a: number, b: number, c: number) => [number, number];
@@ -292,12 +389,18 @@ export interface InitOutput {
  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_setClearColor: (a: number, b: number, c: number, d: number, e: 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_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_submitSpriteBatch: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: 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_unregisterViewport: (a: number, b: number, c: number) => void;
  readonly gameengine_updateInput: (a: number) => void;
  readonly gameengine_width: (a: number) => number;