docs: add v0.10.0 changelog and update timeline, spine, input guides

esengine · esengine · commit 8aeb9c40e5af · 2026-03-11T03:08:26.000-07:00
fix: remove brittle timeline version assertion in test
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
@@ -153,6 +153,7 @@ export default defineConfig({
           label: 'Changelog',
           translations: { 'zh-CN': '更新日志' },
           items: [
+            { label: 'v0.10.0', slug: 'changelog-v0100' },
             { label: 'v0.9.2', slug: 'changelog-v092' },
             { label: 'v0.9.1', slug: 'changelog-v091' },
             { label: 'v0.9.0', slug: 'changelog-v090' },
diff --git a/docs/astro/src/content/docs/changelog-v0100.mdx b/docs/astro/src/content/docs/changelog-v0100.mdx
@@ -0,0 +1,104 @@
+---
+title: v0.10.0
+description: Estella v0.10.0 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.10.0 is a major feature release: AI-powered editor integration via MCP, visual timeline enhancements, expanded physics/spine/tilemap capabilities, and a new pivot point system.
+</Aside>
+
+## MCP Server: AI-Assisted Editor Integration
+
+Estella now includes a built-in MCP (Model Context Protocol) bridge that enables AI assistants like Claude to directly interact with the running editor. The bridge starts automatically and exposes a comprehensive API for:
+
+- **Scene inspection**: read entity hierarchy, component data, asset lists
+- **Entity operations**: create, delete, rename, reparent entities; add/remove components
+- **Property editing**: modify component properties with full undo support
+- **Timeline control**: read/write timeline data, control playback
+- **Play mode**: start/stop/pause play mode, adjust playback speed
+- **Asset management**: read/write asset files, manage asset metadata
+
+A standalone MCP server (`tools/mcp-server/`) wraps the bridge for use with any MCP-compatible client.
+
+## Timeline: AnimFrames Track
+
+A new `animFrames` track type displays individual sprite frames as colored, resizable blocks on the timeline. Each frame has its own duration that can be adjusted by dragging the block edges, enabling precise control over frame timing without splitting into multiple clips.
+
+### Live Playhead Sync
+
+When entering Play Mode, the timeline automatically switches to **LIVE** mode: the playhead tracks the runtime animation position in real-time (polled at 60fps from the C++ timeline system). A red blinking "LIVE" indicator appears in the toolbar. Editor playback controls are disabled during live mode and restore when exiting Play Mode.
+
+### Timeline Editing Improvements
+
+- **Multi-select keyframes**: Ctrl+click to toggle, Shift+click for range select, rubber-band box select
+- **Batch operations**: move or delete multiple selected keyframes as a single undo step
+- **Interpolation presets**: right-click keyframes to apply Linear, EaseIn, EaseOut, EaseInOut, or Step
+- **Marker & custom event tracks**: new track types for placing markers and custom events on the timeline
+- **Grid snap**: toggle snap-to-grid in the toolbar; keyframes snap to grid lines during drag
+- **Playback controls**: step forward/back by frame, speed control (0.25x–4x), wrap mode cycling (Once/Loop/PingPong)
+- **Duration editing**: double-click the time display to edit total timeline duration
+- **Track management**: drag to reorder, right-click for rename/delete, type-colored sidebar indicators
+
+## Physics: Joints, Raycasting & Queries
+
+### Joint Types
+
+Five joint types are now available for connecting physics bodies:
+
+- **Distance Joint**: maintains a fixed distance between two bodies
+- **Revolute Joint**: hinge rotation around a shared anchor point, with optional motor and angle limits
+- **Prismatic Joint**: linear sliding along an axis, with optional motor and translation limits
+- **Weld Joint**: rigidly bonds two bodies together
+- **Wheel Joint**: combines revolute and prismatic behavior for vehicle suspensions
+
+### Spatial Queries
+
+- **Raycast**: cast a ray through the physics world and get all hit results (point, normal, distance, entity)
+- **Overlap queries**: test a circle against the world to find overlapping bodies
+- **Compound shapes**: attach multiple collision shapes to a single physics body
+
+### Editor Integration
+
+A new physics editor plugin provides visual configuration of joints and shapes directly in the Inspector.
+
+## Spine: Mixing, Events & IK
+
+- **Animation mixing**: crossfade between Spine animations with configurable mix duration
+- **Event system**: listen for Spine animation events (start, end, complete, custom) via `SpineModuleController`
+- **Attachment control**: show/hide slots and swap attachments at runtime via `SpineController`
+- **IK constraints**: configure inverse kinematics constraints in Spine skeletons
+- **Slot color**: tint individual Spine slots programmatically
+
+Performance improvements:
+- Mesh extraction results are cached across multi-camera renders
+- Mesh allocations batched to 2 per frame maximum
+- Transform matrix computation moved to C++ for reduced overhead
+
+## Tilemap: Animated Tiles & Isometric
+
+- **Animated tiles**: tiles can reference animation sequences that play automatically
+- **Tile properties**: access custom properties defined in Tiled on individual tiles
+- **Flip & rotate**: tiles support horizontal/vertical flip and 90-degree rotation
+- **Isometric grid**: native isometric tilemap rendering alongside orthogonal
+- **Debug visualization**: toggle tilemap grid overlay for debugging tile placement
+- **Tilemap API**: new `tilemapAPI` module for runtime tile manipulation (setTile, getTile, fillRect, etc.)
+
+## Pivot & Anchor Points
+
+Sprites now support configurable pivot points that affect rotation, scaling, and positioning. The editor displays a draggable pivot overlay in the Scene View. Bounds calculation accounts for non-center pivots.
+
+## Editor Improvements
+
+- **Asset picker dialog**: reusable modal for selecting assets by type, with grid preview and search
+- **Settings validation**: project settings now validate against a JSON schema, surfacing configuration errors early
+- **Improved inspectors**: AnimClip and BitmapFont inspectors redesigned with better UX
+- **Content browser**: asset grid supports additional preview modes
+
+## Engine Internals
+
+- Entity destruction cleanup hooks in the C++ Registry
+- Blend state moved from file-static to RenderCommand class member
+- Physics and Spine global state encapsulated into context structs
+- `App.physicsInitPromise` for awaiting async physics initialization
diff --git a/docs/astro/src/content/docs/guides/input.mdx b/docs/astro/src/content/docs/guides/input.mdx
@@ -104,6 +104,31 @@ if (input.isMouseButtonReleased(0)) {
 }
 ```
 
+<Aside type="caution">
+  `getMousePosition()` returns **screen coordinates** (CSS pixels relative to the canvas element), not world coordinates. If you need to interact with entities in the scene, use `UICameraInfo` to get world coordinates — see [Screen to World Coordinates](#screen-to-world-coordinates) below.
+</Aside>
+
+### Screen to World Coordinates
+
+When using UI plugins (included by default via `createWebApp`), `UICameraInfo` automatically converts mouse position to world coordinates each frame:
+
+```typescript
+import { defineSystem, addSystem, Res, Input, UICameraInfo } from 'esengine';
+
+addSystem(defineSystem(
+    [Res(Input), Res(UICameraInfo)],
+    (input, camera) => {
+        if (input.isMouseButtonPressed(0)) {
+            // World coordinates, ready to use for scene interaction
+            const wx = camera.worldMouseX;
+            const wy = camera.worldMouseY;
+            spawnBullet(wx, wy);
+        }
+    }
+));
+```
+
+
 ## Scroll Input
 
 ```typescript
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
@@ -138,6 +138,58 @@ addSystem(defineSystem(
 ));
 ```
 
+## Animation Mixing
+
+Crossfade between animations with configurable mix duration via `SpineManager`:
+
+```typescript
+import { SpineManager } from 'esengine';
+
+const manager = app.getResource(SpineManager);
+
+// Set default mix duration for all transitions
+manager.setDefaultMix(entity, 0.2);
+
+// Set mix duration for a specific transition pair
+manager.setMixDuration(entity, 'idle', 'run', 0.15);
+manager.setMixDuration(entity, 'run', 'idle', 0.3);
+```
+
+## Attachment Control
+
+Show/hide slots and swap attachments at runtime:
+
+```typescript
+const manager = app.getResource(SpineManager);
+
+// Hide a slot
+manager.setAttachment(entity, 'weapon', '');
+
+// Swap to a different attachment
+manager.setAttachment(entity, 'weapon', 'sword');
+```
+
+## IK Constraints
+
+Configure inverse kinematics constraints on Spine skeletons. IK targets can be positioned programmatically:
+
+```typescript
+const manager = app.getResource(SpineManager);
+
+// mix: 0.0 = no effect, 1.0 = full IK
+manager.setIKTarget(entity, 'aim-ik', targetX, targetY, 1.0);
+```
+
+## Slot Color
+
+Tint individual Spine slots:
+
+```typescript
+const manager = app.getResource(SpineManager);
+
+manager.setSlotColor(entity, 'body', 1, 0.5, 0.5, 1);
+```
+
 ## Multi-Version Architecture
 
 Estella supports Spine versions **3.8**, **4.1**, and **4.2** simultaneously. The engine automatically detects the Spine version from the skeleton data and selects the appropriate runtime backend.
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -26,8 +26,34 @@ The **Timeline** system drives multi-track animations that coordinate property c
 | Property | Animate any numeric component property (position, scale, color, etc.) with keyframe interpolation |
 | Spine | Trigger Spine animation clips on a SpineAnimation component |
 | Sprite Animation | Play sprite animation clips |
+| AnimFrames | Visual frame track — each sprite frame is a colored, resizable block with its own duration |
 | Audio | Trigger audio events at specific times |
 | Activation | Enable/disable entities over time ranges |
+| Marker | Place named markers at specific times |
+| Custom Event | Trigger custom events at specific times |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Space` | Play / Pause |
+| `,` / `.` | Step backward / forward one frame |
+| `K` | Add keyframe at playhead |
+| `Delete` | Delete selected keyframes |
+| `Ctrl+Click` | Toggle keyframe selection |
+| `Shift+Click` | Range select keyframes |
+
+### Toolbar Controls
+
+- **Record**: Toggle auto-keyframe mode — changes to properties are automatically recorded as keyframes
+- **Speed**: Cycle playback speed (0.25x, 0.5x, 1x, 2x, 4x)
+- **Wrap Mode**: Cycle between Once, Loop, and PingPong
+- **Snap**: Toggle grid snapping during keyframe drag
+- **Duration**: Double-click the time display to edit total timeline duration
+
+### Live Playhead Sync
+
+When entering Play Mode, the timeline automatically switches to **LIVE** mode. The playhead tracks the runtime animation position in real-time, and a red "LIVE" indicator appears in the toolbar. Editor playback controls are disabled during live mode and restore when exiting Play Mode.
 
 ## TimelinePlayer Component
 
diff --git a/docs/astro/src/content/docs/zh/changelog-v0100.mdx b/docs/astro/src/content/docs/zh/changelog-v0100.mdx
@@ -0,0 +1,104 @@
+---
+title: v0.10.0
+description: Estella v0.10.0 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.10.0 是一个重要的功能版本：AI 驱动的编辑器集成（MCP）、可视化时间轴增强、扩展的物理/Spine/Tilemap 能力，以及新的锚点系统。
+</Aside>
+
+## MCP Server：AI 辅助编辑器集成
+
+Estella 现在内置 MCP（Model Context Protocol）桥接器，允许 Claude 等 AI 助手直接与运行中的编辑器交互。桥接器自动启动，提供全面的 API：
+
+- **场景检查**：读取实体层级、组件数据、资产列表
+- **实体操作**：创建、删除、重命名、重新父级实体；添加/移除组件
+- **属性编辑**：修改组件属性，完整支持撤销
+- **时间轴控制**：读写时间轴数据，控制播放
+- **Play 模式**：启动/停止/暂停 Play 模式，调整播放速度
+- **资产管理**：读写资产文件，管理资产元数据
+
+独立的 MCP 服务器（`tools/mcp-server/`）封装了桥接器，可与任何 MCP 兼容客户端配合使用。
+
+## 时间轴：AnimFrames 帧轨道
+
+新增 `animFrames` 轨道类型，将精灵帧显示为时间轴上带颜色、可调整大小的色块。每帧有独立的时长，可通过拖拽色块边缘调整，实现对帧时序的精细控制。
+
+### 实时播放头同步
+
+进入 Play 模式时，时间轴自动切换到 **LIVE** 模式：播放头实时跟踪运行时动画位置（以 60fps 从 C++ 时间轴系统轮询）。工具栏显示红色闪烁的"LIVE"指示器。LIVE 模式下编辑器播放控件被禁用，退出 Play 模式后恢复。
+
+### 时间轴编辑改进
+
+- **多选关键帧**：Ctrl+点击切换选择、Shift+点击范围选择、框选
+- **批量操作**：批量移动或删除选中的关键帧，作为单次撤销步骤
+- **插值预设**：右键关键帧可应用 Linear、EaseIn、EaseOut、EaseInOut 或 Step
+- **标记与事件轨道**：新增标记和自定义事件轨道类型
+- **网格吸附**：工具栏切换网格吸附；拖拽时关键帧吸附到网格线
+- **播放控制**：逐帧前进/后退、速度控制（0.25x–4x）、循环模式切换（Once/Loop/PingPong）
+- **时长编辑**：双击时间显示可编辑总时长
+- **轨道管理**：拖拽排序、右键重命名/删除、类型颜色标识
+
+## 物理：关节、射线检测与查询
+
+### 关节类型
+
+五种关节类型可用于连接物理体：
+
+- **Distance Joint**：保持两个物理体之间的固定距离
+- **Revolute Joint**：围绕共享锚点的铰链旋转，支持可选马达和角度限制
+- **Prismatic Joint**：沿轴线线性滑动，支持可选马达和平移限制
+- **Weld Joint**：将两个物理体刚性绑定
+- **Wheel Joint**：组合旋转和平移行为，适用于车辆悬挂
+
+### 空间查询
+
+- **射线检测**：在物理世界中投射射线，获取所有命中结果（碰撞点、法线、距离、实体）
+- **重叠查询**：用圆形测试世界中的重叠物理体
+- **复合形状**：在单个物理体上附加多个碰撞形状
+
+### 编辑器集成
+
+新增物理编辑器插件，可在 Inspector 中直接可视化配置关节和形状。
+
+## Spine：混合、事件与 IK
+
+- **动画混合**：Spine 动画之间可配置混合时长的交叉淡入淡出
+- **事件系统**：通过 `SpineModuleController` 监听 Spine 动画事件（start、end、complete、custom）
+- **附件控制**：通过 `SpineController` 在运行时显示/隐藏插槽和替换附件
+- **IK 约束**：在 Spine 骨架中配置反向动力学约束
+- **插槽颜色**：以编程方式为单个 Spine 插槽着色
+
+性能改进：
+- 多相机渲染时缓存网格提取结果
+- 网格分配每帧最多批处理为 2 次
+- 变换矩阵计算移至 C++ 以减少开销
+
+## Tilemap：动画瓦片与等距视角
+
+- **动画瓦片**：瓦片可引用自动播放的动画序列
+- **瓦片属性**：访问 Tiled 中定义的自定义瓦片属性
+- **翻转与旋转**：瓦片支持水平/垂直翻转和 90 度旋转
+- **等距网格**：支持等距瓦片地图渲染
+- **调试可视化**：切换瓦片地图网格覆盖层用于调试
+- **Tilemap API**：新增 `tilemapAPI` 模块用于运行时瓦片操作（setTile、getTile、fillRect 等）
+
+## 锚点支持
+
+精灵现在支持可配置的锚点（pivot），影响旋转、缩放和定位。编辑器在 Scene View 中显示可拖拽的锚点覆盖层。边界计算考虑非中心锚点。
+
+## 编辑器改进
+
+- **资产选择对话框**：可复用的资产选择模态框，支持按类型筛选、网格预览和搜索
+- **设置验证**：项目设置现在基于 JSON Schema 验证，提前暴露配置错误
+- **改进的检查器**：AnimClip 和 BitmapFont 检查器重新设计，UX 更佳
+- **内容浏览器**：资产网格支持额外的预览模式
+
+## 引擎内部
+
+- C++ Registry 新增实体销毁清理钩子
+- 混合状态从文件级静态变量移至 RenderCommand 类成员
+- 物理和 Spine 全局状态封装为上下文结构体
+- `App.physicsInitPromise` 用于等待异步物理初始化
diff --git a/docs/astro/src/content/docs/zh/guides/input.mdx b/docs/astro/src/content/docs/zh/guides/input.mdx
@@ -104,6 +104,31 @@ if (input.isMouseButtonReleased(0)) {
 }
 ```
 
+<Aside type="caution">
+  `getMousePosition()` 返回的是**屏幕坐标**（相对于 Canvas 元素的 CSS 像素），不是世界坐标。如果需要与场景中的实体交互，请使用 `UICameraInfo` 获取世界坐标——参见下方[屏幕坐标转世界坐标](#屏幕坐标转世界坐标)。
+</Aside>
+
+### 屏幕坐标转世界坐标
+
+使用 UI 插件时（`createWebApp` 默认包含），`UICameraInfo` 每帧自动将鼠标位置转换为世界坐标：
+
+```typescript
+import { defineSystem, addSystem, Res, Input, UICameraInfo } from 'esengine';
+
+addSystem(defineSystem(
+    [Res(Input), Res(UICameraInfo)],
+    (input, camera) => {
+        if (input.isMouseButtonPressed(0)) {
+            // 世界坐标，可直接用于场景交互
+            const wx = camera.worldMouseX;
+            const wy = camera.worldMouseY;
+            spawnBullet(wx, wy);
+        }
+    }
+));
+```
+
+
 ## 滚轮输入
 
 ```typescript
diff --git a/docs/astro/src/content/docs/zh/guides/spine.mdx b/docs/astro/src/content/docs/zh/guides/spine.mdx
diff --git a/docs/astro/src/content/docs/zh/guides/timeline.mdx b/docs/astro/src/content/docs/zh/guides/timeline.mdx
diff --git a/sdk/tests/timeline-loader.test.ts b/sdk/tests/timeline-loader.test.ts
