A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix: editor property sync, Canvas template, Windows path handling, and update check timing
esengined6d35dade16e
diff --git a/desktop/src/main.ts b/desktop/src/main.tsindex 87d371a56..1bf679100 100644--- a/desktop/src/main.ts+++ b/desktop/src/main.ts@@ -104,6 +104,8 @@ async function openEditor(container: HTMLElement, projectPath: string): Promise<const config = await loadProjectConfig(projectPath);await loadPhysicsFactory(editor);++ checkForUpdate();}function loadUmdModule(url: string, globalName: string): Promise<any> {@@ -202,7 +204,6 @@ async function init(): Promise<void> {}showLauncher(container);- checkForUpdate();}init().catch(console.error);diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex acbd52361..b8e8094be 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -156,6 +156,7 @@ export default defineConfig({label: 'Changelog',translations: { 'zh-CN': '更新日志' },items: [+ { label: 'v0.12.2', slug: 'changelog-v0122' },{ label: 'v0.12.1', slug: 'changelog-v0121' },{ label: 'v0.12.0', slug: 'changelog-v0120' },{ label: 'v0.11.0', slug: 'changelog-v0110' },diff --git a/docs/astro/src/content/docs/changelog-v0122.mdx b/docs/astro/src/content/docs/changelog-v0122.mdxnew file mode 100644index 000000000..c4625ab44--- /dev/null+++ b/docs/astro/src/content/docs/changelog-v0122.mdx@@ -0,0 +1,77 @@+---+title: v0.12.2+description: Estella v0.12.2 release notes+---++import { Aside } from '@astrojs/starlight/components';++<Aside type="tip">+v0.12.2 is a stability release — fixes particle rendering, plugs multiple WASM memory leaks, adds ECS command exception isolation, and introduces an extensible asset handler registration API.+</Aside>++## Particle Rendering Fix++The particle system failed to render in v0.12.1 — vertex data never reached the GPU. This release rewrites the particle render path:++- ParticlePlugin now builds rotated quads directly into TransientBufferPool during `collect()`, using the standard DrawCommand path+- Eliminates per-emitter intermediate heap allocations+- New `CMD_STATE_CUSTOM_DRAW` flag on DrawCommand makes custom draw extensible instead of hardcoding RenderType checks++## Extensible Asset Handlers++New `registerAssetHandler()` API lets plugins register custom asset type handlers:++- Scene loading no longer hardcodes asset field handling logic+- Builtin handlers (texture, Spine, material, font, etc.) lazy-initialize via `builtinAssetHandlers.ts`+- Plugins can call `registerAssetHandler()` in `build()` to register custom asset types++## Cross-Platform devicePixelRatio++`PlatformAdapter` interface now includes a `devicePixelRatio()` method:++- Web and WeChat Mini Game platforms provide native implementations+- Replaces platform-specific branching previously in `base.ts`++## Memory Leak Fixes++Fixed multiple WASM memory leaks when entities are despawned:++- **Timeline/Tween**: C++ timeline objects and tween entities were not freed on entity despawn — now automatically calls `_tl_destroy` and `Tween.cancelAll()` via `onDespawn`+- **Spine**: SpineManager was not cleaned up on entity despawn — now automatically calls `SpineManager.removeEntity()`+- **Audio**: audio handles were not stopped or released on entity despawn — now automatically stops and cleans up+- **Font resources**: font resources were not released on scene unload — now cleaned up via `releaseFont()`++## ECS Stability Improvements++### Commands Exception Isolation++`Commands.flush()` now wraps each pending command in try-catch — a single command throwing no longer silently skips remaining commands in the queue.++### Query Mut Entity Validation++Query Mut write-back paths (both iterator and forEach) now validate entity existence before writing back mutations, preventing crashes when entities are despawned mid-iteration via deferred Commands.++### ScriptStorage Validation++`ScriptStorage.set()` now validates component data against schema (warn level), catching invalid data in hot iteration paths.++## Scene and Plugin Error Recovery++- Scene loading now cleans up already-created entities when component deserialization fails, preventing half-initialized entities from lingering+- Plugin `build()` failures now trigger automatic rollback — the plugin is removed from `installedPluginSet_`, `installed_plugins_`, and `installedPluginNames_`++## Internal Improvements++- Eliminated module-level singletons: CollectionViewPlugin, TimelinePlugin, and PostProcessStack global state moved into plugin/class instances+- Unified asset discovery via `discoverSceneAssets()` — scene loading, preloading, and runtime loading share a single discovery function+- PostProcessStack dirty flag skips WASM sync when no mutations occurred+- MaterialCache extracted from static globals into EngineContext with proper lifecycle cleanup+- 11 UI plugins now declare explicit plugin dependencies, leveraging topological sort for initialization order++## Bug Fixes++- Fixed async startup systems potentially executing twice under concurrent `tick()` calls — added reentrant guard+- Fixed web `fileExists` false positive under Tauri custom protocol — Tauri returns 200 for all HEAD requests, switched to GET + body cancel+- Fixed Windows build failure when invoking `emcmake.bat` — `.bat` files require `cmd.exe /C` shell execution+- Fixed Windows build failure when `emcmake.bat` path contains spaces — path is now quoted+- Fixed uniform buffer overflow writing out of bounds — overflow guard moved before writesdiff --git a/docs/astro/src/content/docs/core-concepts/queries.mdx b/docs/astro/src/content/docs/core-concepts/queries.mdxindex 447172e55..6d3e4ed47 100644--- a/docs/astro/src/content/docs/core-concepts/queries.mdx+++ b/docs/astro/src/content/docs/core-concepts/queries.mdx@@ -259,6 +259,10 @@ const despawnDead = defineSystem(`Commands` operations are flushed after the current system function returns. At that point iteration has finished, so the modifications do not affect any in-progress traversal.+<Aside type="note">+When using `Mut` queries, the engine validates that each entity still exists before writing back mutations. This means it is safe to despawn entities via `Commands` during iteration — the write-back for a despawned entity is silently skipped rather than crashing.+</Aside>+## Next Steps- [Change Detection](/docs/core-concepts/change-detection/) — tick-based tracking for Added, Changed, Removeddiff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdxindex ca8e2b686..eac4629ea 100644--- a/docs/astro/src/content/docs/guides/assets.mdx+++ b/docs/astro/src/content/docs/guides/assets.mdx@@ -307,6 +307,33 @@ Each group contains assets with their paths, optional addresses, labels, and typAddressable addresses, labels, and groups are configured in the editor's Addressable panel. The manifest is generated automatically during build.</Aside>+## Custom Asset Handlers++*Added in v0.12.2.*++Plugins can register custom asset type handlers so the scene loader knows how to discover and load your asset types:++```typescript+import { registerAssetHandler } from 'esengine';+import type { AssetFieldHandler } from 'esengine';++const myHandler: AssetFieldHandler = {+ async load(paths, assetServer, baseUrl, texturePathToUrl) {+ const results = new Map<string, number>();+ for (const path of paths) {+ // load your asset, return a handle+ const handle = await loadMyAsset(assetServer, path, baseUrl);+ results.set(path, handle);+ }+ return results;+ },+};++registerAssetHandler('my-asset-type', myHandler);+```++Built-in handlers (texture, material, font, spine, audio, tilemap, timeline, anim-clip) are registered automatically. Custom handlers are typically registered in a plugin's `build()` method.+## Next Steps- [Materials & Shaders](/docs/guides/materials/) — custom shaders and blend modesdiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex d3b76cf98..34c048441 100644--- a/docs/astro/src/content/docs/guides/audio.mdx+++ b/docs/astro/src/content/docs/guides/audio.mdx@@ -208,6 +208,10 @@ On WeChat, audio uses `wx.createInnerAudioContext()` instead of Web Audio API. K- **Game View** — a mute toggle button appears in the Game View toolbar- **Scene View** — audio systems are skipped in Scene View to avoid unwanted playback during editing+## Resource Cleanup++Audio handles are automatically stopped and released when the owning entity is despawned. You do not need to manually stop or clean up `AudioSource` playback when destroying entities.+<Aside type="note">`playOnAwake` defers playback until the browser's `AudioContext` is running. Most browsers require a user interaction before allowing audio playback.</Aside>diff --git a/docs/astro/src/content/docs/guides/plugins.mdx b/docs/astro/src/content/docs/guides/plugins.mdxindex ce36ec5ea..a740f74d4 100644--- a/docs/astro/src/content/docs/guides/plugins.mdx+++ b/docs/astro/src/content/docs/guides/plugins.mdx@@ -199,6 +199,10 @@ const myPlugin: Plugin = {| `finish?(app)` | After all plugins are built | Cross-plugin initialization that depends on other plugins being ready || `cleanup?(app)` | App shutdown | Release resources, clean up listeners and state |+<Aside type="note">+If `build()` throws an exception, the plugin is automatically rolled back — it is removed from the installed plugin set and will not receive `finish()` or `cleanup()` calls. This prevents half-initialized plugins from corrupting engine state.+</Aside>+Plugins can declare resource dependencies:```typescriptdiff --git a/docs/astro/src/content/docs/guides/scenes.mdx b/docs/astro/src/content/docs/guides/scenes.mdxindex ad9509709..8b68e59db 100644--- a/docs/astro/src/content/docs/guides/scenes.mdx+++ b/docs/astro/src/content/docs/guides/scenes.mdx@@ -143,6 +143,10 @@ addSystem(defineSystem(Commands are buffered and applied at the end of the current schedule stage, not immediately.</Aside>+### Error Recovery++If a component fails to deserialize during scene loading, all entities already created for that scene are automatically despawned. This prevents half-initialized entities from lingering in the world.+## Entity VisibilityEntities have a `visible` property (default `true`). When set to `false` in the editor, the entity's components are skipped during scene loading — it exists in the hierarchy but has no runtime behaviour. Use this to keep reference entities in the scene file without spawning them.diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdxindex 2316b0c7e..d627590fa 100644--- a/docs/astro/src/content/docs/guides/spine.mdx+++ b/docs/astro/src/content/docs/guides/spine.mdx@@ -327,6 +327,10 @@ manager.setPathConstraintMix(entity, 'path-follow', {Spine skeletons that use multiple atlas pages are automatically batched by the renderer. No additional configuration is needed — the C++ backend handles multi-texture setups transparently, keeping draw calls low even with complex multi-atlas characters.+## Resource Cleanup++Spine resources are automatically cleaned up when the owning entity is despawned. The engine calls `SpineManager.removeEntity()` via `onDespawn`, freeing the underlying WASM memory. You do not need to manually release Spine resources when destroying entities.+<Aside type="tip">Spine rendering is handled by the C++ backend. The TypeScript side only sets component data — the engine handles loading, blending, and drawing automatically.</Aside>diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdxindex 1086c96be..49df6107a 100644--- a/docs/astro/src/content/docs/guides/timeline.mdx+++ b/docs/astro/src/content/docs/guides/timeline.mdx@@ -280,6 +280,10 @@ addSystem(defineSystem());```+## Resource Cleanup++Timeline and tween resources attached to an entity are automatically cleaned up when the entity is despawned. The engine calls `_tl_destroy` to free C++ timeline objects and `Tween.cancelAll()` to cancel active tweens via `onDespawn`. You do not need to manually stop timelines or cancel tweens when destroying entities.+## Next Steps- [State Machine](/docs/guides/state-machine/) — drive timelines through state transitionsdiff --git a/docs/astro/src/content/docs/guides/tween.mdx b/docs/astro/src/content/docs/guides/tween.mdxindex 632221df6..ab02783e3 100644--- a/docs/astro/src/content/docs/guides/tween.mdx+++ b/docs/astro/src/content/docs/guides/tween.mdx@@ -198,6 +198,10 @@ handle.cancel();Tween.cancelAll(entity);```+<Aside type="note">+When an entity is despawned, all its active tweens are automatically cancelled via `Tween.cancelAll()`. You do not need to manually cancel tweens before destroying entities.+</Aside>+## Custom Property AnimationUse `Tween.value()` to animate any numeric value with a callback:diff --git a/docs/astro/src/content/docs/zh/changelog-v0122.mdx b/docs/astro/src/content/docs/zh/changelog-v0122.mdxnew file mode 100644index 000000000..df1f22ded--- /dev/null+++ b/docs/astro/src/content/docs/zh/changelog-v0122.mdx@@ -0,0 +1,77 @@+---+title: v0.12.2+description: Estella v0.12.2 更新日志+---++import { Aside } from '@astrojs/starlight/components';++<Aside type="tip">+v0.12.2 是稳定性修复版本——修复了粒子不渲染、多处 WASM 内存泄漏、ECS 命令异常隔离,并新增可扩展资产处理器注册 API。+</Aside>++## 粒子渲染修复++粒子系统在 v0.12.1 中无法正确渲染——顶点数据未到达 GPU。此版本重写了粒子渲染路径:++- ParticlePlugin 现在在标准 `collect()` 阶段直接构建旋转四边形到 TransientBufferPool,走标准 DrawCommand 路径+- 消除了每个发射器的中间堆分配+- DrawCommand 新增 `CMD_STATE_CUSTOM_DRAW` 标志,使自定义绘制可扩展,不再硬编码 RenderType 检查++## 可扩展资产处理器++新增 `registerAssetHandler()` API,允许插件注册自定义资产类型处理器:++- 场景加载不再硬编码资产字段处理逻辑+- 内置处理器(纹理、Spine、材质、字体等)通过 `builtinAssetHandlers.ts` 懒初始化注册+- 插件可在 `build()` 中调用 `registerAssetHandler()` 注册自定义资产类型++## 跨平台 devicePixelRatio++`PlatformAdapter` 接口新增 `devicePixelRatio()` 方法:++- Web 平台和微信小游戏平台各自提供原生实现+- 替代了此前 `base.ts` 中的平台特殊分支判断++## 内存泄漏修复++修复了多处实体销毁时的 WASM 内存泄漏:++- **Timeline/Tween**:实体销毁时未释放 C++ 侧 timeline 对象和 tween 实体,现在通过 `onDespawn` 自动调用 `_tl_destroy` 和 `Tween.cancelAll()`+- **Spine**:实体销毁时 SpineManager 未清理,现在自动调用 `SpineManager.removeEntity()`+- **Audio**:实体销毁时音频句柄未停止和释放,现在自动停止并清理+- **字体资源**:场景卸载时未释放字体资源,现在通过 `releaseFont()` 清理++## ECS 稳定性增强++### Commands 异常隔离++`Commands.flush()` 现在为每个待执行命令包裹 try-catch——单个命令抛出异常不再跳过队列中的后续命令。++### Query Mut 实体校验++Query 的 Mut 回写路径(迭代器和 forEach)在写回前验证实体是否仍然存在,防止迭代过程中通过 Commands 销毁实体导致的崩溃。++### ScriptStorage 校验++`ScriptStorage.set()` 新增 schema 校验(warn 级别),在热路径中检测无效组件数据。++## 场景与插件容错++- 场景加载时组件反序列化失败会自动清理已创建的实体,防止半初始化实体残留+- 插件 `build()` 抛出异常时自动回滚注册,从 `installedPluginSet_`、`installed_plugins_` 和 `installedPluginNames_` 中移除++## 引擎内部改进++- 消除模块级单例:CollectionViewPlugin、TimelinePlugin、PostProcessStack 的全局状态移入插件/类实例+- 统一资产发现逻辑 `discoverSceneAssets()`——场景加载、预加载、运行时加载共用一套发现函数+- PostProcessStack 增加 dirty flag,无变更时跳过 WASM 同步+- MaterialCache 从静态全局提取到 EngineContext,随引擎生命周期正确释放+- 11 个 UI 插件显式声明插件依赖,利用拓扑排序保证初始化顺序++## Bug 修复++- 修复异步 startup system 在并发 `tick()` 调用下可能执行两次——新增重入锁保护+- 修复 Web 平台 `fileExists` 在 Tauri 自定义协议下误报——Tauri 对 HEAD 请求总返回 200,改用 GET + body cancel+- 修复 Windows 平台调用 `emcmake.bat` 构建失败——`.bat` 文件需通过 `cmd.exe /C` 执行+- 修复 Windows 平台 `emcmake.bat` 路径含空格时构建失败——路径加引号处理+- 修复 uniform buffer 溢出时越界写入——溢出检查移至写入前diff --git a/docs/astro/src/content/docs/zh/core-concepts/queries.mdx b/docs/astro/src/content/docs/zh/core-concepts/queries.mdxindex 0ae028942..d01adf625 100644--- a/docs/astro/src/content/docs/zh/core-concepts/queries.mdx+++ b/docs/astro/src/content/docs/zh/core-concepts/queries.mdx@@ -258,6 +258,10 @@ const despawnDead = defineSystem(`Commands` 的操作会在当前系统函数返回后统一刷新(flush),此时迭代已结束,修改不会影响正在进行的遍历。+<Aside type="note">+使用 `Mut` 查询时,引擎会在回写变更前验证实体是否仍然存在。这意味着在迭代过程中通过 `Commands` 销毁实体是安全的——已销毁实体的回写会被静默跳过,不会导致崩溃。+</Aside>+## 下一步- [变更检测](/docs/zh/core-concepts/change-detection/) — 基于 tick 的 Added、Changed、Removed 追踪diff --git a/docs/astro/src/content/docs/zh/guides/assets.mdx b/docs/astro/src/content/docs/zh/guides/assets.mdxindex b353d47b5..83628f167 100644--- a/docs/astro/src/content/docs/zh/guides/assets.mdx+++ b/docs/astro/src/content/docs/zh/guides/assets.mdx@@ -307,6 +307,33 @@ interface AddressableManifestAsset {Addressable 的地址、标签和分组在编辑器的 Addressable 面板中配置。清单在构建时自动生成。</Aside>+## 自定义资产处理器++*v0.12.2 新增。*++插件可以注册自定义资产类型处理器,使场景加载器能够发现和加载你的资产类型:++```typescript+import { registerAssetHandler } from 'esengine';+import type { AssetFieldHandler } from 'esengine';++const myHandler: AssetFieldHandler = {+ async load(paths, assetServer, baseUrl, texturePathToUrl) {+ const results = new Map<string, number>();+ for (const path of paths) {+ // 加载你的资产,返回句柄+ const handle = await loadMyAsset(assetServer, path, baseUrl);+ results.set(path, handle);+ }+ return results;+ },+};++registerAssetHandler('my-asset-type', myHandler);+```++内置处理器(texture、material、font、spine、audio、tilemap、timeline、anim-clip)会自动注册。自定义处理器通常在插件的 `build()` 方法中注册。+## 下一步- [材质与着色器](/docs/zh/guides/materials/) — 自定义着色器和混合模式diff --git a/docs/astro/src/content/docs/zh/guides/audio.mdx b/docs/astro/src/content/docs/zh/guides/audio.mdxindex c70b23b63..4c42a201e 100644--- a/docs/astro/src/content/docs/zh/guides/audio.mdx+++ b/docs/astro/src/content/docs/zh/guides/audio.mdx@@ -208,6 +208,10 @@ import { AudioSource, AudioListener, AttenuationModel } from 'esengine';- **Game View** — Game View 工具栏中有静音切换按钮- **Scene View** — Scene View 中跳过音频系统,避免编辑时产生不必要的播放+## 资源清理++音频句柄会在所属实体被销毁时自动停止并释放。销毁实体时无需手动停止或清理 `AudioSource` 播放。+<Aside type="note">`playOnAwake` 会延迟到浏览器的 `AudioContext` 激活后才播放。大多数浏览器要求用户交互后才允许音频播放。</Aside>diff --git a/docs/astro/src/content/docs/zh/guides/plugins.mdx b/docs/astro/src/content/docs/zh/guides/plugins.mdxindex 8aec20765..44196e143 100644--- a/docs/astro/src/content/docs/zh/guides/plugins.mdx+++ b/docs/astro/src/content/docs/zh/guides/plugins.mdx@@ -199,6 +199,10 @@ const myPlugin: Plugin = {| `finish?(app)` | 所有插件 build 完成后 | 依赖其他插件就绪的跨插件初始化 || `cleanup?(app)` | 应用关闭时 | 释放资源、清理监听器和状态 |+<Aside type="note">+如果 `build()` 抛出异常,插件会自动回滚——从已安装的插件集合中移除,不会收到 `finish()` 或 `cleanup()` 调用。这可以防止半初始化的插件破坏引擎状态。+</Aside>+插件可以声明资源依赖:```typescriptdiff --git a/docs/astro/src/content/docs/zh/guides/scenes.mdx b/docs/astro/src/content/docs/zh/guides/scenes.mdxindex 7361d1687..089132f45 100644--- a/docs/astro/src/content/docs/zh/guides/scenes.mdx+++ b/docs/astro/src/content/docs/zh/guides/scenes.mdx@@ -143,6 +143,10 @@ addSystem(defineSystem(Commands 是缓冲的,在当前调度阶段结束时应用,不会立即生效。</Aside>+### 错误恢复++如果场景加载过程中某个组件反序列化失败,该场景已创建的所有实体会被自动销毁,防止半初始化的实体残留在世界中。+## 实体可见性实体拥有 `visible` 属性(默认 `true`)。在编辑器中将其设为 `false` 时,场景加载会跳过该实体的组件 — 它在层级中存在但没有运行时行为。适合用于在场景文件中保留参考实体而不在运行时生成。diff --git a/docs/astro/src/content/docs/zh/guides/spine.mdx b/docs/astro/src/content/docs/zh/guides/spine.mdxindex bd5544791..165a86e45 100644--- a/docs/astro/src/content/docs/zh/guides/spine.mdx+++ b/docs/astro/src/content/docs/zh/guides/spine.mdx@@ -327,6 +327,10 @@ manager.setPathConstraintMix(entity, 'path-follow', {使用多个图集页的 Spine 骨骼会被渲染器自动批处理。无需额外配置 — C++ 后端透明地处理多纹理情况,即使是复杂的多图集角色也能保持较低的 draw call。+## 资源清理++Spine 资源会在所属实体被销毁时自动清理。引擎通过 `onDespawn` 调用 `SpineManager.removeEntity()`,释放底层 WASM 内存。销毁实体时无需手动释放 Spine 资源。+<Aside type="tip">Spine 渲染由 C++ 后端处理。TypeScript 只负责设置组件数据 — 引擎自动处理加载、混合和绘制。</Aside>diff --git a/docs/astro/src/content/docs/zh/guides/timeline.mdx b/docs/astro/src/content/docs/zh/guides/timeline.mdxindex e91817737..3542abbce 100644--- a/docs/astro/src/content/docs/zh/guides/timeline.mdx+++ b/docs/astro/src/content/docs/zh/guides/timeline.mdx@@ -280,6 +280,10 @@ addSystem(defineSystem());```+## 资源清理++实体被销毁时,附加在实体上的时间轴和补间资源会自动清理。引擎通过 `onDespawn` 调用 `_tl_destroy` 释放 C++ 时间轴对象,并调用 `Tween.cancelAll()` 取消活跃的补间动画。销毁实体时无需手动停止时间轴或取消补间。+## 下一步- [状态机](/docs/zh/guides/state-machine/) — 通过状态转换驱动时间轴diff --git a/docs/astro/src/content/docs/zh/guides/tween.mdx b/docs/astro/src/content/docs/zh/guides/tween.mdxindex d36b38b55..b4cc1a8e9 100644--- a/docs/astro/src/content/docs/zh/guides/tween.mdx+++ b/docs/astro/src/content/docs/zh/guides/tween.mdx@@ -198,6 +198,10 @@ handle.cancel();Tween.cancelAll(entity);```+<Aside type="note">+实体被销毁时,其所有活跃的补间会通过 `Tween.cancelAll()` 自动取消。销毁实体前无需手动取消补间。+</Aside>+## 自定义属性动画使用 `Tween.value()` 通过回调动画化任意数值:diff --git a/editor/src/launcher/ProjectService.ts b/editor/src/launcher/ProjectService.tsindex eda126c35..1a55365a8 100644--- a/editor/src/launcher/ProjectService.ts+++ b/editor/src/launcher/ProjectService.ts@@ -11,6 +11,7 @@ import type {} from '../types/ProjectTypes';import { ENGINE_VERSION } from '../types/ProjectTypes';import { DEFAULT_DESIGN_WIDTH, DEFAULT_DESIGN_HEIGHT, DEFAULT_PIXELS_PER_UNIT } from 'esengine';+import { createCanvasComponents } from '../panels/hierarchy/uiEntityUtils';import { SdkExportService } from '../sdk';import { EditorExportService } from '../extension/EditorExportService';import { getEditorContext } from '../context/EditorContext';@@ -334,7 +335,7 @@ export async function openProject(return { success: false, error: 'Invalid project file format' };}- const projectDir = projectPath.replace(/\/[^/]+\.esproject$/, '');+ const projectDir = projectPath.replace(/[/\\][^/\\]+\.esproject$/, '');const sdkService = new SdkExportService();await sdkService.exportToProject(projectDir);@@ -358,7 +359,7 @@ export async function loadEditorLocalSettings(projectPath: string): Promise<Recoconst fs = getNativeFS();if (!fs) return null;- const projectDir = projectPath.replace(/\/[^/]+\.esproject$/, '');+ const projectDir = projectPath.replace(/[/\\][^/\\]+\.esproject$/, '');const settingsPath = joinPath(projectDir, '.esengine/settings.json');const content = await fs.readFile(settingsPath);if (!content) return null;@@ -374,7 +375,7 @@ export async function saveEditorLocalSetting(projectPath: string, key: string, vconst fs = getNativeFS();if (!fs) return;- const projectDir = projectPath.replace(/\/[^/]+\.esproject$/, '');+ const projectDir = projectPath.replace(/[/\\][^/\\]+\.esproject$/, '');const settingsPath = joinPath(projectDir, '.esengine/settings.json');let settings: Record<string, unknown> = {};@@ -505,26 +506,13 @@ function createDefaultScene(name: 'Canvas',parent: null,children: [],- components: [- {- type: 'Transform',- data: {- position: { x: 0, y: 0, z: 0 },- rotation: { x: 0, y: 0, z: 0, w: 1 },- scale: { x: 1, y: 1, z: 1 },- },- },- {- type: 'Canvas',- data: {- designResolution: { x: designResolution.width, y: designResolution.height },- pixelsPerUnit,- scaleMode: 1,- matchWidthOrHeight: 0.5,- backgroundColor: { r: 0, g: 0, b: 0, a: 1 },- },- },- ],+ components: createCanvasComponents({+ designResolution: { x: designResolution.width, y: designResolution.height },+ pixelsPerUnit,+ scaleMode: 1,+ matchWidthOrHeight: 0.5,+ backgroundColor: { r: 0, g: 0, b: 0, a: 1 },+ }),},],};diff --git a/editor/src/panels/hierarchy/EntityTemplates.ts b/editor/src/panels/hierarchy/EntityTemplates.tsindex 2634981c0..6a3d953eb 100644--- a/editor/src/panels/hierarchy/EntityTemplates.ts+++ b/editor/src/panels/hierarchy/EntityTemplates.ts@@ -21,6 +21,7 @@ interface EntityTemplate {root: EntityTemplateNode;bindings?: Record<string, string>;category: EntityCategory;+ isUIRoot?: boolean;menuLabel?: string;icon?: string;}@@ -29,6 +30,10 @@ function ui(root: EntityTemplateNode, bindings?: Record<string, string>): Entityreturn { root, bindings, category: 'ui' };}+function uiRoot(root: EntityTemplateNode): EntityTemplate {+ return { root, category: 'ui', isUIRoot: true };+}+function physics(root: EntityTemplateNode): EntityTemplate {return { root, category: 'physics' };}@@ -98,7 +103,7 @@ export const ENTITY_TEMPLATES: Record<string, EntityTemplate> = {}),// ---- UI ----- Canvas: ui({+ Canvas: uiRoot({name: 'Canvas',components: [{ type: 'Transform' }, { type: 'UIRect' }, { type: 'Canvas' }],}),@@ -359,7 +364,7 @@ export function instantiateTemplate(if (!template) return null;let effectiveParent = parent;- if (template.category === 'ui') {+ if (template.category === 'ui' && !template.isUIRoot) {effectiveParent = resolveUIParent(state.store, parent);}diff --git a/editor/src/panels/hierarchy/uiEntityUtils.ts b/editor/src/panels/hierarchy/uiEntityUtils.tsindex deb826c4a..9cd1ada9c 100644--- a/editor/src/panels/hierarchy/uiEntityUtils.ts+++ b/editor/src/panels/hierarchy/uiEntityUtils.ts@@ -2,6 +2,25 @@ import type { Entity } from 'esengine';import { getInitialComponentData } from '../../schemas/ComponentSchemas';import type { EditorStore } from '../../store/EditorStore';+export interface CanvasOverrides {+ designResolution?: { x: number; y: number };+ pixelsPerUnit?: number;+ scaleMode?: number;+ matchWidthOrHeight?: number;+ backgroundColor?: { r: number; g: number; b: number; a: number };+}++export function createCanvasComponents(+ overrides?: CanvasOverrides,+): { type: string; data: Record<string, unknown> }[] {+ const canvasData = { ...getInitialComponentData('Canvas'), ...overrides };+ return [+ { type: 'Transform', data: getInitialComponentData('Transform') },+ { type: 'UIRect', data: getInitialComponentData('UIRect') },+ { type: 'Canvas', data: canvasData },+ ];+}+export function ensureCanvasEntity(store: EditorStore): Entity {for (const entity of store.scene.entities) {if (entity.components.some(c => c.type === 'Canvas')) {@@ -9,9 +28,9 @@ export function ensureCanvasEntity(store: EditorStore): Entity {}}const canvas = store.createEntity('Canvas', null);- store.addComponent(canvas, 'Transform', getInitialComponentData('Transform'));- store.addComponent(canvas, 'UIRect', getInitialComponentData('UIRect'));- store.addComponent(canvas, 'Canvas', getInitialComponentData('Canvas'));+ for (const comp of createCanvasComponents()) {+ store.addComponent(canvas, comp.type, comp.data);+ }return canvas;}diff --git a/editor/src/sync/BuiltinPropertySync.ts b/editor/src/sync/BuiltinPropertySync.tsindex af251358c..5a9326ad2 100644--- a/editor/src/sync/BuiltinPropertySync.ts+++ b/editor/src/sync/BuiltinPropertySync.ts@@ -13,6 +13,7 @@ export class BuiltinPropertySync {private store_: EditorStore;private renderCallback_: (() => void) | null = null;private incrementalSync_: IncrementalSync | null = null;+ private assetFieldCache_ = new Map<string, Set<string>>();constructor(sceneManager: EditorSceneManager, store: EditorStore) {this.sceneManager_ = sceneManager;@@ -32,6 +33,8 @@ export class BuiltinPropertySync {if (!this.store_.isEntityVisible(event.entity)) return true;+ if (this.isAssetField_(event.componentType, event.propertyName)) return false;+if (event.componentType === 'Transform') {return this.syncTransform_(event, entityData);}@@ -50,6 +53,25 @@ export class BuiltinPropertySync {return false;}+ private isAssetField_(componentType: string, propertyName: string): boolean {+ let fields = this.assetFieldCache_.get(componentType);+ if (fields === undefined) {+ fields = new Set<string>();+ const compDef = getComponent(componentType);+ if (compDef) {+ for (const af of compDef.assetFields) {+ fields.add(af.field);+ }+ if (compDef.spineFields) {+ fields.add(compDef.spineFields.skeletonField);+ fields.add(compDef.spineFields.atlasField);+ }+ }+ this.assetFieldCache_.set(componentType, fields);+ }+ return fields.has(propertyName);+ }+private syncTransform_(event: PropertyChangeEvent, entityData: EntityData): boolean {if (!TRANSFORM_PATCH_PROPS.has(event.propertyName)) {return false;