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.0 documentation for new features and API updates

esengineb80d3b8ee632
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 13558eb91..07f10fba9 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -73,6 +73,7 @@ export default defineConfig({
{ label: 'Sprite Animation', translations: { 'zh-CN': '精灵动画' }, slug: 'guides/sprite-animation' },
{ label: 'Tween Animation', translations: { 'zh-CN': '补间动画' }, slug: 'guides/tween' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
+ { label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },
{ label: 'Bitmap Text', translations: { 'zh-CN': '位图文本' }, slug: 'guides/bitmap-text' },
{ label: 'Custom Draw', translations: { 'zh-CN': '自定义绘制' }, slug: 'guides/custom-draw' },
{ label: 'Post-Processing', translations: { 'zh-CN': '后处理效果' }, slug: 'guides/post-processing' },
@@ -93,6 +94,7 @@ export default defineConfig({
{ label: 'Interaction', translations: { 'zh-CN': '交互' }, slug: 'guides/ui-interaction' },
{ label: 'Widgets', translations: { 'zh-CN': '控件' }, slug: 'guides/ui-widgets' },
{ label: 'Masking & SafeArea', translations: { 'zh-CN': '遮罩与安全区' }, slug: 'guides/ui-masking' },
+ { label: 'UI Builder', translations: { 'zh-CN': 'UI 构建器' }, slug: 'guides/ui-builder' },
],
},
{
@@ -149,6 +151,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.9.0', slug: 'changelog-v090' },
{ label: 'v0.8.3', slug: 'changelog-v083' },
{ label: 'v0.8.2', slug: 'changelog-v082' },
{ label: 'v0.8.1', slug: 'changelog-v081' },
diff --git a/docs/astro/src/content/docs/changelog-v090.mdx b/docs/astro/src/content/docs/changelog-v090.mdx
new file mode 100644
index 000000000..29466917d
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v090.mdx
@@ -0,0 +1,129 @@
+---
+title: v0.9.0
+description: ESEngine v0.9.0 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.9.0 brings a Timeline animation system, async system support, a declarative UI builder, Spine multi-version architecture, a Frame Debugger, and major performance optimizations to query iteration and the rendering pipeline.
+</Aside>
+
+## Timeline System
+
+A new multi-track animation system for coordinating property animations, Spine playback, sprite animations, audio events, and entity activation over time.
+
+- **`TimelinePlayer` component** — attach to any entity, set a `.estl` timeline asset and control playback with `playing`, `speed`, and `wrapMode` (`once`, `loop`, `pingPong`)
+- **`TimelineControl` API** — `play()`, `pause()`, `stop()`, `setTime()`, `isPlaying()`, `getCurrentTime()` for runtime control
+- **5 track types** — Property (keyframe interpolation), Spine (animation clips), Sprite Animation, Audio (timed events), Activation (enable/disable entities)
+- **Editor Timeline panel** — visual track editor with keyframe editing, right-click context menu, and horizontal scroll
+
+See the [Timeline guide](/microes/guides/timeline/) for the full API.
+
+## Async Systems
+
+`defineSystem` now accepts `async` functions. Systems can `await` promises, and Commands are automatically flushed after the async function completes. Works in all schedule phases.
+
+```typescript
+addStartupSystem(defineSystem(
+ [Res(Prefabs)],
+ async (prefabs) => {
+ const { root } = await prefabs.instantiate('prefabs/Enemy.esprefab');
+ }
+));
+```
+
+See [Systems](/microes/core-concepts/systems/#async-systems) for details.
+
+## UI Builder
+
+A declarative API for creating UI hierarchies from code. Factory methods (`UI.button()`, `UI.slider()`, `UI.toggle()`, etc.) spawn fully configured widget entities in one call. A tree builder (`UI.build()`) creates nested hierarchies from JSON-like definitions.
+
+- **Theming** — all widgets pull defaults from `UITheme` resource; `DARK_THEME` built-in
+- **Event callbacks** — `onClick`, `onChange`, `onSubmit` on widget options
+- **Entity refs** — capture created entities via `ref` callback on any node
+
+See the [UI Builder guide](/microes/guides/ui-builder/) for the full API.
+
+## UIEvents Callback API
+
+In addition to polling events with `events.query()`, you can now subscribe with callbacks:
+
+- `events.on(entity, type, handler)` — entity-scoped subscription
+- `events.on(type, handler)` — global subscription
+- Both return an `Unsubscribe` function
+
+A new `makeInteractable(world, entity)` helper simplifies adding the `Interactable` component with sensible defaults.
+
+## Spine Multi-Version Architecture
+
+Spine now supports versions **3.8**, **4.1**, and **4.2** simultaneously with automatic version detection. The engine selects the best backend (C++ native or WASM fallback) transparently.
+
+- `SpineVersion` type exported for advanced introspection
+- `SpineManager` provides runtime queries: `getEntityVersion()`, `getAnimations()`, `getSkins()`, `getBounds()`
+- Spine and Tilemap rendering migrated to C++ renderer plugins, removing the JS-side `ExternalMeshPlugin`
+
+## Frame Debugger
+
+A new debugging tool for inspecting the render pipeline draw-by-draw.
+
+- **Editor panel** — capture a frame, browse draw calls, replay to any point, inspect in a detached window
+- **SDK API** — `Renderer.captureNextFrame()`, `Renderer.getCapturedData()`, `Renderer.replayToDrawCall()`, `Renderer.getSnapshotImageData()`
+- **Diagnostics** — `FlushReason` (why batches break), `RenderType` (sprite/text/spine/particle), per-draw-call metadata
+
+See [Debugging](/microes/guides/debugging/#frame-debugger) for usage.
+
+## Renderer v2
+
+The rendering pipeline has been unified and optimized:
+
+- **`Renderer.submitAll()`** — single call replaces 6 per-type submit methods (sprites, text, spine, particles, shapes, UI)
+- **`SubmitSkipFlags`** — selectively skip Spine or Particle submission
+- **Vertex format compression** — `UByte4N` packed color attribute reduces vertex size
+- **RenderFrame decoupled** from `BatchRenderer2D` for cleaner architecture
+- **Mask processing** moved to C++ for better performance
+
+## Performance Optimizations
+
+Significant improvements to ECS query iteration and component access:
+
+- **Query iteration** — 40–70% faster via manual iterator, pre-allocated result objects, and switch-based `forEach` dispatch
+- **Component reads/writes** — pointer-based access bypassing embind marshalling for Transform, Sprite, Camera, Velocity, UIRect, physics components
+- **`world.has()` / `tryGet()`** — JS-side entity set tracking eliminates WASM round-trips
+- **Physics sync** — 37× faster body position synchronization
+- **Change detection** — eliminated query cache miss array copies
+- **System runner** — cached `QueryInstance` eliminates per-run allocations
+
+## Editor Improvements
+
+### Architecture Overhaul
+
+- **Service-oriented architecture** — Editor god object decomposed into services with IoC container (`EditorContainer`)
+- **EditorPlugin system** — decentralized registration replacing centralized switch dispatch
+- **DisposableStore** — fixes event listener leaks across panels
+- **PropertyWritePipeline** — unified property change handling replacing per-component switch
+
+### UI & UX
+
+- **Redesigned theme** — HSL color system with design tokens for consistent styling
+- **Multi-window support** — floating panels with command replication across windows
+- **Extensions panel** — manage editor extensions with detachable window support
+- **Timeline panel** — track editing with right-click context menu and horizontal scroll
+
+## Bug Fixes
+
+### Rendering
+- Fixed UI layer ordering and text rendering issues after renderer v2 refactor
+- Fixed tilemap flickering by ensuring transforms update before tile submission
+- Restored stats collection and external triangle submission
+
+### Editor
+- Fixed UIRect entity position jump on gizmo drag end
+- Fixed timeline horizontal scroll and frame debugger click in live mode
+- Fixed PostProcessVolume inspector registration key mismatch
+- Fixed cross-platform `openFile` and `openInEditor` commands
+
+### SDK
+- Fixed JS builtin entity tracking when C++ adds components directly
+- Exported shared `.d.ts` files to user projects for IntelliSense
+- Simplified UI dropdown positioning and added color equality guards
diff --git a/docs/astro/src/content/docs/core-concepts/resources.mdx b/docs/astro/src/content/docs/core-concepts/resources.mdx
index e2901fd1a..bbf6e13f9 100644
--- a/docs/astro/src/content/docs/core-concepts/resources.mdx
+++ b/docs/astro/src/content/docs/core-concepts/resources.mdx
@@ -103,7 +103,23 @@ defineSystem([Res(UIEvents)], (events) => {
});
```
-See [UI Interaction](/microes/guides/ui-interaction/) for the full list of event types.
+You can also subscribe to events with callbacks using `.on()`:
+
+```typescript
+defineSystem([Res(UIEvents)], (events) => {
+ // Subscribe to a specific entity's events
+ const unsub = events.on(buttonEntity, 'click', (e) => {
+ console.log('Button clicked!');
+ });
+
+ // Subscribe to all events of a type
+ events.on('change', (e) => {
+ console.log('Value changed on:', e.entity);
+ });
+});
+```
+
+See [UI Interaction](/microes/guides/ui-interaction/) for the full list of event types and the callback API.
## Custom Resources
diff --git a/docs/astro/src/content/docs/core-concepts/systems.mdx b/docs/astro/src/content/docs/core-concepts/systems.mdx
index 6861d4245..de0bb2d1d 100644
--- a/docs/astro/src/content/docs/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/core-concepts/systems.mdx
@@ -316,6 +316,28 @@ addSystem(defineSystem(
));
```
+## Async Systems
+
+`defineSystem` accepts async functions. This is useful for startup systems that need to load assets, or systems that call async APIs:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, Prefabs } from 'esengine';
+
+addStartupSystem(defineSystem(
+ [Res(Prefabs)],
+ async (prefabs) => {
+ const { root } = await prefabs.instantiate('prefabs/Enemy.esprefab');
+ console.log('Spawned enemy:', root);
+ }
+));
+```
+
+Async systems work in all schedule phases. No special declaration is needed — just pass an `async` function and the engine handles the rest. Commands are automatically flushed after the async function completes.
+
+<Aside type="caution">
+ Async systems that take a long time will delay subsequent systems in the same schedule phase. Keep async work short or move heavy loading to `Startup`.
+</Aside>
+
## Error Handling
Each system runs inside its own try/catch boundary. If a system throws an error, it is caught and logged to the console without crashing the entire game loop. Other systems continue to execute normally.
diff --git a/docs/astro/src/content/docs/guides/debugging.mdx b/docs/astro/src/content/docs/guides/debugging.mdx
index 6893eb785..800e1673c 100644
--- a/docs/astro/src/content/docs/guides/debugging.mdx
+++ b/docs/astro/src/content/docs/guides/debugging.mdx
@@ -153,6 +153,69 @@ The editor's Game View panel provides a graphical playback control toolbar:
These controls call the `setPaused()`, `stepFrame()`, and `setPlaySpeed()` APIs described above.
+## Frame Debugger
+
+The Frame Debugger lets you capture a single frame and inspect every draw call — useful for diagnosing batching issues, unexpected flush reasons, and render order problems.
+
+### Editor Panel
+
+In the editor, open the **Frame Debugger** panel (available as a detachable window). Click **Capture** to freeze the current frame. The panel displays each draw call with its type, texture, material, triangle count, flush reason, and stencil/scissor state. Click a draw call to replay rendering up to that point and see the intermediate result.
+
+### SDK API
+
+You can also capture and analyze frames programmatically:
+
+```typescript
+import { Renderer, FlushReason, RenderType } from 'esengine';
+
+// Trigger capture (takes effect next frame)
+Renderer.captureNextFrame();
+
+// After the frame renders, retrieve the captured data
+const capture = Renderer.getCapturedData();
+if (capture) {
+ for (const dc of capture.drawCalls) {
+ console.log(
+ `#${dc.index} ${RenderType[dc.type]} | ` +
+ `${dc.triangleCount} tris | ` +
+ `flush: ${FlushReason[dc.flushReason]}`
+ );
+ }
+}
+
+// Replay to a specific draw call for visual inspection
+Renderer.replayToDrawCall(3);
+const snapshot = Renderer.getSnapshotImageData();
+```
+
+### FlushReason
+
+Why the renderer started a new draw call:
+
+| Reason | Description |
+|--------|-------------|
+| `BatchFull` | Vertex buffer capacity reached |
+| `TextureSlotsFull` | All texture slots occupied |
+| `ScissorChange` | Scissor rect changed (UIMask) |
+| `StencilChange` | Stencil state changed |
+| `MaterialChange` | Different material/shader |
+| `BlendModeChange` | Blend mode changed |
+| `StageEnd` | Render stage boundary |
+| `TypeChange` | Different render type (sprite → text) |
+| `FrameEnd` | End of frame flush |
+
+### RenderType
+
+| Type | Description |
+|------|-------------|
+| `Sprite` | Sprite rendering |
+| `Text` | Bitmap text |
+| `Spine` | Spine skeleton |
+| `Particle` | Particle emitter |
+| `Shape` | Shape renderer |
+| `UIElement` | UI element |
+| `Mesh` | Custom mesh |
+
## WASM Debugging
The engine core runs as WebAssembly. WASM debugging requires a debug build of the engine.
diff --git a/docs/astro/src/content/docs/guides/plugins.mdx b/docs/astro/src/content/docs/guides/plugins.mdx
index f99df1f36..371ef55b9 100644
--- a/docs/astro/src/content/docs/guides/plugins.mdx
+++ b/docs/astro/src/content/docs/guides/plugins.mdx
@@ -18,6 +18,7 @@ When you create a project in the editor, all built-in plugins are active by defa
| Asset loading | `AssetServer` for loading textures, Spine data, prefabs, and other assets at runtime |
| Prefabs | `Prefabs` resource for instantiating prefabs |
| Input | `Input` resource with keyboard, mouse, and touch input -- cleared each frame |
+| Timeline | `TimelinePlayer` component for playing timeline animations, `TimelineControl` runtime API |
### UI Plugins
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index 6a6fe99f6..afa48fdfb 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -138,6 +138,40 @@ addSystem(defineSystem(
));
```
+## Multi-Version Architecture
+
+ESEngine 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.
+
+```typescript
+import type { SpineVersion } from 'esengine';
+// SpineVersion = '3.8' | '4.1' | '4.2'
+```
+
+### How It Works
+
+- When a Spine asset is loaded, the engine detects the version from the skeleton file header
+- A matching backend is selected automatically: C++ native (preferred) or WASM fallback
+- No code changes are needed — the same `SpineAnimation` component works with all versions
+
+### SpineManager Runtime API
+
+For advanced use cases, the `SpineManager` provides runtime introspection:
+
+```typescript
+import { SpineManager } from 'esengine';
+
+// Detect version from raw data (before loading)
+const version = SpineManager.detectVersion(skelBinaryData);
+const versionJson = SpineManager.detectVersionJson(skelJsonString);
+
+// Query a loaded entity
+const manager = app.getResource(SpineManager);
+const ver = manager.getEntityVersion(entity); // '3.8' | '4.1' | '4.2'
+const anims = manager.getAnimations(entity); // ['idle', 'run', 'jump']
+const skins = manager.getSkins(entity); // ['default', 'warrior']
+const bounds = manager.getBounds(entity); // { x, y, width, height }
+```
+
## Multi-Texture Batching
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.
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
new file mode 100644
index 000000000..130dfed55
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -0,0 +1,141 @@
+---
+title: Timeline
+description: Timeline animation system in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The **Timeline** system drives multi-track animations that coordinate property changes, Spine playback, sprite animations, audio events, and entity activation over time. Timelines are created in the editor's Timeline panel and played back at runtime via the `TimelinePlayer` component and `TimelineControl` API.
+
+<Aside type="note">
+ The timeline plugin is included by default — no manual setup is needed.
+</Aside>
+
+## Editor Workflow
+
+1. Select an entity in the Hierarchy
+2. Open the **Timeline** panel
+3. Click **+** to add tracks (Property, Spine, Sprite Animation, Audio, Activation)
+4. Add keyframes by clicking on the timeline ruler
+5. The timeline is saved as a `.estl` asset file
+
+### Track Types
+
+| Type | Description |
+|------|-------------|
+| 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 |
+| Audio | Trigger audio events at specific times |
+| Activation | Enable/disable entities over time ranges |
+
+## TimelinePlayer Component
+
+Add `TimelinePlayer` to an entity to play a timeline asset at runtime. Configure it in the editor Inspector or from code.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `timeline` | string | `''` | Path to the `.estl` timeline asset |
+| `playing` | boolean | `false` | Whether the timeline is currently playing |
+| `speed` | number | `1.0` | Playback speed multiplier |
+| `wrapMode` | string | `'once'` | `'once'`, `'loop'`, or `'pingPong'` |
+
+### WrapMode
+
+| Value | Description |
+|-------|-------------|
+| `once` | Play once and stop at the end |
+| `loop` | Restart from the beginning when finished |
+| `pingPong` | Alternate between forward and reverse playback |
+
+## TimelineControl API
+
+Use `TimelineControl` to control timeline playback from systems:
+
+```typescript
+import { defineSystem, addSystem, Query, TimelinePlayer, TimelineControl } from 'esengine';
+import { Res, Input } from 'esengine';
+
+addSystem(defineSystem(
+ [Res(Input), Query(TimelinePlayer)],
+ (input, query) => {
+ for (const [entity] of query) {
+ if (input.isKeyPressed('Space')) {
+ TimelineControl.play(entity);
+ }
+ if (input.isKeyPressed('KeyP')) {
+ TimelineControl.pause(entity);
+ }
+ }
+ }
+));
+```
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `TimelineControl.play(entity)` | void | Start or resume playback |
+| `TimelineControl.pause(entity)` | void | Pause playback |
+| `TimelineControl.stop(entity)` | void | Stop and reset to the beginning |
+| `TimelineControl.setTime(entity, time)` | void | Seek to a specific time (seconds) |
+| `TimelineControl.isPlaying(entity)` | boolean | Check if timeline is playing |
+| `TimelineControl.getCurrentTime(entity)` | number | Get current playback time (seconds) |
+
+## Registering Timeline Assets
+
+When loading timelines outside the editor (e.g., in a custom asset pipeline), use the registration API:
+
+```typescript
+import { registerTimelineAsset, getTimelineAsset, parseTimelineAsset } from 'esengine';
+
+// Parse raw timeline data
+const asset = parseTimelineAsset(jsonData);
+
+// Register for runtime lookup
+registerTimelineAsset('timelines/intro.estl', asset);
+
+// Retrieve later
+const tl = getTimelineAsset('timelines/intro.estl');
+```
+
+## Example: Intro Sequence
+
+```typescript
+import {
+ defineSystem, addStartupSystem, addSystem,
+ Query, Mut, TimelinePlayer, TimelineControl, Res, Input
+} from 'esengine';
+
+// Play the intro timeline on startup
+addStartupSystem(defineSystem(
+ [Query(Mut(TimelinePlayer))],
+ (query) => {
+ for (const [entity, player] of query) {
+ if (player.timeline === 'timelines/intro.estl') {
+ TimelineControl.play(entity);
+ }
+ }
+ }
+));
+
+// Allow skipping with any key
+addSystem(defineSystem(
+ [Res(Input), Query(TimelinePlayer)],
+ (input, query) => {
+ if (input.isKeyPressed('Space')) {
+ for (const [entity, player] of query) {
+ if (TimelineControl.isPlaying(entity)) {
+ TimelineControl.stop(entity);
+ }
+ }
+ }
+ }
+));
+```
+
+## Next Steps
+
+- [Tween Animation](/microes/guides/tween/) — code-driven property animation
+- [Spine Animation](/microes/guides/spine/) — skeletal animation
+- [Sprite Animation](/microes/guides/sprite-animation/) — frame-by-frame sprite animation
diff --git a/docs/astro/src/content/docs/guides/ui-builder.mdx b/docs/astro/src/content/docs/guides/ui-builder.mdx
new file mode 100644
index 000000000..4ce1c52e8
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/ui-builder.mdx
@@ -0,0 +1,265 @@
+---
+title: UI Builder
+description: Declarative UI construction API in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The `UI` builder provides a code-first way to create UI hierarchies. Instead of manually spawning entities and inserting components, use factory methods that handle all the wiring automatically.
+
+<Aside type="tip">
+ The UI builder is for **runtime UI creation from code**. For designing UI in the visual editor, see [UI Layout](/microes/guides/ui/).
+</Aside>
+
+## Factory Methods
+
+Each method spawns a fully configured UI entity and returns its `Entity` ID:
+
+```typescript
+import { UI } from 'esengine';
+
+const btn = UI.button(world, { text: 'Play', parent: rootEntity });
+const slider = UI.slider(world, { value: 0.5, parent: rootEntity });
+const label = UI.label(world, { text: 'Score: 0', parent: rootEntity });
+```
+
+### Available Factories
+
+| Method | Description |
+|--------|-------------|
+| `UI.label(world, options)` | Text label |
+| `UI.panel(world, options)` | Container with background color |
+| `UI.button(world, options)` | Clickable button with text |
+| `UI.slider(world, options)` | Value slider with fill and handle |
+| `UI.toggle(world, options)` | Checkbox/toggle switch |
+| `UI.progressBar(world, options)` | Non-interactive progress display |
+| `UI.textInput(world, options)` | Editable text field |
+| `UI.dropdown(world, options)` | Dropdown selector |
+| `UI.scrollView(world, options)` | Scrollable container |
+| `UI.flexRow(world, options)` | Horizontal flex layout container |
+| `UI.flexColumn(world, options)` | Vertical flex layout container |
+
+## Widget Options
+
+All options are optional unless noted. Defaults come from the active theme.
+
+<Aside type="caution">
+ Event callbacks (`onClick`, `onChange`, `onSubmit`) require passing the `events` (UIEventQueue) instance. Without it, callbacks are silently ignored.
+</Aside>
+
+### ButtonOptions
+
+```typescript
+UI.button(world, {
+ text: 'Click Me', // default: 'Button'
+ fontSize: 16, // default: theme.fontSize.md
+ size: { x: 150, y: 40 }, // default: { x: 120, y: 36 }
+ color: { r: 0.2, g: 0.5, b: 0.9, a: 1 },
+ textColor: { r: 1, g: 1, b: 1, a: 1 },
+ transition: null, // ColorTransition or null
+ parent: rootEntity,
+ events: uiEvents, // required for onClick/onHover to work
+ onClick: (entity) => console.log('Clicked!'),
+});
+```
+
+### SliderOptions
+
+```typescript
+UI.slider(world, {
+ value: 0.5,
+ minValue: 0,
+ maxValue: 1,
+ wholeNumbers: false,
+ size: { x: 200, y: 16 },
+ trackColor: { r: 0.15, g: 0.15, b: 0.15, a: 1 },
+ fillColor: { r: 0.25, g: 0.56, b: 0.96, a: 1 },
+ handleSize: { x: 24, y: 24 },
+ handleColor: { r: 1, g: 1, b: 1, a: 1 },
+ parent: rootEntity,
+ events: uiEvents, // required for onChange to work
+ onChange: (value, entity) => console.log('Value:', value),
+});
+```
+
+### ToggleOptions
+
+```typescript
+UI.toggle(world, {
+ isOn: true,
+ size: { x: 24, y: 24 },
+ onColor: { r: 0.2, g: 0.6, b: 1, a: 1 },
+ offColor: { r: 0.4, g: 0.4, b: 0.4, a: 1 },
+ label: 'Enable sound', // optional text label
+ group: toggleGroupEntity, // for radio-button behavior
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (isOn, entity) => console.log('Toggle:', isOn),
+});
+```
+
+### TextInputOptions
+
+```typescript
+UI.textInput(world, {
+ placeholder: 'Enter name...',
+ value: '',
+ size: { x: 200, y: 36 },
+ fontSize: 16,
+ maxLength: 0, // 0 = unlimited
+ multiline: false,
+ password: false,
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (value, entity) => console.log('Text:', value),
+ onSubmit: (value, entity) => console.log('Submit:', value),
+});
+```
+
+### DropdownOptions
+
+```typescript
+UI.dropdown(world, {
+ options: ['Easy', 'Normal', 'Hard'], // required
+ selectedIndex: 1,
+ size: { x: 160, y: 32 },
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (index, entity) => console.log('Selected:', index),
+});
+```
+
+### FlexOptions
+
+```typescript
+UI.flexRow(world, {
+ gap: 8,
+ padding: { left: 12, top: 12, right: 12, bottom: 12 },
+ wrap: false,
+ justifyContent: 'center', // 'start', 'center', 'end', 'spaceBetween', 'spaceAround', 'spaceEvenly'
+ alignItems: 'stretch', // 'stretch', 'start', 'center', 'end'
+ parent: rootEntity,
+});
+```
+
+## Declarative Tree Builder
+
+For complex UIs, use `UI.build()` to create an entire hierarchy from a nested definition:
+
+```typescript
+import { UI } from 'esengine';
+
+let nameInput: Entity;
+
+const form = UI.build(world, {
+ type: 'panel',
+ options: { size: { x: 400, y: 300 } },
+ children: [
+ {
+ type: 'label',
+ options: { text: 'Player Setup', fontSize: 20 },
+ },
+ {
+ type: 'textInput',
+ options: { placeholder: 'Enter name' },
+ ref: (entity) => { nameInput = entity; },
+ },
+ {
+ type: 'flexRow',
+ options: { gap: 8 },
+ children: [
+ {
+ type: 'button',
+ options: { text: 'Cancel' },
+ },
+ {
+ type: 'button',
+ options: { text: 'Start', onClick: () => startGame() },
+ },
+ ],
+ },
+ ],
+});
+```
+
+### Node Types
+
+| Type | Children | Description |
+|------|----------|-------------|
+| `element` | Yes | Raw UI entity with manual component configuration |
+| `label` | No | Text label |
+| `button` | No | Button widget |
+| `slider` | No | Slider widget |
+| `toggle` | No | Toggle widget |
+| `textInput` | No | Text input |
+| `dropdown` | No | Dropdown selector |
+| `progressBar` | No | Progress bar |
+| `panel` | Yes | Container with background |
+| `flexRow` | Yes | Horizontal flex container |
+| `flexColumn` | Yes | Vertical flex container |
+| `scrollView` | Yes | Scrollable container (children auto-parent to content) |
+
+### Entity Refs
+
+Use `ref` on any node to capture the created entity:
+
+```typescript
+let sliderRef: Entity;
+
+UI.build(world, {
+ type: 'slider',
+ options: { value: 0.5 },
+ ref: (entity) => { sliderRef = entity; },
+});
+```
+
+## Theming
+
+All widgets use the active `UITheme` for default colors, sizes, and fonts. The built-in `DARK_THEME` is used by default.
+
+### Custom Theme
+
+Override the theme by inserting `UIThemeRes` before initialization:
+
+```typescript
+import { UIThemeRes, DARK_THEME } from 'esengine';
+
+const myTheme = {
+ ...DARK_THEME,
+ primary: { r: 0.9, g: 0.3, b: 0.1, a: 1 },
+ button: {
+ ...DARK_THEME.button,
+ color: { r: 0.9, g: 0.3, b: 0.1, a: 1 },
+ },
+};
+
+cmds.insertResource(UIThemeRes, myTheme);
+```
+
+### UITheme Properties
+
+| Group | Properties |
+|-------|-----------|
+| Colors | `primary`, `secondary`, `background`, `surface`, `error`, `text`, `textSecondary`, `border` |
+| Typography | `fontFamily`, `fontSize` (`xs`, `sm`, `md`, `lg`, `xl`) |
+| Spacing | `spacing` (`xs`, `sm`, `md`, `lg`, `xl`) |
+| Button | `height`, `color`, `textColor`, `transition` |
+| Slider | `trackHeight`, `trackColor`, `fillColor`, `handleSize`, `handleColor` |
+| Toggle | `size`, `onColor`, `offColor`, `checkColor` |
+| Input | `height`, `backgroundColor`, `textColor`, `placeholderColor`, `fontSize`, `padding` |
+| Dropdown | `height`, `backgroundColor`, `itemHeight` |
+| Panel | `backgroundColor`, `padding` |
+
+## Cleanup
+
+Remove a UI entity and all its children:
+
+```typescript
+UI.destroy(world, formEntity);
+```
+
+## Next Steps
+
+- [UI Layout](/microes/guides/ui/) — anchor-based layout with UIRect
+- [UI Widgets](/microes/guides/ui-widgets/) — component-level widget reference
+- [UI Interaction](/microes/guides/ui-interaction/) — events and callbacks
diff --git a/docs/astro/src/content/docs/guides/ui-interaction.mdx b/docs/astro/src/content/docs/guides/ui-interaction.mdx
index cd3a4ae45..55e963ce7 100644
--- a/docs/astro/src/content/docs/guides/ui-interaction.mdx
+++ b/docs/astro/src/content/docs/guides/ui-interaction.mdx
@@ -90,6 +90,52 @@ if (events.hasEvent(buttonEntity, 'click')) {
const all = events.drain();
```
+### Callback Subscriptions
+
+Instead of polling events each frame, you can subscribe to events with callbacks using `.on()`. This is ideal for one-off setup in startup systems:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, GetWorld } from 'esengine';
+import { UIEvents, makeInteractable } from 'esengine';
+
+addStartupSystem(defineSystem(
+ [Res(UIEvents), GetWorld()],
+ (events, world) => {
+ const button = findEntityByName(world, 'StartButton');
+
+ // Entity-scoped: only fires for this entity
+ const unsub = events.on(button, 'click', (e) => {
+ console.log('Start button clicked!');
+ });
+
+ // Global: fires for any entity with this event type
+ events.on('change', (e) => {
+ console.log('Value changed on:', e.entity);
+ });
+
+ // Call unsub() to remove the listener
+ }
+));
+```
+
+| Overload | Description |
+|----------|-------------|
+| `events.on(entity, type, handler)` | Subscribe to events on a specific entity. Returns `Unsubscribe` function |
+| `events.on(type, handler)` | Subscribe to all events of a type globally. Returns `Unsubscribe` function |
+
+### makeInteractable
+
+Helper function to ensure an entity has the `Interactable` component with sensible defaults:
+
+```typescript
+import { makeInteractable } from 'esengine';
+
+makeInteractable(world, entity);
+// Equivalent to adding Interactable with { enabled: true, blockRaycast: true, raycastTarget: true }
+```
+
+Use this when creating interactive entities from code — it avoids manually importing and inserting the `Interactable` component.
+
### Event Bubbling
`press`, `release`, and `click` events bubble up the entity hierarchy. If a parent has `Interactable` with `blockRaycast: true`, bubbling stops there. `hover_enter` and `hover_exit` do **not** bubble.
diff --git a/docs/astro/src/content/docs/guides/ui-widgets.mdx b/docs/astro/src/content/docs/guides/ui-widgets.mdx
index ab714fac4..2171aa468 100644
--- a/docs/astro/src/content/docs/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/guides/ui-widgets.mdx
@@ -281,6 +281,23 @@ Virtual scrolling for large lists — only visible items are rendered.
| `scrollY` | number | `0` | Scroll position |
| `overscan` | number | `2` | Extra items above/below viewport |
+### Custom Item Renderer
+
+Use `setListViewRenderer()` to define how each list item is populated. The callback receives the item index and the entity to configure:
+
+```typescript
+import { setListViewRenderer, Text, Sprite } from 'esengine';
+
+setListViewRenderer(listEntity, (index, itemEntity) => {
+ world.set(itemEntity, Text, { content: `Item ${index}`, fontSize: 16 });
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `index` | number | 0-based index of the list item |
+| `entity` | Entity | The spawned entity for this item — populate it with components |
+
## TextInput
Editable text field with cursor, selection, and placeholder.
diff --git a/docs/astro/src/content/docs/zh/changelog-v090.mdx b/docs/astro/src/content/docs/zh/changelog-v090.mdx
new file mode 100644
index 000000000..52b87a7b5
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v090.mdx
@@ -0,0 +1,129 @@
+---
+title: v0.9.0
+description: ESEngine v0.9.0 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.9.0 带来了时间轴动画系统、异步系统支持、声明式 UI 构建器、Spine 多版本架构、帧调试器,以及查询迭代和渲染管线的重大性能优化。
+</Aside>
+
+## 时间轴系统
+
+全新的多轨道动画系统,用于协调属性动画、Spine 播放、精灵动画、音频事件和实体激活。
+
+- **`TimelinePlayer` 组件** — 挂载到任意实体,设置 `.estl` 时间轴资源,通过 `playing`、`speed`、`wrapMode`(`once`、`loop`、`pingPong`)控制播放
+- **`TimelineControl` API** — `play()`、`pause()`、`stop()`、`setTime()`、`isPlaying()`、`getCurrentTime()` 运行时控制
+- **5 种轨道类型** — Property(关键帧插值)、Spine(动画片段)、Sprite Animation、Audio(定时事件)、Activation(启用/禁用实体)
+- **编辑器 Timeline 面板** — 可视化轨道编辑器,支持关键帧编辑、右键菜单和水平滚动
+
+详见[时间轴指南](/microes/zh/guides/timeline/)。
+
+## 异步系统
+
+`defineSystem` 现在支持 `async` 函数。系统可以 `await` Promise,Commands 会在异步函数完成后自动刷新。所有调度阶段均可使用。
+
+```typescript
+addStartupSystem(defineSystem(
+ [Res(Prefabs)],
+ async (prefabs) => {
+ const { root } = await prefabs.instantiate('prefabs/Enemy.esprefab');
+ }
+));
+```
+
+详见[系统](/microes/zh/core-concepts/systems/#异步系统)。
+
+## UI 构建器
+
+声明式 API,用于从代码创建 UI 层级。工厂方法(`UI.button()`、`UI.slider()`、`UI.toggle()` 等)一次调用即可创建完整配置的控件实体。树构建器(`UI.build()`)从类 JSON 定义创建嵌套层级。
+
+- **主题化** — 所有控件从 `UITheme` 资源获取默认值;内置 `DARK_THEME`
+- **事件回调** — 控件选项支持 `onClick`、`onChange`、`onSubmit`
+- **实体引用** — 通过 `ref` 回调捕获创建的实体
+
+详见 [UI 构建器指南](/microes/zh/guides/ui-builder/)。
+
+## UIEvents 回调 API
+
+除了通过 `events.query()` 轮询事件外,现在可以使用回调订阅:
+
+- `events.on(entity, type, handler)` — 实体级订阅
+- `events.on(type, handler)` — 全局订阅
+- 均返回 `Unsubscribe` 函数
+
+新增 `makeInteractable(world, entity)` 工具函数,简化添加 `Interactable` 组件。
+
+## Spine 多版本架构
+
+Spine 现在同时支持 **3.8**、**4.1** 和 **4.2** 版本,自动检测版本。引擎透明地选择最佳后端(C++ native 或 WASM fallback)。
+
+- 导出 `SpineVersion` 类型供高级场景使用
+- `SpineManager` 提供运行时查询:`getEntityVersion()`、`getAnimations()`、`getSkins()`、`getBounds()`
+- Spine 和 Tilemap 渲染迁移到 C++ 渲染器插件,移除了 JS 端的 `ExternalMeshPlugin`
+
+## 帧调试器
+
+全新的调试工具,逐 draw call 检查渲染管线。
+
+- **编辑器面板** — 捕获帧、浏览 draw call、回放到任意步骤、支持独立窗口查看
+- **SDK API** — `Renderer.captureNextFrame()`、`Renderer.getCapturedData()`、`Renderer.replayToDrawCall()`、`Renderer.getSnapshotImageData()`
+- **诊断信息** — `FlushReason`(批次中断原因)、`RenderType`(sprite/text/spine/particle)、每个 draw call 的详细元数据
+
+详见[调试](/microes/zh/guides/debugging/#帧调试器)。
+
+## 渲染器 v2
+
+渲染管线统一和优化:
+
+- **`Renderer.submitAll()`** — 单次调用替代 6 个独立提交方法(sprites、text、spine、particles、shapes、UI)
+- **`SubmitSkipFlags`** — 可选跳过 Spine 或 Particle 提交
+- **顶点格式压缩** — `UByte4N` 打包颜色属性减少顶点大小
+- **RenderFrame** 与 `BatchRenderer2D` 解耦,架构更清晰
+- **Mask 处理**迁移至 C++ 以提升性能
+
+## 性能优化
+
+ECS 查询迭代和组件访问的显著改进:
+
+- **查询迭代** — 通过手动迭代器、预分配结果对象和 switch-based `forEach` 分发提速 40–70%
+- **组件读写** — 基于指针的访问绕过 embind 编组,覆盖 Transform、Sprite、Camera、Velocity、UIRect 及物理组件
+- **`world.has()` / `tryGet()`** — JS 端实体集合跟踪消除 WASM 往返调用
+- **物理同步** — body 位置同步提速 37 倍
+- **变更检测** — 消除查询缓存未命中时的数组拷贝
+- **系统运行器** — 缓存 `QueryInstance` 消除每次运行的分配
+
+## 编辑器改进
+
+### 架构重构
+
+- **面向服务架构** — Editor 上帝对象拆分为服务,使用 IoC 容器(`EditorContainer`)
+- **EditorPlugin 系统** — 去中心化注册替代集中式 switch 分发
+- **DisposableStore** — 修复面板间的事件监听器泄漏
+- **PropertyWritePipeline** — 统一属性变更处理替代逐组件 switch
+
+### UI 与交互
+
+- **重设计主题** — HSL 色彩系统配合设计令牌实现一致风格
+- **多窗口支持** — 浮动面板支持跨窗口命令复制
+- **扩展面板** — 管理编辑器扩展,支持独立窗口
+- **Timeline 面板** — 轨道编辑支持右键菜单和水平滚动
+
+## Bug 修复
+
+### 渲染
+- 修复渲染器 v2 重构后的 UI 图层排序和文本渲染问题
+- 修复 tilemap 闪烁(确保 transforms 在 tile 提交前更新)
+- 恢复统计收集和外部三角形提交
+
+### 编辑器
+- 修复 UIRect 实体在 gizmo 拖拽结束时的位置跳动
+- 修复 timeline 水平滚动和帧调试器实时模式下的点击
+- 修复 PostProcessVolume 检查器注册键不匹配
+- 修复跨平台 `openFile` 和 `openInEditor` 命令
+
+### SDK
+- 修复 C++ 直接添加组件时 JS 端内置实体追踪不同步
+- 导出共享 `.d.ts` 文件到用户项目以支持 IntelliSense
+- 简化 UI 下拉定位并添加颜色相等性守卫
diff --git a/docs/astro/src/content/docs/zh/core-concepts/resources.mdx b/docs/astro/src/content/docs/zh/core-concepts/resources.mdx
index 60cce57d5..68898bf26 100644
--- a/docs/astro/src/content/docs/zh/core-concepts/resources.mdx
+++ b/docs/astro/src/content/docs/zh/core-concepts/resources.mdx
@@ -103,7 +103,23 @@ defineSystem([Res(UIEvents)], (events) => {
});
```
-详见 [UI 交互](/microes/zh/guides/ui-interaction/)了解完整的事件类型列表。
+也可以使用 `.on()` 回调方式订阅事件:
+
+```typescript
+defineSystem([Res(UIEvents)], (events) => {
+ // 订阅特定实体的事件
+ const unsub = events.on(buttonEntity, 'click', (e) => {
+ console.log('Button clicked!');
+ });
+
+ // 订阅某类型的所有事件
+ events.on('change', (e) => {
+ console.log('Value changed on:', e.entity);
+ });
+});
+```
+
+详见 [UI 交互](/microes/zh/guides/ui-interaction/)了解完整的事件类型列表和回调 API。
## 自定义资源
diff --git a/docs/astro/src/content/docs/zh/core-concepts/systems.mdx b/docs/astro/src/content/docs/zh/core-concepts/systems.mdx
index c70858fb3..eebd1c8eb 100644
--- a/docs/astro/src/content/docs/zh/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/zh/core-concepts/systems.mdx
@@ -316,6 +316,28 @@ addSystem(defineSystem(
));
```
+## 异步系统
+
+`defineSystem` 支持异步函数。适用于需要加载资源的启动系统,或调用异步 API 的系统:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, Prefabs } from 'esengine';
+
+addStartupSystem(defineSystem(
+ [Res(Prefabs)],
+ async (prefabs) => {
+ const { root } = await prefabs.instantiate('prefabs/Enemy.esprefab');
+ console.log('Spawned enemy:', root);
+ }
+));
+```
+
+异步系统在所有调度阶段均可使用。无需特殊声明——直接传入 `async` 函数即可,引擎会自动处理。Commands 会在异步函数完成后自动刷新。
+
+<Aside type="caution">
+ 耗时较长的异步系统会延迟同一调度阶段中后续系统的执行。尽量保持异步操作简短,或将大量加载移至 `Startup` 阶段。
+</Aside>
+
## 错误处理
每个系统在独立的 try/catch 边界内运行。如果系统抛出错误,会被捕获并输出到控制台,不会导致整个游戏循环崩溃。其他系统继续正常执行。
diff --git a/docs/astro/src/content/docs/zh/guides/debugging.mdx b/docs/astro/src/content/docs/zh/guides/debugging.mdx
index 233182e6e..fe1f5009b 100644
--- a/docs/astro/src/content/docs/zh/guides/debugging.mdx
+++ b/docs/astro/src/content/docs/zh/guides/debugging.mdx
@@ -153,6 +153,69 @@ logger.removeHandler(customHandler);
这些控件直接调用上述 `setPaused()`、`stepFrame()` 和 `setPlaySpeed()` API。
+## 帧调试器
+
+帧调试器可以捕获单帧并检查每个 draw call——适用于诊断批处理问题、异常的 flush 原因和渲染顺序问题。
+
+### 编辑器面板
+
+在编辑器中打开 **Frame Debugger** 面板(支持浮动窗口)。点击 **Capture** 冻结当前帧。面板会显示每个 draw call 的类型、纹理、材质、三角形数量、flush 原因和 stencil/scissor 状态。点击某个 draw call 可以回放渲染到该步骤,查看中间结果。
+
+### SDK API
+
+也可以通过代码捕获和分析帧数据:
+
+```typescript
+import { Renderer, FlushReason, RenderType } from 'esengine';
+
+// 触发捕获(下一帧生效)
+Renderer.captureNextFrame();
+
+// 帧渲染完成后获取捕获数据
+const capture = Renderer.getCapturedData();
+if (capture) {
+ for (const dc of capture.drawCalls) {
+ console.log(
+ `#${dc.index} ${RenderType[dc.type]} | ` +
+ `${dc.triangleCount} tris | ` +
+ `flush: ${FlushReason[dc.flushReason]}`
+ );
+ }
+}
+
+// 回放到特定 draw call 进行视觉检查
+Renderer.replayToDrawCall(3);
+const snapshot = Renderer.getSnapshotImageData();
+```
+
+### FlushReason
+
+渲染器开始新 draw call 的原因:
+
+| 原因 | 说明 |
+|------|------|
+| `BatchFull` | 顶点缓冲区已满 |
+| `TextureSlotsFull` | 所有纹理槽位已被占用 |
+| `ScissorChange` | 裁剪区域变化(UIMask) |
+| `StencilChange` | 模板测试状态变化 |
+| `MaterialChange` | 材质/着色器不同 |
+| `BlendModeChange` | 混合模式变化 |
+| `StageEnd` | 渲染阶段边界 |
+| `TypeChange` | 渲染类型切换(sprite → text) |
+| `FrameEnd` | 帧末尾刷新 |
+
+### RenderType
+
+| 类型 | 说明 |
+|------|------|
+| `Sprite` | 精灵渲染 |
+| `Text` | 位图文本 |
+| `Spine` | Spine 骨骼 |
+| `Particle` | 粒子发射器 |
+| `Shape` | 形状渲染器 |
+| `UIElement` | UI 元素 |
+| `Mesh` | 自定义网格 |
+
## WASM 调试
引擎核心以 WebAssembly 运行。WASM 调试需要引擎的 debug 构建。
diff --git a/docs/astro/src/content/docs/zh/guides/plugins.mdx b/docs/astro/src/content/docs/zh/guides/plugins.mdx
index c4ed51c22..b9599300e 100644
--- a/docs/astro/src/content/docs/zh/guides/plugins.mdx
+++ b/docs/astro/src/content/docs/zh/guides/plugins.mdx
@@ -18,6 +18,7 @@ import { Aside } from '@astrojs/starlight/components';
| 资源加载 | `AssetServer`,用于在运行时加载纹理、Spine 数据、预制体等资源 |
| 预制体 | `Prefabs`,用于实例化预制体 |
| 输入 | `Input`,包含键盘、鼠标和触摸输入——每帧末尾清除 |
+| 时间轴 | `TimelinePlayer` 组件用于播放时间轴动画,`TimelineControl` 运行时控制 API |
### UI 插件
diff --git a/docs/astro/src/content/docs/zh/guides/spine.mdx b/docs/astro/src/content/docs/zh/guides/spine.mdx
index c6931b845..a5116a81a 100644
--- a/docs/astro/src/content/docs/zh/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh/guides/spine.mdx
@@ -138,6 +138,40 @@ addSystem(defineSystem(
));
```
+## 多版本架构
+
+ESEngine 同时支持 Spine **3.8**、**4.1** 和 **4.2** 版本。引擎会自动从骨骼数据中检测 Spine 版本并选择对应的运行时后端。
+
+```typescript
+import type { SpineVersion } from 'esengine';
+// SpineVersion = '3.8' | '4.1' | '4.2'
+```
+
+### 工作原理
+
+- 加载 Spine 资源时,引擎从骨骼文件头中检测版本
+- 自动选择匹配的后端:C++ native(优先)或 WASM fallback
+- 无需修改代码——同一个 `SpineAnimation` 组件适用于所有版本
+
+### SpineManager 运行时 API
+
+对于高级用例,`SpineManager` 提供运行时查询能力:
+
+```typescript
+import { SpineManager } from 'esengine';
+
+// 从原始数据检测版本(加载前)
+const version = SpineManager.detectVersion(skelBinaryData);
+const versionJson = SpineManager.detectVersionJson(skelJsonString);
+
+// 查询已加载实体
+const manager = app.getResource(SpineManager);
+const ver = manager.getEntityVersion(entity); // '3.8' | '4.1' | '4.2'
+const anims = manager.getAnimations(entity); // ['idle', 'run', 'jump']
+const skins = manager.getSkins(entity); // ['default', 'warrior']
+const bounds = manager.getBounds(entity); // { x, y, width, height }
+```
+
## 多纹理批处理
使用多个图集页的 Spine 骨骼会被渲染器自动批处理。无需额外配置 — C++ 后端透明地处理多纹理情况,即使是复杂的多图集角色也能保持较低的 draw call。
diff --git a/docs/astro/src/content/docs/zh/guides/timeline.mdx b/docs/astro/src/content/docs/zh/guides/timeline.mdx
new file mode 100644
index 000000000..879ba30a8
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/timeline.mdx
@@ -0,0 +1,141 @@
+---
+title: 时间轴
+description: ESEngine 中的时间轴动画系统
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**时间轴**系统驱动多轨道动画,可以在时间线上协调属性变化、Spine 播放、精灵动画、音频事件和实体激活。时间轴在编辑器的 Timeline 面板中创建,运行时通过 `TimelinePlayer` 组件和 `TimelineControl` API 播放。
+
+<Aside type="note">
+ 时间轴插件默认包含,无需手动设置。
+</Aside>
+
+## 编辑器工作流
+
+1. 在 Hierarchy 中选择一个实体
+2. 打开 **Timeline** 面板
+3. 点击 **+** 添加轨道(Property、Spine、Sprite Animation、Audio、Activation)
+4. 在时间轴标尺上点击添加关键帧
+5. 时间轴保存为 `.estl` 资源文件
+
+### 轨道类型
+
+| 类型 | 说明 |
+|------|------|
+| Property | 通过关键帧插值动画化任意数值组件属性(位置、缩放、颜色等) |
+| Spine | 在 SpineAnimation 组件上触发 Spine 动画片段 |
+| Sprite Animation | 播放精灵动画片段 |
+| Audio | 在特定时间触发音频事件 |
+| Activation | 在时间范围内启用/禁用实体 |
+
+## TimelinePlayer 组件
+
+将 `TimelinePlayer` 添加到实体上即可在运行时播放时间轴资源。可在编辑器 Inspector 中配置或通过代码设置。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `timeline` | string | `''` | `.estl` 时间轴资源路径 |
+| `playing` | boolean | `false` | 是否正在播放 |
+| `speed` | number | `1.0` | 播放速度倍率 |
+| `wrapMode` | string | `'once'` | `'once'`、`'loop'` 或 `'pingPong'` |
+
+### WrapMode
+
+| 值 | 说明 |
+|----|------|
+| `once` | 播放一次后停止 |
+| `loop` | 播放完毕后从头开始 |
+| `pingPong` | 正向和反向交替播放 |
+
+## TimelineControl API
+
+在系统中使用 `TimelineControl` 控制时间轴播放:
+
+```typescript
+import { defineSystem, addSystem, Query, TimelinePlayer, TimelineControl } from 'esengine';
+import { Res, Input } from 'esengine';
+
+addSystem(defineSystem(
+ [Res(Input), Query(TimelinePlayer)],
+ (input, query) => {
+ for (const [entity] of query) {
+ if (input.isKeyPressed('Space')) {
+ TimelineControl.play(entity);
+ }
+ if (input.isKeyPressed('KeyP')) {
+ TimelineControl.pause(entity);
+ }
+ }
+ }
+));
+```
+
+### 方法
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `TimelineControl.play(entity)` | void | 开始或恢复播放 |
+| `TimelineControl.pause(entity)` | void | 暂停播放 |
+| `TimelineControl.stop(entity)` | void | 停止并重置到开头 |
+| `TimelineControl.setTime(entity, time)` | void | 跳转到指定时间(秒) |
+| `TimelineControl.isPlaying(entity)` | boolean | 检查是否正在播放 |
+| `TimelineControl.getCurrentTime(entity)` | number | 获取当前播放时间(秒) |
+
+## 注册时间轴资源
+
+在编辑器外加载时间轴(如自定义资源管线中)时,使用注册 API:
+
+```typescript
+import { registerTimelineAsset, getTimelineAsset, parseTimelineAsset } from 'esengine';
+
+// 解析原始时间轴数据
+const asset = parseTimelineAsset(jsonData);
+
+// 注册供运行时查找
+registerTimelineAsset('timelines/intro.estl', asset);
+
+// 之后获取
+const tl = getTimelineAsset('timelines/intro.estl');
+```
+
+## 示例:开场序列
+
+```typescript
+import {
+ defineSystem, addStartupSystem, addSystem,
+ Query, Mut, TimelinePlayer, TimelineControl, Res, Input
+} from 'esengine';
+
+// 启动时播放开场时间轴
+addStartupSystem(defineSystem(
+ [Query(Mut(TimelinePlayer))],
+ (query) => {
+ for (const [entity, player] of query) {
+ if (player.timeline === 'timelines/intro.estl') {
+ TimelineControl.play(entity);
+ }
+ }
+ }
+));
+
+// 按任意键跳过
+addSystem(defineSystem(
+ [Res(Input), Query(TimelinePlayer)],
+ (input, query) => {
+ if (input.isKeyPressed('Space')) {
+ for (const [entity, player] of query) {
+ if (TimelineControl.isPlaying(entity)) {
+ TimelineControl.stop(entity);
+ }
+ }
+ }
+ }
+));
+```
+
+## 下一步
+
+- [Tween 动画](/microes/zh/guides/tween/) — 代码驱动的属性动画
+- [Spine 动画](/microes/zh/guides/spine/) — 骨骼动画
+- [精灵动画](/microes/zh/guides/sprite-animation/) — 逐帧精灵动画
diff --git a/docs/astro/src/content/docs/zh/guides/ui-builder.mdx b/docs/astro/src/content/docs/zh/guides/ui-builder.mdx
new file mode 100644
index 000000000..9e5e29fb2
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/ui-builder.mdx
@@ -0,0 +1,265 @@
+---
+title: UI 构建器
+description: ESEngine 中的声明式 UI 构建 API
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`UI` 构建器提供代码优先的方式创建 UI 层级。无需手动创建实体和插入组件,使用工厂方法自动完成所有连接。
+
+<Aside type="tip">
+ UI 构建器用于**运行时代码创建 UI**。可视化编辑器设计 UI 请参见 [UI 布局](/microes/zh/guides/ui/)。
+</Aside>
+
+## 工厂方法
+
+每个方法创建一个完整配置的 UI 实体并返回其 `Entity` ID:
+
+```typescript
+import { UI } from 'esengine';
+
+const btn = UI.button(world, { text: 'Play', parent: rootEntity });
+const slider = UI.slider(world, { value: 0.5, parent: rootEntity });
+const label = UI.label(world, { text: 'Score: 0', parent: rootEntity });
+```
+
+### 可用工厂
+
+| 方法 | 说明 |
+|------|------|
+| `UI.label(world, options)` | 文本标签 |
+| `UI.panel(world, options)` | 带背景色的容器 |
+| `UI.button(world, options)` | 可点击按钮 |
+| `UI.slider(world, options)` | 带填充和手柄的值滑块 |
+| `UI.toggle(world, options)` | 复选框/开关 |
+| `UI.progressBar(world, options)` | 非交互式进度条 |
+| `UI.textInput(world, options)` | 可编辑文本框 |
+| `UI.dropdown(world, options)` | 下拉选择器 |
+| `UI.scrollView(world, options)` | 可滚动容器 |
+| `UI.flexRow(world, options)` | 水平 Flex 布局容器 |
+| `UI.flexColumn(world, options)` | 垂直 Flex 布局容器 |
+
+## 控件选项
+
+所有选项除特别标注外均为可选,默认值来自当前主题。
+
+<Aside type="caution">
+ 事件回调(`onClick`、`onChange`、`onSubmit`)需要传入 `events`(UIEventQueue)实例才能生效。不传则回调被静默忽略。
+</Aside>
+
+### ButtonOptions
+
+```typescript
+UI.button(world, {
+ text: 'Click Me', // 默认: 'Button'
+ fontSize: 16, // 默认: theme.fontSize.md
+ size: { x: 150, y: 40 }, // 默认: { x: 120, y: 36 }
+ color: { r: 0.2, g: 0.5, b: 0.9, a: 1 },
+ textColor: { r: 1, g: 1, b: 1, a: 1 },
+ transition: null, // ColorTransition 或 null
+ parent: rootEntity,
+ events: uiEvents, // onClick/onHover 需要此参数
+ onClick: (entity) => console.log('Clicked!'),
+});
+```
+
+### SliderOptions
+
+```typescript
+UI.slider(world, {
+ value: 0.5,
+ minValue: 0,
+ maxValue: 1,
+ wholeNumbers: false,
+ size: { x: 200, y: 16 },
+ trackColor: { r: 0.15, g: 0.15, b: 0.15, a: 1 },
+ fillColor: { r: 0.25, g: 0.56, b: 0.96, a: 1 },
+ handleSize: { x: 24, y: 24 },
+ handleColor: { r: 1, g: 1, b: 1, a: 1 },
+ parent: rootEntity,
+ events: uiEvents, // onChange 需要此参数
+ onChange: (value, entity) => console.log('Value:', value),
+});
+```
+
+### ToggleOptions
+
+```typescript
+UI.toggle(world, {
+ isOn: true,
+ size: { x: 24, y: 24 },
+ onColor: { r: 0.2, g: 0.6, b: 1, a: 1 },
+ offColor: { r: 0.4, g: 0.4, b: 0.4, a: 1 },
+ label: 'Enable sound', // 可选文本标签
+ group: toggleGroupEntity, // 用于单选按钮行为
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (isOn, entity) => console.log('Toggle:', isOn),
+});
+```
+
+### TextInputOptions
+
+```typescript
+UI.textInput(world, {
+ placeholder: 'Enter name...',
+ value: '',
+ size: { x: 200, y: 36 },
+ fontSize: 16,
+ maxLength: 0, // 0 = 无限
+ multiline: false,
+ password: false,
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (value, entity) => console.log('Text:', value),
+ onSubmit: (value, entity) => console.log('Submit:', value),
+});
+```
+
+### DropdownOptions
+
+```typescript
+UI.dropdown(world, {
+ options: ['Easy', 'Normal', 'Hard'], // 必填
+ selectedIndex: 1,
+ size: { x: 160, y: 32 },
+ parent: rootEntity,
+ events: uiEvents,
+ onChange: (index, entity) => console.log('Selected:', index),
+});
+```
+
+### FlexOptions
+
+```typescript
+UI.flexRow(world, {
+ gap: 8,
+ padding: { left: 12, top: 12, right: 12, bottom: 12 },
+ wrap: false,
+ justifyContent: 'center',
+ alignItems: 'stretch',
+ parent: rootEntity,
+});
+```
+
+## 声明式树构建
+
+对于复杂 UI,使用 `UI.build()` 从嵌套定义创建整个层级:
+
+```typescript
+import { UI } from 'esengine';
+
+let nameInput: Entity;
+
+const form = UI.build(world, {
+ type: 'panel',
+ options: { size: { x: 400, y: 300 } },
+ children: [
+ {
+ type: 'label',
+ options: { text: 'Player Setup', fontSize: 20 },
+ },
+ {
+ type: 'textInput',
+ options: { placeholder: 'Enter name' },
+ ref: (entity) => { nameInput = entity; },
+ },
+ {
+ type: 'flexRow',
+ options: { gap: 8 },
+ children: [
+ {
+ type: 'button',
+ options: { text: 'Cancel' },
+ },
+ {
+ type: 'button',
+ options: { text: 'Start', onClick: () => startGame() },
+ },
+ ],
+ },
+ ],
+});
+```
+
+### 节点类型
+
+| 类型 | 子节点 | 说明 |
+|------|--------|------|
+| `element` | 是 | 原始 UI 实体,手动配置组件 |
+| `label` | 否 | 文本标签 |
+| `button` | 否 | 按钮控件 |
+| `slider` | 否 | 滑块控件 |
+| `toggle` | 否 | 开关控件 |
+| `textInput` | 否 | 文本输入 |
+| `dropdown` | 否 | 下拉选择 |
+| `progressBar` | 否 | 进度条 |
+| `panel` | 是 | 带背景的容器 |
+| `flexRow` | 是 | 水平 Flex 容器 |
+| `flexColumn` | 是 | 垂直 Flex 容器 |
+| `scrollView` | 是 | 可滚动容器(子节点自动挂载到 content 实体) |
+
+### 实体引用
+
+使用 `ref` 捕获创建的实体:
+
+```typescript
+let sliderRef: Entity;
+
+UI.build(world, {
+ type: 'slider',
+ options: { value: 0.5 },
+ ref: (entity) => { sliderRef = entity; },
+});
+```
+
+## 主题
+
+所有控件使用当前 `UITheme` 的默认颜色、尺寸和字体。内置 `DARK_THEME` 为默认主题。
+
+### 自定义主题
+
+在初始化前插入 `UIThemeRes` 覆盖主题:
+
+```typescript
+import { UIThemeRes, DARK_THEME } from 'esengine';
+
+const myTheme = {
+ ...DARK_THEME,
+ primary: { r: 0.9, g: 0.3, b: 0.1, a: 1 },
+ button: {
+ ...DARK_THEME.button,
+ color: { r: 0.9, g: 0.3, b: 0.1, a: 1 },
+ },
+};
+
+cmds.insertResource(UIThemeRes, myTheme);
+```
+
+### UITheme 属性
+
+| 分组 | 属性 |
+|------|------|
+| 颜色 | `primary`, `secondary`, `background`, `surface`, `error`, `text`, `textSecondary`, `border` |
+| 排版 | `fontFamily`, `fontSize`(`xs`, `sm`, `md`, `lg`, `xl`) |
+| 间距 | `spacing`(`xs`, `sm`, `md`, `lg`, `xl`) |
+| 按钮 | `height`, `color`, `textColor`, `transition` |
+| 滑块 | `trackHeight`, `trackColor`, `fillColor`, `handleSize`, `handleColor` |
+| 开关 | `size`, `onColor`, `offColor`, `checkColor` |
+| 输入框 | `height`, `backgroundColor`, `textColor`, `placeholderColor`, `fontSize`, `padding` |
+| 下拉框 | `height`, `backgroundColor`, `itemHeight` |
+| 面板 | `backgroundColor`, `padding` |
+
+## 清理
+
+移除 UI 实体及其所有子实体:
+
+```typescript
+UI.destroy(world, formEntity);
+```
+
+## 下一步
+
+- [UI 布局](/microes/zh/guides/ui/) — 基于锚点的 UIRect 布局
+- [UI 控件](/microes/zh/guides/ui-widgets/) — 组件级控件参考
+- [UI 交互](/microes/zh/guides/ui-interaction/) — 事件和回调
diff --git a/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx b/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
index 005b6750d..576e27d2f 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
@@ -90,6 +90,52 @@ if (events.hasEvent(buttonEntity, 'click')) {
const all = events.drain();
```
+### 回调订阅
+
+除了每帧轮询事件,还可以使用 `.on()` 通过回调方式订阅事件。适合在启动系统中进行一次性设置:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, GetWorld } from 'esengine';
+import { UIEvents, makeInteractable } from 'esengine';
+
+addStartupSystem(defineSystem(
+ [Res(UIEvents), GetWorld()],
+ (events, world) => {
+ const button = findEntityByName(world, 'StartButton');
+
+ // 实体级:仅当该实体触发事件时回调
+ const unsub = events.on(button, 'click', (e) => {
+ console.log('开始按钮被点击!');
+ });
+
+ // 全局:任何实体触发该类型事件时回调
+ events.on('change', (e) => {
+ console.log('值变更:', e.entity);
+ });
+
+ // 调用 unsub() 移除监听器
+ }
+));
+```
+
+| 重载形式 | 说明 |
+|----------|------|
+| `events.on(entity, type, handler)` | 订阅特定实体的事件,返回 `Unsubscribe` 函数 |
+| `events.on(type, handler)` | 全局订阅某类型的所有事件,返回 `Unsubscribe` 函数 |
+
+### makeInteractable
+
+确保实体拥有 `Interactable` 组件的工具函数,使用合理的默认值:
+
+```typescript
+import { makeInteractable } from 'esengine';
+
+makeInteractable(world, entity);
+// 等价于添加 Interactable { enabled: true, blockRaycast: true, raycastTarget: true }
+```
+
+在代码中创建交互实体时使用此函数,避免手动导入和插入 `Interactable` 组件。
+
### 事件冒泡
`press`、`release` 和 `click` 事件沿实体层级向上冒泡。如果父级的 `Interactable` 设置了 `blockRaycast: true`,冒泡在此停止。`hover_enter` 和 `hover_exit` **不会**冒泡。
diff --git a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
index 5a7c1e769..2f52d4ab3 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
@@ -281,6 +281,23 @@ addSystem(defineSystem(
| `scrollY` | number | `0` | 滚动位置 |
| `overscan` | number | `2` | 视口上下额外渲染的项目数 |
+### 自定义项目渲染器
+
+使用 `setListViewRenderer()` 定义每个列表项的填充方式。回调接收项目索引和要配置的实体:
+
+```typescript
+import { setListViewRenderer, Text, Sprite } from 'esengine';
+
+setListViewRenderer(listEntity, (index, itemEntity) => {
+ world.set(itemEntity, Text, { content: `Item ${index}`, fontSize: 16 });
+});
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `index` | number | 列表项的 0 基索引 |
+| `entity` | Entity | 该列表项的实体——用组件填充它 |
+
## TextInput
可编辑文本输入框,支持光标、选择和占位符。