Skip to content

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.

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.ts
index 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.mjs
index 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.mdx
new file mode 100644
index 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 writes
diff --git a/docs/astro/src/content/docs/core-concepts/queries.mdx b/docs/astro/src/content/docs/core-concepts/queries.mdx
index 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, Removed
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 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 typ
Addressable 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 modes
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
index 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.mdx
index 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:
```typescript
diff --git a/docs/astro/src/content/docs/guides/scenes.mdx b/docs/astro/src/content/docs/guides/scenes.mdx
index 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 Visibility
Entities 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.mdx
index 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.mdx
index 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 transitions
diff --git a/docs/astro/src/content/docs/guides/tween.mdx b/docs/astro/src/content/docs/guides/tween.mdx
index 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 Animation
Use `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.mdx
new file mode 100644
index 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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>
+
插件可以声明资源依赖:
```typescript
diff --git a/docs/astro/src/content/docs/zh/guides/scenes.mdx b/docs/astro/src/content/docs/zh/guides/scenes.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.ts
index 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<Reco
const 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, v
const 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.ts
index 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>): Entity
return { 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.ts
index 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.ts
index 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;