CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 纹理路径稳定 ID 与架构改进 (#305)

Browse Source 
* feat(asset-system): 实现路径稳定 ID 生成器

使用 FNV-1a hash 算法为纹理生成稳定的运行时 ID：
- 新增 _pathIdCache 静态缓存，跨 Play/Stop 循环保持稳定
- 新增 getStableIdForPath() 方法，相同路径永远返回相同 ID
- 修改 loadTextureForComponent/loadTextureByGuid 使用稳定 ID
- clearTextureMappings() 不再清除 _pathIdCache

这解决了 Play/Stop 后纹理 ID 失效的根本问题。

* fix(runtime-core): 移除 Play/Stop 循环中的 clearTextureMappings 调用

使用路径稳定 ID 后，不再需要在快照保存/恢复时清除纹理缓存：
- saveSceneSnapshot() 移除 clearTextureMappings() 调用
- restoreSceneSnapshot() 移除 clearTextureMappings() 调用
- 组件保存的 textureId 在 Play/Stop 后仍然有效

* fix(editor-core): 修复场景切换时的资源泄漏

在 openScene() 加载新场景前先卸载旧场景资源：
- 调用 sceneResourceManager.unloadSceneResources() 释放旧资源
- 使用引用计数机制，仅卸载不再被引用的资源
- 路径稳定 ID 缓存不受影响，保持 ID 稳定性

* fix(runtime-core): 修复 PluginManager 组件注册类型错误

将 ComponentRegistry 类改为 GlobalComponentRegistry 实例：
- registerComponents() 期望 IComponentRegistry 接口实例
- GlobalComponentRegistry 是 ComponentRegistry 的全局实例

* refactor(core): 提取 IComponentRegistry 接口

将组件注册表抽象为接口，支持场景级组件注册：
- 新增 IComponentRegistry 接口定义
- Scene 持有独立的 componentRegistry 实例
- 支持从 GlobalComponentRegistry 克隆
- 各系统支持传入自定义注册表

* refactor(engine-core): 改进插件服务注册机制

- 更新 IComponentRegistry 类型引用
- 优化 PluginServiceRegistry 服务管理

* refactor(modules): 适配新的组件注册接口

更新各模块 RuntimeModule 使用 IComponentRegistry 接口：
- audio, behavior-tree, camera
- sprite, tilemap, world-streaming

* fix(physics-rapier2d): 修复物理插件组件注册

- PhysicsEditorPlugin 添加 runtimeModule 引用
- 适配 IComponentRegistry 接口
- 修复物理组件在场景加载时未注册的问题

* feat(editor-core): 添加 UserCodeService 就绪信号机制

- 新增 waitForReady()/signalReady() API
- 支持等待用户脚本编译完成
- 解决场景加载时组件未注册的时序问题

* fix(editor-app): 在编译完成后调用 signalReady()

确保用户脚本编译完成后发出就绪信号：
- 编译成功后调用 userCodeService.signalReady()
- 编译失败也要发出信号，避免阻塞场景加载

* feat(editor-core): 改进编辑器核心服务

- EntityStoreService 添加调试日志
- AssetRegistryService 优化资产注册
- PluginManager 改进插件管理
- IFileAPI 添加 getFileMtime 接口

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

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

* feat(ui): 添加场景切换和文本闪烁组件

新增组件：
- SceneLoadTriggerComponent: 场景切换触发器
- TextBlinkComponent: 文本闪烁效果

新增系统：
- SceneLoadTriggerSystem: 处理场景切换逻辑
- TextBlinkSystem: 处理文本闪烁动画

其他改进：
- UIRuntimeModule 适配新组件注册接口
- UI 渲染系统优化

* feat(editor-app): 添加外部文件修改检测

- 新增 ExternalModificationDialog 组件
- TauriFileAPI 支持 getFileMtime
- 场景文件被外部修改时提示用户

* feat(editor-app): 添加渲染调试面板

- 新增 RenderDebugService 和调试面板 UI
- App/ContentBrowser 添加调试日志
- TitleBar/Viewport 优化
- DialogManager 改进

* refactor(editor-app): 编辑器服务和组件优化

- EngineService 改进引擎集成
- EditorEngineSync 同步优化
- AssetFileInspector 改进
- VectorFieldEditors 优化
- InstantiatePrefabCommand 改进

* feat(i18n): 更新国际化翻译

- 添加新功能相关翻译
- 更新中文、英文、西班牙文

* feat(tauri): 添加文件修改时间查询命令

- 新增 get_file_mtime 命令
- 支持检测文件外部修改

* refactor(particle): 粒子系统改进

- 适配新的组件注册接口
- ParticleSystem 优化
- 添加单元测试

* refactor(platform): 平台适配层优化

- BrowserRuntime 改进
- 新增 RuntimeSceneManager 服务
- 导出优化

* refactor(asset-system-editor): 资产元数据改进

- AssetMetaFile 优化
- 导出调整

* fix(asset-system): 移除未使用的 TextureLoader 导入

* fix(tests): 更新测试以使用 GlobalComponentRegistry 实例

修复多个测试文件以适配 ComponentRegistry 从静态类变为实例类的变更：
- ComponentStorage.test.ts: 使用 GlobalComponentRegistry.reset()
- EntitySerializer.test.ts: 使用 GlobalComponentRegistry 实例
- IncrementalSerialization.test.ts: 使用 GlobalComponentRegistry 实例
- SceneSerializer.test.ts: 使用 GlobalComponentRegistry 实例
- ComponentRegistry.extended.test.ts: 使用 GlobalComponentRegistry，同时注册到 scene.componentRegistry
- SystemTypes.test.ts: 在 Scene 创建前注册组件
- QuerySystem.test.ts: mockScene 添加 componentRegistry
This commit is contained in:
YHH
2025-12-16 12:46:14 +08:00
committed by GitHub
parent d834ca5e77
commit ed8f6e283b
107 changed files with 7399 additions and 847 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
packages/ecs-engine-bindgen/src/core/EngineBridge.ts
View File

@@ -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.
* 销毁桥接并释放资源。

33
packages/ecs-engine-bindgen/src/systems/EngineRenderSystem.ts
View File

@@ -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]
};

28
packages/ecs-engine-bindgen/src/wasm/es_engine.d.ts vendored
View File

@@ -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];