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 asset build transforms section and update WeChat troubleshooting

esengine16952e03f2e1
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index b0c8c9121..aaf8388c8 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -70,6 +70,8 @@ export default defineConfig({
{ label: 'Overview', translations: { 'zh-CN': '概览' }, slug: 'guides/rendering' },
{ label: 'Canvas & Resolution', translations: { 'zh-CN': 'Canvas 与分辨率' }, slug: 'guides/canvas' },
{ label: 'Sprite', translations: { 'zh-CN': '精灵' }, slug: 'guides/sprite' },
+ { 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: 'Bitmap Text', translations: { 'zh-CN': '位图文本' }, slug: 'guides/bitmap-text' },
{ label: 'Custom Draw', translations: { 'zh-CN': '自定义绘制' }, slug: 'guides/custom-draw' },
@@ -91,10 +93,12 @@ export default defineConfig({
{ label: 'Masking & SafeArea', translations: { 'zh-CN': '遮罩与安全区' }, slug: 'guides/ui-masking' },
],
},
+ { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Asset Loading', translations: { 'zh-CN': '资源加载' }, slug: 'guides/assets' },
{ label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'guides/materials' },
{ label: 'Geometry & Meshes', translations: { 'zh-CN': '几何体与网格' }, slug: 'guides/geometry' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
+ { label: 'Profiler', translations: { 'zh-CN': '性能分析' }, slug: 'guides/profiler' },
{ label: 'Editor Extensions', translations: { 'zh-CN': '编辑器扩展' }, slug: 'guides/editor-extensions' },
{ label: 'Plugins', translations: { 'zh-CN': '插件系统' }, slug: 'guides/plugins' },
{ label: 'Building', translations: { 'zh-CN': '构建' }, slug: 'guides/building' },
@@ -112,6 +116,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.7.0', slug: 'changelog-v070' },
{ label: 'v0.6.2', slug: 'changelog-v062' },
{ label: 'v0.6.1', slug: 'changelog-v061' },
{ label: 'v0.6.0', slug: 'changelog-v060' },
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
new file mode 100644
index 000000000..99086d302
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/audio.mdx
@@ -0,0 +1,139 @@
+---
+title: Audio
+description: Audio playback in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ESEngine provides a complete audio system with ECS components, bus-based mixing, and spatial audio. The `AudioPlugin` is included by the engine by default.
+
+## Components
+
+### AudioSource
+
+Attach to any entity to play audio. Requires a `Transform` component for spatial audio.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `clip` | string | `''` | Audio file path |
+| `bus` | string | `'sfx'` | Audio bus: `sfx`, `music`, `ui`, `voice` |
+| `volume` | number | `1.0` | Volume (0–1) |
+| `pitch` | number | `1.0` | Playback rate (0.1–3) |
+| `loop` | boolean | `false` | Loop playback |
+| `playOnAwake` | boolean | `false` | Auto-play when entity loads |
+| `spatial` | boolean | `false` | Enable spatial audio |
+| `minDistance` | number | `100` | Spatial reference distance |
+| `maxDistance` | number | `1000` | Spatial max distance |
+| `attenuationModel` | number | `0` | 0 = Linear, 1 = Inverse, 2 = Exponential |
+| `rolloff` | number | `1.0` | Spatial rolloff factor (0–5) |
+| `priority` | number | `0` | Playback priority |
+| `enabled` | boolean | `true` | Component active |
+
+### AudioListener
+
+Add to the camera or player entity to receive spatial audio. Only one listener should be active at a time.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `true` | Listener active |
+
+## Quick Playback API
+
+For simple one-shot sounds that don't need an entity, use the static `Audio` class:
+
+```typescript
+import { Audio } from 'esengine';
+
+// Play a sound effect
+const handle = Audio.playSFX('assets/explosion.mp3', {
+ volume: 0.8,
+ pitch: 1.2,
+});
+
+// Control playback
+handle.pause();
+handle.resume();
+handle.stop();
+
+// Play background music with fade-in
+Audio.playBGM('assets/theme.mp3', { volume: 0.5, fadeIn: 2.0 });
+
+// Stop BGM with fade-out
+Audio.stopBGM(1.0);
+```
+
+## Volume Control
+
+Control volume per bus:
+
+```typescript
+import { Audio } from 'esengine';
+
+Audio.setMasterVolume(0.8);
+Audio.setMusicVolume(0.5);
+Audio.setSFXVolume(1.0);
+Audio.setUIVolume(0.7);
+
+// Mute a specific bus
+Audio.muteBus('music', true);
+```
+
+## Preloading
+
+Preload audio files to avoid latency on first play:
+
+```typescript
+import { Audio } from 'esengine';
+
+await Audio.preload('assets/explosion.mp3');
+await Audio.preloadAll([
+ 'assets/jump.mp3',
+ 'assets/coin.mp3',
+ 'assets/bgm.mp3',
+]);
+```
+
+## Entity-Based Playback
+
+Add `AudioSource` to an entity in the editor or via code:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, AudioSource } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(AudioSource))],
+ (query) => {
+ for (const [entity, audio] of query) {
+ // Change clip at runtime
+ audio.clip = 'assets/new-sound.mp3';
+ audio.volume = 0.5;
+ }
+ }
+));
+```
+
+## Spatial Audio
+
+Enable spatial audio by setting `spatial: true` on `AudioSource` and adding an `AudioListener` to the camera entity.
+
+```typescript
+import { AudioSource, AudioListener, AttenuationModel } from 'esengine';
+```
+
+The system automatically calculates distance-based attenuation and stereo panning based on the `Transform` positions of the source and listener entities.
+
+**Attenuation models:**
+- **Linear** (0) — volume decreases linearly between `minDistance` and `maxDistance`
+- **Inverse** (1) — realistic falloff based on inverse distance
+- **Exponential** (2) — steep falloff using exponential curve
+
+## Editor Integration
+
+- **Inspector** — audio files show an inline preview player with play/pause controls
+- **Drag-to-scene** — drag an audio file from the asset browser onto the scene to create an entity with `AudioSource`
+- **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
+
+<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/building.mdx b/docs/astro/src/content/docs/guides/building.mdx
index d2e02cc18..b44ac424a 100644
--- a/docs/astro/src/content/docs/guides/building.mdx
+++ b/docs/astro/src/content/docs/guides/building.mdx
@@ -127,7 +127,31 @@ Referenced images are packed into texture atlas pages (max 2048x2048 by default)
User scripts from the `src/` directory are compiled and bundled with esbuild. The `esengine` SDK is treated as an external module -- on Playable it is inlined, on WeChat it is loaded from `sdk.js`.
-### 5. Platform Emission
+### 5. Asset Build Transforms
+
+Before writing assets, the pipeline applies **build transforms** to JSON-based assets that contain references needing rewriting. For example, prefabs and animation clips contain texture paths that must be remapped to atlas coordinates.
+
+Transforms are registered on the `AssetTypeEntry` via `registerAssetBuildTransform()`. The built-in transforms are:
+
+| Asset Type | Transform |
+|------------|-----------|
+| `prefab` | Resolves UUID refs to build paths, rewrites atlas-packed texture refs with `uvOffset`/`uvScale` |
+| `anim-clip` | Rewrites frame texture paths to atlas pages, adds `atlasFrame` metadata for UV calculation |
+
+Both platform emitters call `entry.buildTransform(content, artifact)` generically -- no per-type branching. To add a custom asset type that needs build-time rewriting, register a transform in your editor plugin:
+
+```typescript
+import { registerAssetBuildTransform } from 'esengine';
+
+registerAssetBuildTransform('my-custom-type', (content, context) => {
+ const artifact = context; // BuildArtifact
+ const data = JSON.parse(content);
+ // ... rewrite asset references ...
+ return JSON.stringify(data);
+});
+```
+
+### 6. Platform Emission
The final output is produced for the target platform:
diff --git a/docs/astro/src/content/docs/guides/input.mdx b/docs/astro/src/content/docs/guides/input.mdx
index 5f1eeb4ff..996274e34 100644
--- a/docs/astro/src/content/docs/guides/input.mdx
+++ b/docs/astro/src/content/docs/guides/input.mdx
@@ -5,7 +5,7 @@ description: Keyboard, mouse, and touch input in ESEngine
import { Aside } from '@astrojs/starlight/components';
-ESEngine provides input handling through the `Input` resource. The `InputPlugin` is automatically registered by `createWebApp()`, binding DOM keyboard, mouse, touch, and scroll events.
+ESEngine provides input handling through the `Input` resource. The `InputPlugin` is registered by the engine automatically, binding DOM keyboard, mouse, touch, and scroll events.
## Using Input in Systems
diff --git a/docs/astro/src/content/docs/guides/plugins.mdx b/docs/astro/src/content/docs/guides/plugins.mdx
index 0735bffde..8ffcd3287 100644
--- a/docs/astro/src/content/docs/guides/plugins.mdx
+++ b/docs/astro/src/content/docs/guides/plugins.mdx
@@ -198,17 +198,14 @@ const analyticsPlugin: Plugin = {
};
```
-### SDK Entry Points
+### Registering Custom Plugins
-For users building standalone applications without the editor, ESEngine provides two entry points:
-
-- **`esengine`** -- full SDK with all UI plugins included
-- **`esengine/core`** -- base SDK without UI plugins, for smaller bundles when UI is not needed
+Register custom plugins in your script's `setup` function:
```typescript
-import { createWebApp } from 'esengine/core';
+import { type App } from 'esengine';
-const app = createWebApp(module, {
- plugins: [textPlugin, uiLayoutPlugin],
-});
+export function setup(app: App) {
+ app.addPlugin(myPlugin);
+}
```
diff --git a/docs/astro/src/content/docs/guides/prefabs.mdx b/docs/astro/src/content/docs/guides/prefabs.mdx
index 5af099f03..7fa2223db 100644
--- a/docs/astro/src/content/docs/guides/prefabs.mdx
+++ b/docs/astro/src/content/docs/guides/prefabs.mdx
@@ -42,7 +42,7 @@ Access these via right-click → **Prefab** on a prefab root entity.
Use the `Prefabs` resource to load and instantiate prefabs inside a system. It handles asset loading and entity creation in a single call.
<Aside type="note">
- The `Prefabs` resource is automatically available when using `createWebApp()` — the `PrefabsPlugin` is included by default.
+ The `Prefabs` resource is automatically available — the `PrefabsPlugin` is included by default.
</Aside>
```typescript
diff --git a/docs/astro/src/content/docs/guides/profiler.mdx b/docs/astro/src/content/docs/guides/profiler.mdx
new file mode 100644
index 000000000..bcf01638d
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/profiler.mdx
@@ -0,0 +1,111 @@
+---
+title: Profiler
+description: Real-time performance monitoring in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The `StatsPlugin` provides real-time performance monitoring with an on-screen overlay showing FPS, frame time, rendering stats, and per-system timings.
+
+## Enabling the Profiler
+
+Add `StatsPlugin` in your script's `setup` function:
+
+```typescript
+import { StatsPlugin } from 'esengine';
+
+export function setup(app) {
+ app.addPlugin(new StatsPlugin());
+}
+```
+
+<Aside type="note">
+Unlike `AudioPlugin` and `AnimationPlugin`, `StatsPlugin` is **not** included by default. You must add it explicitly in a user script.
+</Aside>
+
+## Configuration
+
+```typescript
+new StatsPlugin({
+ overlay: true, // Show on-screen panel (default: true)
+ position: 'top-left', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+ container: document.body, // DOM parent for the overlay
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `overlay` | boolean | `true` | Show the on-screen stats panel |
+| `position` | string | `'top-left'` | Overlay position on screen |
+| `container` | HTMLElement | `document.body` | DOM parent for the overlay element |
+
+## Metrics
+
+The overlay displays:
+
+**Performance**
+- **FPS** — frames per second, smoothed over a 60-frame window
+- **Frame time** — average milliseconds per frame
+
+**Rendering**
+- **Draw calls** — number of draw calls per frame
+- **Triangles** — total triangle count
+- **Sprites / Text / Spine / Meshes** — rendered count per type
+- **Culled** — entities skipped by frustum culling
+
+**World**
+- **Entities** — total entity count
+
+**Systems**
+- Top 5 slowest systems with execution time in milliseconds
+
+## Reading Stats in Code
+
+Access the `Stats` resource in your systems:
+
+```typescript
+import { defineSystem, addSystem, Res, Stats } from 'esengine';
+
+addSystem(defineSystem(
+ [Res(Stats)],
+ (stats) => {
+ console.log(`FPS: ${stats.fps}`);
+ console.log(`Draw calls: ${stats.drawCalls}`);
+ console.log(`Entities: ${stats.entityCount}`);
+ }
+));
+```
+
+## Frame History
+
+The profiler maintains a 300-frame rolling buffer for trend analysis:
+
+```typescript
+import { FrameHistory } from 'esengine';
+
+const history = app.getResource(FrameHistory);
+
+// Get all recorded frames
+const frames = history.getAll();
+
+// Get the most recent frame snapshot
+const latest = history.getLatest();
+if (latest) {
+ console.log(`Frame time: ${latest.frameTimeMs}ms`);
+ for (const [system, ms] of latest.systemTimings) {
+ console.log(` ${system}: ${ms.toFixed(2)}ms`);
+ }
+}
+```
+
+## Editor Integration
+
+The profiler panel is accessible from the editor toolbar. It provides:
+
+- Pause/resume stats collection
+- Per-frame inspection — step through individual frames to analyze spikes
+- System timing breakdown per frame
+
+<Aside type="tip">
+Use the profiler to identify performance bottlenecks. If a system consistently shows high execution time, consider optimizing its queries or reducing the work done per frame.
+</Aside>
diff --git a/docs/astro/src/content/docs/guides/scenes.mdx b/docs/astro/src/content/docs/guides/scenes.mdx
index dd59a351a..4f61c7af2 100644
--- a/docs/astro/src/content/docs/guides/scenes.mdx
+++ b/docs/astro/src/content/docs/guides/scenes.mdx
@@ -134,40 +134,46 @@ Entities have a `visible` property (default `true`). When set to `false` in the
## Scene Manager
-The SDK provides the `SceneManager` resource and `sceneManagerPlugin` for managing the loading, switching, and lifecycle of multiple scenes. When using `createWebApp()`, the plugin is included automatically -- no manual registration needed.
+The SDK provides the `SceneManager` resource and `sceneManagerPlugin` for managing the loading, switching, and lifecycle of multiple scenes. The plugin is included by the engine automatically — no manual registration needed.
```typescript
-import { SceneManager } from 'esengine';
+import { Res, SceneManager, defineSystem, addSystem } from 'esengine';
-const mgr = app.getResource(SceneManager);
+addSystem(defineSystem(
+ [Res(SceneManager)],
+ (mgr) => {
+ // access scene manager in a system
+ }
+));
```
## Registering Scenes
-Before the app starts, register each scene with a name, a path to its JSON file, and optional per-scene systems and lifecycle hooks:
+Scenes are managed in the editor — create `.scene` files and configure them in the project settings. For advanced use cases, you can register scenes programmatically in a `setup` function:
```typescript
-import { createWebApp, SceneManager, Schedule, type SceneConfig } from 'esengine';
-
-const app = createWebApp(module);
-
-app.registerScene({
- name: 'menu',
- path: '/scenes/menu.json',
- systems: [
- { schedule: Schedule.Update, system: menuUpdateSystem },
- ],
- setup: (ctx) => {
- ctx.registerDrawCallback('menu-particles', drawParticles);
- },
- cleanup: (ctx) => {
- // called before scene unload
- },
-});
-
-app.registerScene({ name: 'game', path: '/scenes/game.json' });
-app.setInitialScene('menu');
-app.run();
+import { SceneManager, Schedule, type App } from 'esengine';
+
+export function setup(app: App) {
+ const mgr = app.getResource(SceneManager);
+
+ mgr.register({
+ name: 'menu',
+ path: '/scenes/menu.json',
+ systems: [
+ { schedule: Schedule.Update, system: menuUpdateSystem },
+ ],
+ setup: (ctx) => {
+ ctx.registerDrawCallback('menu-particles', drawParticles);
+ },
+ cleanup: (ctx) => {
+ // called before scene unload
+ },
+ });
+
+ mgr.register({ name: 'game', path: '/scenes/game.json' });
+ mgr.setInitial('menu');
+}
```
Instead of specifying a file path with `path`, you can pass scene data directly via `data`. This is useful for procedurally generated or in-memory scenes:
diff --git a/docs/astro/src/content/docs/guides/sprite-animation.mdx b/docs/astro/src/content/docs/guides/sprite-animation.mdx
new file mode 100644
index 000000000..822b3fd23
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/sprite-animation.mdx
@@ -0,0 +1,109 @@
+---
+title: Sprite Animation
+description: Frame-based sprite animation in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The sprite animation system plays frame-based animations by cycling through a sequence of textures. The `AnimationPlugin` is included by the engine by default.
+
+## SpriteAnimator Component
+
+Add `SpriteAnimator` to an entity with `Transform` and `Sprite` to animate it.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `clip` | string | `''` | Animation clip name (registered or `.esanim` asset) |
+| `speed` | number | `1.0` | Animation speed multiplier |
+| `playing` | boolean | `true` | Is animation playing |
+| `loop` | boolean | `true` | Loop when finished |
+| `enabled` | boolean | `true` | Component active |
+
+## Animation Clip Format
+
+Animation clips are defined as `.esanim` files — a JSON format listing texture frames and playback settings:
+
+```json
+{
+ "version": "1.0",
+ "type": "animation-clip",
+ "fps": 12,
+ "loop": true,
+ "frames": [
+ { "texture": "assets/walk_01.png" },
+ { "texture": "assets/walk_02.png" },
+ { "texture": "assets/walk_03.png" },
+ { "texture": "assets/walk_04.png" }
+ ]
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `fps` | number | `12` | Frames per second |
+| `loop` | boolean | `true` | Loop playback |
+| `frames` | array | — | List of texture references |
+
+## Editor Workflow
+
+1. **Create a clip** — right-click in the asset browser → Create → Animation Clip (`.esanim`)
+2. **Edit frames** — open the clip in the visual editor to add/remove/reorder texture frames and set FPS
+3. **Assign to entity** — add a `SpriteAnimator` component and select the clip in the inspector
+4. **Preview** — the animation plays in the Scene View and Game View
+
+## Runtime API
+
+### Playing Animations
+
+Set the `clip` property to switch animations:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, SpriteAnimator } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(SpriteAnimator))],
+ (query) => {
+ for (const [entity, animator] of query) {
+ animator.clip = 'walk';
+ animator.speed = 1.5;
+ animator.playing = true;
+ }
+ }
+));
+```
+
+### Registering Clips in Code
+
+For procedurally generated animations, register clips at runtime:
+
+```typescript
+import { registerAnimClip, getAnimClip } from 'esengine';
+
+registerAnimClip({
+ name: 'explosion',
+ fps: 24,
+ loop: false,
+ frames: [
+ { texture: tex1Handle },
+ { texture: tex2Handle },
+ { texture: tex3Handle },
+ ],
+});
+```
+
+### Stopping and Resetting
+
+```typescript
+// Pause
+animator.playing = false;
+
+// Resume
+animator.playing = true;
+
+// Switch clip (resets to frame 0)
+animator.clip = 'idle';
+```
+
+<Aside type="tip">
+The `SpriteAnimator` system automatically updates the entity's `Sprite` texture each frame. You don't need to manually set the texture — just control the animator.
+</Aside>
diff --git a/docs/astro/src/content/docs/guides/ui-masking.mdx b/docs/astro/src/content/docs/guides/ui-masking.mdx
index b2f120c38..513781c33 100644
--- a/docs/astro/src/content/docs/guides/ui-masking.mdx
+++ b/docs/astro/src/content/docs/guides/ui-masking.mdx
@@ -156,16 +156,7 @@ world.insert(navBar, SafeArea, {
### Plugin Registration
-Both `uiMaskPlugin` and `safeAreaPlugin` are **automatically registered** when using `createWebApp()`. For manual setup:
-
-```typescript
-import { uiMaskPlugin, safeAreaPlugin } from 'esengine';
-
-const app = App.new()
- .addPlugin(uiMaskPlugin)
- .addPlugin(safeAreaPlugin)
- .run();
-```
+Both `uiMaskPlugin` and `safeAreaPlugin` are **registered by the engine automatically**. No manual setup is needed.
## Next Steps
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdx
index 57559284d..e803d1a2f 100644
--- a/docs/astro/src/content/docs/guides/ui.mdx
+++ b/docs/astro/src/content/docs/guides/ui.mdx
@@ -8,7 +8,7 @@ import { Aside } from '@astrojs/starlight/components';
ESEngine provides a complete UI framework with layout, interaction, text rendering, and a library of ready-made widgets. Layout computation runs in C++/WASM for performance, while all components are configured from TypeScript.
<Aside type="note">
- All UI plugins are registered automatically by `createWebApp()`. No manual setup is needed.
+ All UI plugins are registered by the engine automatically. No manual setup is needed.
</Aside>
## Quick Start
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdx
index 7f40022b2..48b732c73 100644
--- a/docs/astro/src/content/docs/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/guides/wechat.mdx
@@ -132,9 +132,22 @@ This happens when WeChat blocks access to a file with an unrecognized extension.
### "File not found"
-The asset is not included in the build. Ensure it is either:
-- Referenced by a scene or prefab (automatically included)
-- In a folder with export mode set to `always` in the asset export configuration
+The asset is not included in the build. Possible causes:
+
+- **Not referenced**: Ensure the asset is referenced by a scene or prefab (automatically included), or is in a folder with export mode set to `always`.
+- **Packed into atlas but path not rewritten**: If you created a custom JSON asset type that contains texture paths, those textures may have been packed into the texture atlas while the JSON file still references the original path. Register a build transform to rewrite the paths:
+
+```typescript
+import { registerAssetBuildTransform } from 'esengine';
+
+registerAssetBuildTransform('my-type', (content, context) => {
+ const data = JSON.parse(content);
+ // rewrite texture refs to atlas paths using context.atlasResult
+ return JSON.stringify(data);
+});
+```
+
+See [Build Pipeline > Asset Build Transforms](/microes/guides/building/#5-asset-build-transforms) for details.
### WebGL Context Errors
diff --git a/docs/astro/src/content/docs/zh/guides/audio.mdx b/docs/astro/src/content/docs/zh/guides/audio.mdx
new file mode 100644
index 000000000..eef65db37
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/audio.mdx
@@ -0,0 +1,139 @@
+---
+title: 音频
+description: ESEngine 中的音频播放
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ESEngine 提供完整的音频系统,包含 ECS 组件、总线混音和空间音频。`AudioPlugin` 由引擎默认包含。
+
+## 组件
+
+### AudioSource
+
+附加到任意实体上播放音频。空间音频需要 `Transform` 组件。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `clip` | string | `''` | 音频文件路径 |
+| `bus` | string | `'sfx'` | 音频总线:`sfx`、`music`、`ui`、`voice` |
+| `volume` | number | `1.0` | 音量(0–1) |
+| `pitch` | number | `1.0` | 播放速率(0.1–3) |
+| `loop` | boolean | `false` | 循环播放 |
+| `playOnAwake` | boolean | `false` | 实体加载时自动播放 |
+| `spatial` | boolean | `false` | 启用空间音频 |
+| `minDistance` | number | `100` | 空间音频参考距离 |
+| `maxDistance` | number | `1000` | 空间音频最大距离 |
+| `attenuationModel` | number | `0` | 0 = 线性, 1 = 反比, 2 = 指数 |
+| `rolloff` | number | `1.0` | 空间衰减因子(0–5) |
+| `priority` | number | `0` | 播放优先级 |
+| `enabled` | boolean | `true` | 组件激活 |
+
+### AudioListener
+
+添加到摄像机或玩家实体上接收空间音频。同一时间只应有一个激活的监听器。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | boolean | `true` | 监听器激活 |
+
+## 快速播放 API
+
+对于不需要实体的简单音效,使用静态 `Audio` 类:
+
+```typescript
+import { Audio } from 'esengine';
+
+// 播放音效
+const handle = Audio.playSFX('assets/explosion.mp3', {
+ volume: 0.8,
+ pitch: 1.2,
+});
+
+// 控制播放
+handle.pause();
+handle.resume();
+handle.stop();
+
+// 播放背景音乐,带淡入
+Audio.playBGM('assets/theme.mp3', { volume: 0.5, fadeIn: 2.0 });
+
+// 停止背景音乐,带淡出
+Audio.stopBGM(1.0);
+```
+
+## 音量控制
+
+按总线控制音量:
+
+```typescript
+import { Audio } from 'esengine';
+
+Audio.setMasterVolume(0.8);
+Audio.setMusicVolume(0.5);
+Audio.setSFXVolume(1.0);
+Audio.setUIVolume(0.7);
+
+// 静音指定总线
+Audio.muteBus('music', true);
+```
+
+## 预加载
+
+预加载音频文件以避免首次播放延迟:
+
+```typescript
+import { Audio } from 'esengine';
+
+await Audio.preload('assets/explosion.mp3');
+await Audio.preloadAll([
+ 'assets/jump.mp3',
+ 'assets/coin.mp3',
+ 'assets/bgm.mp3',
+]);
+```
+
+## 基于实体的播放
+
+在编辑器中或通过代码为实体添加 `AudioSource`:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, AudioSource } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(AudioSource))],
+ (query) => {
+ for (const [entity, audio] of query) {
+ // 运行时更改音频剪辑
+ audio.clip = 'assets/new-sound.mp3';
+ audio.volume = 0.5;
+ }
+ }
+));
+```
+
+## 空间音频
+
+在 `AudioSource` 上设置 `spatial: true` 并为摄像机实体添加 `AudioListener` 即可启用空间音频。
+
+```typescript
+import { AudioSource, AudioListener, AttenuationModel } from 'esengine';
+```
+
+系统会根据源实体和监听器实体的 `Transform` 位置自动计算基于距离的衰减和立体声声像。
+
+**衰减模型:**
+- **线性** (0) — 音量在 `minDistance` 和 `maxDistance` 之间线性降低
+- **反比** (1) — 基于反比距离的真实衰减
+- **指数** (2) — 使用指数曲线的陡峭衰减
+
+## 编辑器集成
+
+- **检查器** — 音频文件显示内联预览播放器,支持播放/暂停控制
+- **拖拽到场景** — 从资产浏览器拖拽音频文件到场景中,自动创建带 `AudioSource` 的实体
+- **Game View** — Game View 工具栏中有静音切换按钮
+- **Scene View** — Scene View 中跳过音频系统,避免编辑时产生不必要的播放
+
+<Aside type="note">
+`playOnAwake` 会延迟到浏览器的 `AudioContext` 激活后才播放。大多数浏览器要求用户交互后才允许音频播放。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh/guides/building.mdx b/docs/astro/src/content/docs/zh/guides/building.mdx
index 5b1d06177..89be6942a 100644
--- a/docs/astro/src/content/docs/zh/guides/building.mdx
+++ b/docs/astro/src/content/docs/zh/guides/building.mdx
@@ -127,7 +127,31 @@ ESEngine 项目可以从编辑器构建到两个目标平台:**可玩广告**
`src/` 目录下的用户脚本通过 esbuild 编译打包。`esengine` SDK 作为外部模块处理——在可玩广告中内联,在微信小游戏中从 `sdk.js` 加载。
-### 5. 平台输出
+### 5. 资源构建变换
+
+在写入资源之前,构建流水线会对包含需要重写引用的 JSON 资源应用**构建变换**。例如,预制体和动画剪辑包含的纹理路径需要被重映射为图集坐标。
+
+变换通过 `registerAssetBuildTransform()` 注册在 `AssetTypeEntry` 上。内置变换包括:
+
+| 资源类型 | 变换内容 |
+|---------|---------|
+| `prefab` | 将 UUID 引用解析为构建路径,将图集打包的纹理引用重写为 `uvOffset`/`uvScale` |
+| `anim-clip` | 将帧纹理路径重写为图集页,添加 `atlasFrame` 元数据用于 UV 计算 |
+
+两个平台发射器都通过 `entry.buildTransform(content, artifact)` 进行通用调用——无需按类型分支。要为需要构建时重写的自定义资源类型添加变换,请在编辑器插件中注册:
+
+```typescript
+import { registerAssetBuildTransform } from 'esengine';
+
+registerAssetBuildTransform('my-custom-type', (content, context) => {
+ const artifact = context; // BuildArtifact
+ const data = JSON.parse(content);
+ // ... 重写资源引用 ...
+ return JSON.stringify(data);
+});
+```
+
+### 6. 平台输出
为目标平台生成最终产物:
diff --git a/docs/astro/src/content/docs/zh/guides/input.mdx b/docs/astro/src/content/docs/zh/guides/input.mdx
index 61def83db..65959294e 100644
--- a/docs/astro/src/content/docs/zh/guides/input.mdx
+++ b/docs/astro/src/content/docs/zh/guides/input.mdx
@@ -5,7 +5,7 @@ description: ESEngine 中的键盘、鼠标和触摸输入
import { Aside } from '@astrojs/starlight/components';
-ESEngine 通过 `Input` 资源提供输入处理。`InputPlugin` 由 `createWebApp()` 自动注册,绑定 DOM 键盘、鼠标、触摸和滚轮事件。
+ESEngine 通过 `Input` 资源提供输入处理。`InputPlugin` 由引擎自动注册,绑定 DOM 键盘、鼠标、触摸和滚轮事件。
## 在系统中使用输入
diff --git a/docs/astro/src/content/docs/zh/guides/plugins.mdx b/docs/astro/src/content/docs/zh/guides/plugins.mdx
index bf555e8f3..913d1d62a 100644
--- a/docs/astro/src/content/docs/zh/guides/plugins.mdx
+++ b/docs/astro/src/content/docs/zh/guides/plugins.mdx
@@ -198,17 +198,14 @@ const analyticsPlugin: Plugin = {
};
```
-### SDK 入口
+### 注册自定义插件
-对于不使用编辑器的独立应用开发者,ESEngine 提供两种入口:
-
-- **`esengine`** — 完整 SDK,包含所有 UI 插件
-- **`esengine/core`** — 基础 SDK,不含 UI 插件,适用于不需要 UI 时减小包体积
+在脚本的 `setup` 函数中注册自定义插件:
```typescript
-import { createWebApp } from 'esengine/core';
+import { type App } from 'esengine';
-const app = createWebApp(module, {
- plugins: [textPlugin, uiLayoutPlugin],
-});
+export function setup(app: App) {
+ app.addPlugin(myPlugin);
+}
```
diff --git a/docs/astro/src/content/docs/zh/guides/prefabs.mdx b/docs/astro/src/content/docs/zh/guides/prefabs.mdx
index 743729943..adfe7042f 100644
--- a/docs/astro/src/content/docs/zh/guides/prefabs.mdx
+++ b/docs/astro/src/content/docs/zh/guides/prefabs.mdx
@@ -42,7 +42,7 @@ import { Aside } from '@astrojs/starlight/components';
使用 `Prefabs` 资源在系统中加载和实例化预制体,一次调用完成资源加载和实体创建。
<Aside type="note">
- 使用 `createWebApp()` 时 `Prefabs` 资源自动可用 — `PrefabsPlugin` 默认包含在内。
+ `Prefabs` 资源自动可用 — `PrefabsPlugin` 默认包含在内。
</Aside>
```typescript
diff --git a/docs/astro/src/content/docs/zh/guides/profiler.mdx b/docs/astro/src/content/docs/zh/guides/profiler.mdx
new file mode 100644
index 000000000..2f1662552
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/profiler.mdx
@@ -0,0 +1,111 @@
+---
+title: 性能分析
+description: ESEngine 中的实时性能监控
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`StatsPlugin` 提供实时性能监控,通过屏幕叠加面板显示 FPS、帧时间、渲染统计和逐系统计时。
+
+## 启用性能分析
+
+在脚本的 `setup` 函数中添加 `StatsPlugin`:
+
+```typescript
+import { StatsPlugin } from 'esengine';
+
+export function setup(app) {
+ app.addPlugin(new StatsPlugin());
+}
+```
+
+<Aside type="note">
+与 `AudioPlugin` 和 `AnimationPlugin` 不同,`StatsPlugin` **不是**默认包含的。你必须在用户脚本中显式添加。
+</Aside>
+
+## 配置
+
+```typescript
+new StatsPlugin({
+ overlay: true, // 显示屏幕面板(默认:true)
+ position: 'top-left', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+ container: document.body, // 叠加面板的 DOM 父元素
+})
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `overlay` | boolean | `true` | 显示屏幕统计面板 |
+| `position` | string | `'top-left'` | 叠加面板在屏幕上的位置 |
+| `container` | HTMLElement | `document.body` | 叠加面板元素的 DOM 父节点 |
+
+## 指标
+
+叠加面板显示:
+
+**性能**
+- **FPS** — 每秒帧数,60 帧窗口平滑
+- **帧时间** — 每帧平均毫秒数
+
+**渲染**
+- **绘制调用** — 每帧绘制调用次数
+- **三角形** — 总三角形数
+- **精灵 / 文本 / Spine / 网格** — 各类型渲染计数
+- **剔除** — 被视锥剔除跳过的实体数
+
+**世界**
+- **实体** — 总实体数量
+
+**系统**
+- 前 5 个最慢系统及其执行时间(毫秒)
+
+## 在代码中读取统计数据
+
+在系统中访问 `Stats` 资源:
+
+```typescript
+import { defineSystem, addSystem, Res, Stats } from 'esengine';
+
+addSystem(defineSystem(
+ [Res(Stats)],
+ (stats) => {
+ console.log(`FPS: ${stats.fps}`);
+ console.log(`Draw calls: ${stats.drawCalls}`);
+ console.log(`Entities: ${stats.entityCount}`);
+ }
+));
+```
+
+## 帧历史
+
+性能分析器维护一个 300 帧的滚动缓冲区用于趋势分析:
+
+```typescript
+import { FrameHistory } from 'esengine';
+
+const history = app.getResource(FrameHistory);
+
+// 获取所有记录的帧
+const frames = history.getAll();
+
+// 获取最近一帧快照
+const latest = history.getLatest();
+if (latest) {
+ console.log(`帧时间: ${latest.frameTimeMs}ms`);
+ for (const [system, ms] of latest.systemTimings) {
+ console.log(` ${system}: ${ms.toFixed(2)}ms`);
+ }
+}
+```
+
+## 编辑器集成
+
+性能分析面板可从编辑器工具栏访问,提供:
+
+- 暂停/恢复统计收集
+- 逐帧检查 — 逐步浏览单个帧以分析卡顿
+- 每帧系统计时细分
+
+<Aside type="tip">
+使用性能分析器识别性能瓶颈。如果某个系统持续显示高执行时间,考虑优化其查询或减少每帧的工作量。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh/guides/scenes.mdx b/docs/astro/src/content/docs/zh/guides/scenes.mdx
index 958795bd3..a9ae3bea6 100644
--- a/docs/astro/src/content/docs/zh/guides/scenes.mdx
+++ b/docs/astro/src/content/docs/zh/guides/scenes.mdx
@@ -134,40 +134,46 @@ addSystem(defineSystem(
## 场景管理器
-SDK 提供了 `SceneManager` 资源和 `sceneManagerPlugin` 插件,用于管理多个场景的加载、切换和生命周期。使用 `createWebApp()` 时会自动包含该插件,无需手动注册。
+SDK 提供了 `SceneManager` 资源和 `sceneManagerPlugin` 插件,用于管理多个场景的加载、切换和生命周期。该插件由引擎自动包含,无需手动注册。
```typescript
-import { SceneManager } from 'esengine';
+import { Res, SceneManager, defineSystem, addSystem } from 'esengine';
-const mgr = app.getResource(SceneManager);
+addSystem(defineSystem(
+ [Res(SceneManager)],
+ (mgr) => {
+ // 在系统中访问场景管理器
+ }
+));
```
## 注册场景
-在应用启动前,使用 `app.registerScene()` 注册所有场景。每个场景需要一个唯一名称和场景文件路径,还可以配置专属系统、setup 回调和 cleanup 回调:
+场景在编辑器中管理 — 创建 `.scene` 文件并在项目设置中配置。如需高级用例,可在 `setup` 函数中以编程方式注册场景:
```typescript
-import { SceneManager, type SceneConfig, Schedule } from 'esengine';
-
-const app = createWebApp(module);
-
-app.registerScene({
- name: 'menu',
- path: '/scenes/menu.json',
- systems: [
- { schedule: Schedule.Update, system: menuUpdateSystem },
- ],
- setup: (ctx) => {
- ctx.registerDrawCallback('menu-particles', drawParticles);
- },
- cleanup: (ctx) => {
- // 场景卸载前调用
- },
-});
-
-app.registerScene({ name: 'game', path: '/scenes/game.json' });
-app.setInitialScene('menu');
-app.run();
+import { SceneManager, Schedule, type App } from 'esengine';
+
+export function setup(app: App) {
+ const mgr = app.getResource(SceneManager);
+
+ mgr.register({
+ name: 'menu',
+ path: '/scenes/menu.json',
+ systems: [
+ { schedule: Schedule.Update, system: menuUpdateSystem },
+ ],
+ setup: (ctx) => {
+ ctx.registerDrawCallback('menu-particles', drawParticles);
+ },
+ cleanup: (ctx) => {
+ // 场景卸载前调用
+ },
+ });
+
+ mgr.register({ name: 'game', path: '/scenes/game.json' });
+ mgr.setInitial('menu');
+}
```
除了通过 `path` 指定场景文件路径外,也可以通过 `data` 直接传入场景数据对象,适用于动态生成或内存中的场景:
diff --git a/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx b/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx
new file mode 100644
index 000000000..e8f7f1c5a
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/sprite-animation.mdx
@@ -0,0 +1,109 @@
+---
+title: 精灵动画
+description: ESEngine 中基于帧的精灵动画
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+精灵动画系统通过循环播放一系列纹理来实现基于帧的动画。`AnimationPlugin` 由引擎默认包含。
+
+## SpriteAnimator 组件
+
+为带有 `Transform` 和 `Sprite` 的实体添加 `SpriteAnimator` 即可播放动画。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `clip` | string | `''` | 动画剪辑名称(已注册或 `.esanim` 资产) |
+| `speed` | number | `1.0` | 动画速度倍率 |
+| `playing` | boolean | `true` | 是否正在播放 |
+| `loop` | boolean | `true` | 播放完毕后循环 |
+| `enabled` | boolean | `true` | 组件激活 |
+
+## 动画剪辑格式
+
+动画剪辑定义为 `.esanim` 文件 — 一种列出纹理帧和播放设置的 JSON 格式:
+
+```json
+{
+ "version": "1.0",
+ "type": "animation-clip",
+ "fps": 12,
+ "loop": true,
+ "frames": [
+ { "texture": "assets/walk_01.png" },
+ { "texture": "assets/walk_02.png" },
+ { "texture": "assets/walk_03.png" },
+ { "texture": "assets/walk_04.png" }
+ ]
+}
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fps` | number | `12` | 每秒帧数 |
+| `loop` | boolean | `true` | 循环播放 |
+| `frames` | array | — | 纹理引用列表 |
+
+## 编辑器工作流
+
+1. **创建剪辑** — 在资产浏览器中右键 → 创建 → 动画剪辑(`.esanim`)
+2. **编辑帧** — 在可视化编辑器中打开剪辑,添加/删除/重排纹理帧并设置 FPS
+3. **分配给实体** — 添加 `SpriteAnimator` 组件,在检查器中选择剪辑
+4. **预览** — 动画在 Scene View 和 Game View 中播放
+
+## 运行时 API
+
+### 播放动画
+
+设置 `clip` 属性切换动画:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, SpriteAnimator } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(SpriteAnimator))],
+ (query) => {
+ for (const [entity, animator] of query) {
+ animator.clip = 'walk';
+ animator.speed = 1.5;
+ animator.playing = true;
+ }
+ }
+));
+```
+
+### 代码注册剪辑
+
+对于程序化生成的动画,可在运行时注册剪辑:
+
+```typescript
+import { registerAnimClip, getAnimClip } from 'esengine';
+
+registerAnimClip({
+ name: 'explosion',
+ fps: 24,
+ loop: false,
+ frames: [
+ { texture: tex1Handle },
+ { texture: tex2Handle },
+ { texture: tex3Handle },
+ ],
+});
+```
+
+### 停止和重置
+
+```typescript
+// 暂停
+animator.playing = false;
+
+// 恢复
+animator.playing = true;
+
+// 切换剪辑(重置到第 0 帧)
+animator.clip = 'idle';
+```
+
+<Aside type="tip">
+`SpriteAnimator` 系统每帧自动更新实体的 `Sprite` 纹理。你不需要手动设置纹理 — 只需控制动画器即可。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh/guides/ui-masking.mdx b/docs/astro/src/content/docs/zh/guides/ui-masking.mdx
index 00e0fc68b..4189e490b 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-masking.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-masking.mdx
@@ -156,16 +156,7 @@ world.insert(navBar, SafeArea, {
### 插件注册
-`uiMaskPlugin` 和 `safeAreaPlugin` 在使用 `createWebApp()` 时**自动注册**。手动设置:
-
-```typescript
-import { uiMaskPlugin, safeAreaPlugin } from 'esengine';
-
-const app = App.new()
- .addPlugin(uiMaskPlugin)
- .addPlugin(safeAreaPlugin)
- .run();
-```
+`uiMaskPlugin` 和 `safeAreaPlugin` 由引擎**自动注册**,无需手动设置。
## 下一步
diff --git a/docs/astro/src/content/docs/zh/guides/ui.mdx b/docs/astro/src/content/docs/zh/guides/ui.mdx
index cd6e10671..a08fc3ba5 100644
--- a/docs/astro/src/content/docs/zh/guides/ui.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui.mdx
@@ -8,7 +8,7 @@ import { Aside } from '@astrojs/starlight/components';
ESEngine 提供了完整的 UI 框架,包含布局、交互、文本渲染和一系列预制控件。布局计算在 C++/WASM 中运行以确保性能,所有组件通过 TypeScript 配置。
<Aside type="note">
- 所有 UI 插件由 `createWebApp()` 自动注册,无需手动设置。
+ 所有 UI 插件由引擎自动注册,无需手动设置。
</Aside>
## 快速开始
diff --git a/docs/astro/src/content/docs/zh/guides/wechat.mdx b/docs/astro/src/content/docs/zh/guides/wechat.mdx
index 7d6fd37fc..fe508c1d2 100644
--- a/docs/astro/src/content/docs/zh/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/zh/guides/wechat.mdx
@@ -132,9 +132,22 @@ build/wechat/
### "File not found" 文件未找到
-资源未被包含在构建中。请确保满足以下条件之一:
-- 被场景或预制体引用(会自动包含)
-- 所在文件夹的导出模式在资源导出配置中设为 `always`
+资源未被包含在构建中。可能的原因:
+
+- **未被引用**:确保资源被场景或预制体引用(会自动包含),或者所在文件夹的导出模式设为 `always`。
+- **已打包到图集但路径未重写**:如果你创建了包含纹理路径的自定义 JSON 资源类型,这些纹理可能已被打包到纹理图集中,而 JSON 文件仍引用原始路径。注册一个构建变换来重写路径:
+
+```typescript
+import { registerAssetBuildTransform } from 'esengine';
+
+registerAssetBuildTransform('my-type', (content, context) => {
+ const data = JSON.parse(content);
+ // 使用 context.atlasResult 将纹理引用重写为图集路径
+ return JSON.stringify(data);
+});
+```
+
+详见[构建流水线 > 资源构建变换](/microes/zh/guides/building/#5-资源构建变换)。
### WebGL 上下文错误