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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: add asset build transforms section and update WeChat troubleshooting
esengine16952e03f2e1
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxindex 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 EmissionThe 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.mdxindex 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 ESEngineimport { 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 Systemsdiff --git a/docs/astro/src/content/docs/guides/plugins.mdx b/docs/astro/src/content/docs/guides/plugins.mdxindex 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.mdxindex 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>```typescriptdiff --git a/docs/astro/src/content/docs/guides/profiler.mdx b/docs/astro/src/content/docs/guides/profiler.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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.mdxindex 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 Stepsdiff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdxindex 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 Startdiff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdxindex 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 Errorsdiff --git a/docs/astro/src/content/docs/zh/guides/audio.mdx b/docs/astro/src/content/docs/zh/guides/audio.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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>```typescriptdiff --git a/docs/astro/src/content/docs/zh/guides/profiler.mdx b/docs/astro/src/content/docs/zh/guides/profiler.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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.mdxindex 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 上下文错误