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.

docs: add v0.9.2 changelog and per-frame duration guide

esengine6a6592f9a9fc
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index dac0900e5..b59f70110 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -151,6 +151,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.9.2', slug: 'changelog-v092' },
{ label: 'v0.9.1', slug: 'changelog-v091' },
{ label: 'v0.9.0', slug: 'changelog-v090' },
{ label: 'v0.8.3', slug: 'changelog-v083' },
diff --git a/docs/astro/src/content/docs/changelog-v092.mdx b/docs/astro/src/content/docs/changelog-v092.mdx
new file mode 100644
index 000000000..2b7d674aa
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v092.mdx
@@ -0,0 +1,53 @@
+---
+title: v0.9.2
+description: ESEngine v0.9.2 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.9.2 focuses on stability and correctness across the physics, rendering, and editor subsystems, plus a new per-frame duration feature for sprite animations.
+</Aside>
+
+## Per-Frame Sprite Animation Duration
+
+Sprite animation clips now support an optional `duration` (in seconds) on each frame. When set, it overrides the global `fps` for that frame, enabling variable-speed animations — hold frames, quick hits, or dramatic pauses — without splitting into multiple clips.
+
+- Backward compatible: clips without per-frame duration behave exactly as before
+- Editor: each frame in the AnimClip inspector now has a duration input field
+- `animator.speed` still multiplies whatever duration is used
+
+## Physics: Collision Event Buffer Fix
+
+Collision event buffers (`collisionEnter`, `collisionExit`, `sensorEnter`, `sensorExit`) are now cleared at the start of `physics_step()` instead of inside `physics_collectEvents()`. This prevents stale collision events from leaking across frames when the physics step produces multiple sub-steps.
+
+## WASM Binding Input Validation
+
+All component getter/setter bindings generated by EHT now validate entity existence before accessing components. Previously, passing an invalid or destroyed entity ID from JavaScript could crash the WASM module. The fix covers:
+
+- Generated component bindings (get/add/remove for all C++ components)
+- Tilemap bindings (setTile, getTile, fillRect, etc.)
+- `uiTree_markDirty` and `physics_createBody`
+- The EHT code generator (`eht.py`) was updated so future regenerations include validation automatically
+
+## Asset Address Uniqueness
+
+`AssetDatabase.updateMeta()` now throws when assigning an address that is already used by another asset. The AddressablePanel and AssetInspector catch this error and show feedback to the user, preventing silent address conflicts that could cause incorrect asset lookups at runtime.
+
+## Preview Server Error Reporting
+
+When the preview server fails to start (e.g. port conflict, permission denied), the error is now propagated to the UI as an error toast instead of being silently swallowed. Previously, `PreviewManager` caught errors and returned `null`, leaving users with no indication of why preview failed.
+
+## Scene Transition Error Propagation
+
+Fade-style scene transitions now properly reject their Promise when loading fails, instead of resolving with a silent `console.error`. The `TransitionState` interface gained a `reject` callback, ensuring callers of `transitionTo()` can catch and handle transition failures.
+
+## Circular Prefab Detection
+
+`AssetDependencyAnalyzer` now uses UUID-based cycle tracking (instead of path-based) to prevent path aliasing from bypassing circular dependency detection. Additionally, `PrefabDependencyTracker.registerDependency()` now checks for cycles before adding edges, logging a warning and rejecting circular prefab references.
+
+## Bug Fixes
+
+- Fixed texture reference counting leak when sprite flip parameter changes — `releaseTexture()` no longer phantom-decrements refcounts for flip variants that were never loaded
+- Fixed Vite `dynamic import cannot be analyzed` warning for SpineModuleLoader by preserving `@vite-ignore` comments through terser minification
+- Fixed CI build failure from `INVALID_ENTITY` being undefined in the standalone physics WASM module
diff --git a/docs/astro/src/content/docs/guides/sprite-animation.mdx b/docs/astro/src/content/docs/guides/sprite-animation.mdx
index 822b3fd23..fc4984062 100644
--- a/docs/astro/src/content/docs/guides/sprite-animation.mdx
+++ b/docs/astro/src/content/docs/guides/sprite-animation.mdx
@@ -40,9 +40,36 @@ Animation clips are defined as `.esanim` files — a JSON format listing texture
| Field | Type | Default | Description |
|-------|------|---------|-------------|
-| `fps` | number | `12` | Frames per second |
+| `fps` | number | `12` | Frames per second (used as default for all frames) |
| `loop` | boolean | `true` | Loop playback |
-| `frames` | array | — | List of texture references |
+| `frames` | array | — | List of frame objects |
+| `frames[].texture` | string | — | Texture path or UUID |
+| `frames[].duration` | number | — | Optional per-frame duration in seconds. Overrides `fps` for this frame. |
+
+### Per-Frame Duration
+
+By default, every frame uses the same duration derived from `fps`. To make individual frames longer or shorter, add a `duration` field (in seconds):
+
+```json
+{
+ "version": "1.0",
+ "type": "animation-clip",
+ "fps": 12,
+ "loop": true,
+ "frames": [
+ { "texture": "assets/attack_01.png" },
+ { "texture": "assets/attack_02.png", "duration": 0.5 },
+ { "texture": "assets/attack_03.png" },
+ { "texture": "assets/attack_04.png", "duration": 0.05 }
+ ]
+}
+```
+
+Frames without `duration` fall back to `1 / (fps * speed)`. The `SpriteAnimator.speed` multiplier still applies to per-frame durations.
+
+<Aside type="note">
+In the editor, each frame in the AnimClip inspector has a duration input. Leave it empty to use the global FPS.
+</Aside>
## Editor Workflow
diff --git a/docs/astro/src/content/docs/zh/changelog-v092.mdx b/docs/astro/src/content/docs/zh/changelog-v092.mdx
new file mode 100644
index 000000000..5e2a2f424
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v092.mdx
@@ -0,0 +1,53 @@
+---
+title: v0.9.2
+description: ESEngine v0.9.2 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.9.2 专注于物理、渲染和编辑器子系统的稳定性与正确性修复,并新增精灵动画逐帧时长功能。
+</Aside>
+
+## 精灵动画逐帧时长
+
+精灵动画片段现在支持为每帧设置可选的 `duration`(秒)。设置后会覆盖该帧的全局 `fps`,实现变速动画 — 定格帧、快速打击、戏剧性停顿 — 无需拆分成多个片段。
+
+- 向后兼容:未设置逐帧时长的片段行为不变
+- 编辑器:AnimClip 检查器中每帧现在有一个时长输入框
+- `animator.speed` 仍然作为乘数应用于任何时长
+
+## 物理:碰撞事件缓冲区修复
+
+碰撞事件缓冲区(`collisionEnter`、`collisionExit`、`sensorEnter`、`sensorExit`)现在在 `physics_step()` 开始时清除,而不是在 `physics_collectEvents()` 中清除。这防止了物理步进产生多个子步时,旧碰撞事件泄漏到下一帧。
+
+## WASM 绑定输入校验
+
+EHT 生成的所有组件 getter/setter 绑定现在在访问组件前会校验实体是否存在。此前,从 JavaScript 传入无效或已销毁的实体 ID 会导致 WASM 模块崩溃。修复涵盖:
+
+- 所有 C++ 组件的生成绑定(get/add/remove)
+- Tilemap 绑定(setTile、getTile、fillRect 等)
+- `uiTree_markDirty` 和 `physics_createBody`
+- EHT 代码生成器(`eht.py`)已更新,后续重新生成自动包含校验
+
+## 资源地址唯一性
+
+`AssetDatabase.updateMeta()` 现在在分配已被其他资源使用的地址时会抛出错误。AddressablePanel 和 AssetInspector 捕获此错误并向用户显示反馈,防止静默的地址冲突导致运行时资源查找错误。
+
+## 预览服务器错误提示
+
+当预览服务器启动失败时(如端口冲突、权限不足),错误现在会以错误 Toast 形式传递到 UI,而不是被静默吞掉。此前 `PreviewManager` 捕获错误后返回 `null`,用户无法知道预览为何失败。
+
+## 场景切换错误传播
+
+渐变式场景切换现在在加载失败时会正确地 reject Promise,而不是静默 resolve 并仅输出 `console.error`。`TransitionState` 接口新增了 `reject` 回调,确保 `transitionTo()` 的调用者能捕获并处理切换失败。
+
+## 循环预制体检测
+
+`AssetDependencyAnalyzer` 现在使用基于 UUID 的循环追踪(而非基于路径),防止路径别名绕过循环依赖检测。此外,`PrefabDependencyTracker.registerDependency()` 现在在添加边之前检查循环,发现循环预制体引用时记录警告并拒绝。
+
+## Bug 修复
+
+- 修复精灵翻转参数变更时纹理引用计数泄漏 — `releaseTexture()` 不再对未曾加载的翻转变体进行错误的引用计数递减
+- 修复 SpineModuleLoader 的 Vite `dynamic import cannot be analyzed` 警告,通过在 terser 压缩中保留 `@vite-ignore` 注释
+- 修复独立物理 WASM 模块中 `INVALID_ENTITY` 未定义导致的 CI 构建失败
diff --git a/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx b/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx
index e8f7f1c5a..ccd7cbc47 100644
--- a/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx
+++ b/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx
@@ -40,9 +40,36 @@ import { Aside } from '@astrojs/starlight/components';
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
-| `fps` | number | `12` | 每秒帧数 |
+| `fps` | number | `12` | 每秒帧数(作为所有帧的默认值) |
| `loop` | boolean | `true` | 循环播放 |
-| `frames` | array | — | 纹理引用列表 |
+| `frames` | array | — | 帧对象列表 |
+| `frames[].texture` | string | — | 纹理路径或 UUID |
+| `frames[].duration` | number | — | 可选的逐帧时长(秒)。设置后覆盖该帧的 `fps`。 |
+
+### 逐帧时长
+
+默认情况下,每帧使用由 `fps` 得出的统一时长。要让个别帧更长或更短,添加 `duration` 字段(单位:秒):
+
+```json
+{
+ "version": "1.0",
+ "type": "animation-clip",
+ "fps": 12,
+ "loop": true,
+ "frames": [
+ { "texture": "assets/attack_01.png" },
+ { "texture": "assets/attack_02.png", "duration": 0.5 },
+ { "texture": "assets/attack_03.png" },
+ { "texture": "assets/attack_04.png", "duration": 0.05 }
+ ]
+}
+```
+
+未设置 `duration` 的帧回退到 `1 / (fps * speed)`。`SpriteAnimator.speed` 倍率仍然适用于逐帧时长。
+
+<Aside type="note">
+在编辑器中,AnimClip 检查器的每帧都有一个时长输入框。留空则使用全局 FPS。
+</Aside>
## 编辑器工作流