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: correct what the guides said the engine lacks or does differently (HLOD and streaming, lights, rivers, spatial audio, particles, animator layers, plugins, packaging targets and more), add pictures of the Package target pages, the play and New menus, the Settings window, the Plugins panel and the animator, script graph and sound event editors, and document TextureAtlas
yhha331ec2e2287
diff --git a/README.md b/README.mdindex 9e71fedc6..aa97a7700 100644--- a/README.md+++ b/README.md@@ -52,7 +52,7 @@ Estella is a **2D and 3D game engine** — sprites, tilemaps and UI as much as l| **TypeScript SDK** | Type-safe API: `defineSystem`, `defineComponent`, `Query`, `Commands` || **Cross-Platform** | One project → web, desktop, WeChat MiniGames, playable ads, and native Android / iOS || **Native mobile** | A real arm64 app rendering through an embedded Dawn (Metal / Vulkan) — not a WebView |-| **AI agents** | The editor is an MCP server with 65 tools, and ships a built-in agent that drives the same ones |+| **AI agents** | The editor is an MCP server with 130+ tools, and ships a built-in agent that drives the same ones |## Getting Starteddiff --git a/desktop b/desktopindex 0f6a50397..efd1df332 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 0f6a503977d18c76b4175305539e296cc042b3c6+Subproject commit efd1df332540665fe3dc68052d9d98bdb9a44288diff --git a/docs/astro/src/assets/guides/en/animator-layers.png b/docs/astro/src/assets/guides/en/animator-layers.pngnew file mode 100644index 000000000..cfc545d6aBinary files /dev/null and b/docs/astro/src/assets/guides/en/animator-layers.png differdiff --git a/docs/astro/src/assets/guides/en/build-android.png b/docs/astro/src/assets/guides/en/build-android.pngnew file mode 100644index 000000000..90c8eb698Binary files /dev/null and b/docs/astro/src/assets/guides/en/build-android.png differdiff --git a/docs/astro/src/assets/guides/en/build-playable.png b/docs/astro/src/assets/guides/en/build-playable.pngnew file mode 100644index 000000000..008843bc0Binary files /dev/null and b/docs/astro/src/assets/guides/en/build-playable.png differdiff --git a/docs/astro/src/assets/guides/en/build-wechat.png b/docs/astro/src/assets/guides/en/build-wechat.pngnew file mode 100644index 000000000..9dc6dbde5Binary files /dev/null and b/docs/astro/src/assets/guides/en/build-wechat.png differdiff --git a/docs/astro/src/assets/guides/en/content-new-menu.png b/docs/astro/src/assets/guides/en/content-new-menu.pngnew file mode 100644index 000000000..4c18819adBinary files /dev/null and b/docs/astro/src/assets/guides/en/content-new-menu.png differdiff --git a/docs/astro/src/assets/guides/en/play-mode-menu.png b/docs/astro/src/assets/guides/en/play-mode-menu.pngnew file mode 100644index 000000000..d60c5f67cBinary files /dev/null and b/docs/astro/src/assets/guides/en/play-mode-menu.png differdiff --git a/docs/astro/src/assets/guides/en/plugins-panel.png b/docs/astro/src/assets/guides/en/plugins-panel.pngnew file mode 100644index 000000000..c40a70928Binary files /dev/null and b/docs/astro/src/assets/guides/en/plugins-panel.png differdiff --git a/docs/astro/src/assets/guides/en/script-graph.png b/docs/astro/src/assets/guides/en/script-graph.pngnew file mode 100644index 000000000..4db606865Binary files /dev/null and b/docs/astro/src/assets/guides/en/script-graph.png differdiff --git a/docs/astro/src/assets/guides/en/settings-window.png b/docs/astro/src/assets/guides/en/settings-window.pngnew file mode 100644index 000000000..58a64ce80Binary files /dev/null and b/docs/astro/src/assets/guides/en/settings-window.png differdiff --git a/docs/astro/src/assets/guides/en/sound-event.png b/docs/astro/src/assets/guides/en/sound-event.pngnew file mode 100644index 000000000..a25c1e60bBinary files /dev/null and b/docs/astro/src/assets/guides/en/sound-event.png differdiff --git a/docs/astro/src/assets/guides/en/texture-atlas.png b/docs/astro/src/assets/guides/en/texture-atlas.pngnew file mode 100644index 000000000..867b1a0d9Binary files /dev/null and b/docs/astro/src/assets/guides/en/texture-atlas.png differdiff --git a/docs/astro/src/assets/guides/zh/animator-layers.png b/docs/astro/src/assets/guides/zh/animator-layers.pngnew file mode 100644index 000000000..e331b4f33Binary files /dev/null and b/docs/astro/src/assets/guides/zh/animator-layers.png differdiff --git a/docs/astro/src/assets/guides/zh/build-android.png b/docs/astro/src/assets/guides/zh/build-android.pngnew file mode 100644index 000000000..d54855e88Binary files /dev/null and b/docs/astro/src/assets/guides/zh/build-android.png differdiff --git a/docs/astro/src/assets/guides/zh/build-playable.png b/docs/astro/src/assets/guides/zh/build-playable.pngnew file mode 100644index 000000000..3667fe0baBinary files /dev/null and b/docs/astro/src/assets/guides/zh/build-playable.png differdiff --git a/docs/astro/src/assets/guides/zh/build-wechat.png b/docs/astro/src/assets/guides/zh/build-wechat.pngnew file mode 100644index 000000000..878f3e08eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/build-wechat.png differdiff --git a/docs/astro/src/assets/guides/zh/content-new-menu.png b/docs/astro/src/assets/guides/zh/content-new-menu.pngnew file mode 100644index 000000000..3429076e8Binary files /dev/null and b/docs/astro/src/assets/guides/zh/content-new-menu.png differdiff --git a/docs/astro/src/assets/guides/zh/play-mode-menu.png b/docs/astro/src/assets/guides/zh/play-mode-menu.pngnew file mode 100644index 000000000..c04197799Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-mode-menu.png differdiff --git a/docs/astro/src/assets/guides/zh/plugins-panel.png b/docs/astro/src/assets/guides/zh/plugins-panel.pngnew file mode 100644index 000000000..2a575682eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/plugins-panel.png differdiff --git a/docs/astro/src/assets/guides/zh/script-graph.png b/docs/astro/src/assets/guides/zh/script-graph.pngnew file mode 100644index 000000000..3bd8b5293Binary files /dev/null and b/docs/astro/src/assets/guides/zh/script-graph.png differdiff --git a/docs/astro/src/assets/guides/zh/settings-window.png b/docs/astro/src/assets/guides/zh/settings-window.pngnew file mode 100644index 000000000..1f92df435Binary files /dev/null and b/docs/astro/src/assets/guides/zh/settings-window.png differdiff --git a/docs/astro/src/assets/guides/zh/sound-event.png b/docs/astro/src/assets/guides/zh/sound-event.pngnew file mode 100644index 000000000..559b8fc5eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/sound-event.png differdiff --git a/docs/astro/src/assets/guides/zh/texture-atlas.png b/docs/astro/src/assets/guides/zh/texture-atlas.pngnew file mode 100644index 000000000..867b1a0d9Binary files /dev/null and b/docs/astro/src/assets/guides/zh/texture-atlas.png differdiff --git a/docs/astro/src/content/docs/agents/built-in.mdx b/docs/astro/src/content/docs/agents/built-in.mdxindex 06365f5f9..769d3dc3b 100644--- a/docs/astro/src/content/docs/agents/built-in.mdx+++ b/docs/astro/src/content/docs/agents/built-in.mdx@@ -102,14 +102,15 @@ long run is visible and interruptible with the drawer closed.## What it may do without asking-The tiers are drawn where **Undo stops working**, which is what makes them worth+The tiers are drawn where **going back stops working**, which is what makes them worthknowing:| Tier | Examples | What happens || --- | --- | --- || Read | `get_scene_tree`, `get_inspector`, `capture_viewport` | Runs. Never asks. || Undoable | create, delete, `set_field`, re-parent, paint tiles | Runs. The whole turn is bracketed by one checkpoint, so a single **Undo** takes all of it back. |-| Irreversible | writing a file, exporting a build, saving, `run_editor_command` | **Always asks first.** Undo cannot rescue you afterwards. |+| Project files | `write_project_file`, `save_scene`, creating a script, scene or asset | Runs. The editor keeps each file's before-image, so the turn's **Revert** in History takes the files back with the scene. |+| Irreversible | creating a new project, exporting a build, `run_editor_command`, probing the running game | **Always asks first.** Nothing can take it back afterwards. |So the approval you give is not per edit — it is the Undo button, and it applies tothe turn as a whole. When a run finishes having changed something, the transcriptdiff --git a/docs/astro/src/content/docs/agents/mcp.mdx b/docs/astro/src/content/docs/agents/mcp.mdxindex a0d7d4d03..84fbfa5ab 100644--- a/docs/astro/src/content/docs/agents/mcp.mdx+++ b/docs/astro/src/content/docs/agents/mcp.mdx@@ -10,7 +10,7 @@ tool — Claude Code, Cursor, or your own agent — can drive the real editor: ocreate projects, open scenes, spawn entities from the same Create-menu catalog youuse, edit component fields, verify the result in the live engine World, enter playmode, take screenshots to *see* what it built, and export the finished game — the-exact pipelines the UI uses, sixty-five tools in all.+exact pipelines the UI uses, more than a hundred tools in all.<Aside type="tip">Everything an agent does goes through the editor's own command surface — creates@@ -128,11 +128,11 @@ reconnects automatically rather than stranding the agent.| Prefabs | `create_prefab_from_entity`, `edit_prefab` / `exit_prefab_mode` (Prefab Mode), `apply_prefab`, `revert_prefab`, `unpack_prefab`, `create_prefab_variant` || Behaviour without code | `get_event_bindings` / `set_event_bindings` (wire a button), `add_component` / `remove_component` || Game code | `read_project_file`, `write_project_file`, `list_project_files` |-| Run & ship | `toggle_play` + `get_play_state`, `export_game` (web / desktop / wechat / playable) |+| Run & ship | `set_play` (playing / paused / stopped) + `get_play_state`, `step`, `play_input`, `export_game` (any target in the Package Project list: web, desktop, wechat, playable, android, …) |A typical agent loop: `open_project` → `open_scene` → `list_entity_templates` →`apply_scene_ops` → `get_diagnostics` → `screenshot` to check its work →-`save_scene` → `toggle_play` → `screenshot` again → `export_game`.+`save_scene` → `set_play` → `screenshot` again → `export_game`.### Editing a prefabdiff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex 0c273617d..861bd91fc 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -425,7 +425,8 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `Animator` field | Type | Default | Description ||---|---|---|---|| `controller` | string | `''` | An `.esanimator` asset ref (what the editor writes) or a name passed to `registerController` in code. |-| `currentState` | string | `''` | Active state, as a `/`-separated path for nested machines (seeded from the controller's initial state). |+| `avatar` | string | `''` | An `.esavatar` asset saying how this rig spells the joints the clips name (see [Avatars](#layers-masks-and-ik)). |+| `currentState` | string | `''` | The base layer's active state, as a `/`-separated path for nested machines (seeded from the controller's initial state). || `enabled` | boolean | `true` | Disable to freeze the state machine. || `AnimatorController` method | Description |@@ -436,8 +437,12 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `resetTrigger(entity, name)` | Clear a trigger before it's consumed. || `getFloat(entity, name)` / `getBool(entity, name)` | Read a parameter back. |-The controller can drive both sprite **and** [Spine](/docs/animation/spine/)-animations, so one state machine handles a whole character.+A state's motion can be a sprite clip, a [Spine](/docs/animation/spine/) animation, or+a [timeline](/docs/animation/timeline/) clip (which is how a skinned 3D rig is animated),+so one state machine handles a whole character. A transition can also carry a+`duration` (seconds) to crossfade from the state being left into the one being entered;+it is honoured wherever both motions can be sampled, and a sprite sheet is switched+instead, having nothing to be halfway between.Parameters come in three types (`AnimatorParamType`): `'float'`, `'bool'`, and`'trigger'`. Conditions compare them with `gt` / `lt` / `eq` / `neq` (numeric,@@ -452,10 +457,10 @@ parameter and `eq` / `neq`.*A 1D blend: a float parameter picks the clip whose threshold is the highest one at or below it — here `idle` / `walk` / `run` as `speed` rises, with no transitions between them.*A state can carry a 1D **blend** instead of a single clip: a float parameter-selects between `AnimatorBlendThreshold` stops. Because the sprite channel plays-one clip at a time, this is a *selection* by threshold — the stop with the+selects between `AnimatorBlendThreshold` stops. For sprite clips, which play one at+a time, this is a *selection* by threshold — the stop with thegreatest `value` at or below the parameter wins (below all stops, the first one-plays) — not a weighted pose blend. Each threshold is+plays). Each threshold is`{ value, clip, speed?, loop? }`; per-threshold `speed` / `loop` override thestate's own. The selection re-evaluates every frame, so a rising `speed`parameter walks idle→walk→run with no transitions:@@ -488,11 +493,24 @@ const setup = defineSystem([Res(AnimatorController)], (anim) => {The pure helper `selectBlendClip(blend, value)` returns the threshold a valueselects — handy for tooling or tests.+A blend over motions that can be sampled (timeline clips driving a skeleton or any+component field) does not pick: it **mixes** the stops either side of the parameter,+at a shared phase rather than a shared second, so a 2 s idle and a 0.6 s run keep+their feet together. Write it with a `motion` instead of the single-kind fields:+`{ kind: 'blend1d', parameter, thresholds: [{ value, motion }] }`, where a stop's+motion can itself be another blend. For a locomotion that turns, `blend2d` places its+stops in the plane two parameters span —+`{ kind: 'blend2d', parameterX, parameterY, points: [{ position: { x, y }, motion }] }` —+and mixes the points around the sample (a sample standing on a clip plays that clip+alone; one outside the hull is held by its nearest edge). The state inspector offers+None / Clip / Blend 1D / Blend 2D, so none of this needs a hand-edited file.+For skeletal characters, a state can instead carry a `spine` motion(`AnimatorSpineMotion`, `{ animation, loop? }`): on entry the controller setsthat [Spine](/docs/animation/spine/) animation (`loop` defaults `true`) and leavestrack playback and mixing to the Spine runtime — it never touches`SpriteAnimator`. States are exclusive: exactly one of `clip`, `blend`, `spine`,+`motion` (the general form: any registered kind, `sprite` or `timeline`, or a `blend1d` / `blend2d` over them),or `stateMachine`.### Sub-state machines@@ -566,6 +584,49 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());| `evaluateAnimatorPath(def, path, params, triggers, clipFinished?)` | One pure evaluation step over a path → `{ nextPath, consumedTriggers }`. || `STATE_PATH_SEP` | The path separator, `'/'`. |+### Layers, masks and IK++++*The animator controller of the third-person example. **Layers** (top right) stack on the base layer, each with its own weight and mask; **Parameters** below drive the transitions.*++++One state machine can say a character is running or waving, never both. A controller+can carry **layers** over its base machine: each is a machine of its own, with its own+clock, transitions and active state, and the entity ends up as the whole stack,+written once. Layers compose in order, so swapping two is a different character.++```jsonc+// in the .esanimator, beside "states"+"layers": [{+ "name": "Upper body",+ "weight": 1, // 0 leaves the layers below alone, 1 states this layer whole+ "blend": "override", // or "additive": add what the clip departs from its first frame+ "mask": { "paths": ["Spine"] }, // joints this layer may write, by childPath; each stands for its subtree+ "initialState": "Rest",+ "states": [ /* ... */ ]+}]+```++A `mask` is a set of the same `childPath`s a clip already uses to name what it+animates. No mask writes the whole rig; an empty `paths` list writes nothing. Root+motion belongs to the base layer alone, and a trigger is one event every layer is told+about. The editor's layer rail picks which machine the canvas edits.++A controller's `ik` list reaches for things the clips did not know about:+`two-bone` puts a limb's tip (`tip`, a joint by `childPath`) on a `target`, bending+towards an optional `pole`; `look-at` turns a joint until its own `axis` points at the+target. Each has a `weight`, and a float `parameter` can fade it. IK belongs to the+controller, not to a layer, and runs once on the stack's answer.++**Avatars.** A clip names joints by whatever the exporter called them, so two+characters rigged by two people share no clip. A `.esavatar` (New menu) is the rig's+own translation of those names and records its bind pose; a controller's `avatar` names+the avatar its clips were authored against, and the Animator's `avatar` field takes the rig's own. One controller then drives rigs with different bone names and+different bind poses, and root motion is scaled to the distance each rig would+travel.+### Animation eventsA clip can name the moments inside it. A `customEvent` track in andiff --git a/docs/astro/src/content/docs/animation/spine.mdx b/docs/astro/src/content/docs/animation/spine.mdxindex 856f9da0f..1cdd4222b 100644--- a/docs/astro/src/content/docs/animation/spine.mdx+++ b/docs/astro/src/content/docs/animation/spine.mdx@@ -39,9 +39,10 @@ viewport — including across Play/Stop — and once it loads, the `animation` a`skin` fields become dropdowns of that skeleton's actual animations and skins.<Aside type="note">- The skeleton pick popover lists **`.skel`** files. A **`.json`** skeleton loads- just as well — assign it by **dragging it from the Content Browser** onto the- slot.+ The skeleton slot takes **`.skel`** files and **`.json`** skeletons alike (a `.json`+ has no extension of its own to say so; the editor recognises it by the marker inside+ the file, and it appears in the pick popover beside the `.skel` files). Dragging a+ file from the Content Browser onto the slot works too.</Aside>## Atlasesdiff --git a/docs/astro/src/content/docs/animation/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdxindex 29a1d8119..85c444973 100644--- a/docs/astro/src/content/docs/animation/timeline.mdx+++ b/docs/astro/src/content/docs/animation/timeline.mdx@@ -34,7 +34,7 @@ const attach = defineSystem([Commands()], (cmds) => {| `timeline` | asset | `''` | The timeline asset (`.estimeline`). || `playing` | boolean | `false` | The play flag — raise to play, lower to pause. Raising it on a finished clip replays from the top. || `speed` | number | `1` | Playback rate multiplier. |-| `wrapMode` | string | `'once'` | `'once'`, `'loop'`, or `'pingPong'` (camelCase — other values silently play once). |+| `wrapMode` | string | `''` | Overrides the clip's own wrap mode: `'once'`, `'loop'`, or `'pingPong'` (camelCase). Empty — and any other string, which counts as a typo — leaves the mode the clip declares standing. || `finished` | boolean | `false` | Latched true when a `'once'` clip completes; cleared on the next play. Runtime, read-only. |The component flags **are** the playback control: the engine reconciles them into@@ -220,8 +220,8 @@ the channel's dot-path field on the named component.### Wrap modes-Playback uses the **player component's** `wrapMode` string; the numeric-`WrapMode` constant lives on the asset and in the pure evaluation API. The+A clip declares its own numeric `WrapMode` (on the asset and in the pure evaluation+API); the **player component's** `wrapMode` string, when it names one, overrides it. Themapping and behavior:| `WrapMode` | Player string | Behavior past the end |diff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxindex 95166209d..797be128c 100644--- a/docs/astro/src/content/docs/assets/audio.mdx+++ b/docs/astro/src/content/docs/assets/audio.mdx@@ -8,7 +8,8 @@ import { Aside } from '@astrojs/starlight/components';Estella's audio plays one-shot effects and looping music through the `Audio`resource, controls individual sounds with a handle, balances the mix with a bushierarchy, and positions sounds in the world with spatial audio. It runs on the-Web Audio backend in browsers and the native backend on WeChat.+Web Audio backend in browsers, a player-per-sound backend on WeChat and the other mini-game hosts, and the host's+native audio engine (miniaudio) in the iOS and Android apps.## How it works@@ -123,6 +124,12 @@ and graph triggers.### Authoring sound events+++*A sound event with three variants. Each row has its waveform and weight (the share is weight over the sum), and **Trigger** plays it at the listener with the event's own rules.*+++Choose **New → Create Sound Event** in the Content Browser, or select audio assetsand use **Create Sound Event** in their context menu. Double-click a `.esaudioevent`to open its dedicated editor. Dropping audio into an empty event panel creates an@@ -208,6 +215,8 @@ the audio system starts it automatically.| `volume` | number | `1` | Volume, 0..1. || `pitch` | number | `1` | Playback speed / pitch. || `loop` | boolean | `false` | Loop the clip. |+| `playing` | boolean | `false` | The play flag: raise to play, lower to stop. The engine lowers it when a non-looping clip ends. |+| `finished` | boolean | `false` | Runtime, read-only: the clip completed; raising `playing` plays it again. || `playOnAwake` | boolean | `false` | Start automatically when the entity is enabled. || `spatial` | boolean | `false` | Attenuate by distance from the listener. || `minDistance` | number | `100` | Distance within which volume is full. |@@ -233,7 +242,8 @@ audio.muteBus('music', true);Route a sound to a bus with the `AudioSource.bus` field, or leave `playSFX`defaulting to `sfx`. Volume setters exist for `setMasterVolume` (a global slider)and `setMusicVolume` / `setSFXVolume` / `setUIVolume`. The `voice` bus routes sounds-but has no volume setter — toggle it with `muteBus('voice', …)`.+and has no named setter: set it with `setBusVolume('voice', v)` (which reaches any bus by name) or toggle it with+`muteBus('voice', …)`.### Bus effects & ducking@@ -275,11 +285,19 @@ Settings**: `Compress` and `Bitrate` control the cook's WAV → MP3 transcodepass through untouched. MP3 has a small encoder delay — turn `Compress` off onclips that must loop seamlessly.+**Load Type** decides how the clip is held on the Web: *Auto* streams clips of 30 seconds+or longer from their compressed file and decodes shorter ones, *Decompress On Load* always+decodes (instant to start; a three-minute track costs about 69 MB), and *Streaming* always+streams. A streamed clip takes almost no memory and goes through the same bus, volume and+fades, but gives up a sample-accurate loop point and a second simultaneous voice of the+same clip. The choice ships in the exported game's audio settings, so Play, an export and a+playable ad stream the same clips.+## Under the facade`Audio` is a facade over three exported classes the Web Audio backend assembles —`AudioMixer`, `AudioBus`, and `AudioPool`. You rarely construct them inside a-game (on the WeChat backend they don't exist at all, which is why the bus APIs+game (on the WeChat and native backends they don't exist at all, which is why the bus APIsdegrade to no-ops there), but they're public for two real jobs: **custom busesbeyond the built-in four**, and **standalone audio pipelines** — an auditiontool, a custom `PlatformAudioBackend`, tests — built on your own `AudioContext`.@@ -386,18 +404,19 @@ const setupSpatial = defineSystem([Commands()], (cmds) => {`AudioListener` has a single field, `enabled` (default `true`) — keep exactly oneenabled listener in the scene.-Estella's spatial pipeline is honest 2D: each frame, the audio system takes the-source's and the listener's world positions, computes the distance, and drives-the playing handle with `volume × attenuation` plus an **x-axis stereo pan**-(`(sourceX − listenerX) / maxDistance`, clamped to ±1). There is no HRTF,-doppler, or occlusion. A spatial source playing with no enabled listener warns+Spatial audio is three-dimensional: each frame, the audio system takes the+source's and the listener's world positions, computes the distance in all three+axes, and drives the playing handle with `volume × attenuation` plus a **stereo pan**+along the listener's own right (`dot(source − listener, right) / maxDistance`, clamped+to ±1; an unturned listener's right is world +X, and a listener that turns hears the+world turn with it). There is no HRTF, doppler, or occlusion. A spatial source playing with no enabled listener warnsonce and measures from the world origin.The curve math is exported as pure functions for tools and tests —`calculateAttenuation(distance, config)` with a `SpatialAudioConfig`(`model`, `refDistance`, `maxDistance`, `rolloff` — the system fills it from`AudioSource.minDistance`/`maxDistance`/`rolloff`), and-`calculatePanning(sourceX, sourceY, listenerX, listenerY, maxDistance)`:+`calculatePanning(source, listener, right, maxDistance)` (the first three are `{ x, y, z }`):```typescriptimport { calculateAttenuation, calculatePanning, AttenuationModel } from 'esengine';@@ -405,7 +424,9 @@ import { calculateAttenuation, calculatePanning, AttenuationModel } from 'esengiconst gain = calculateAttenuation(250, {model: AttenuationModel.Inverse, refDistance: 100, maxDistance: 1000, rolloff: 1,}); // 0.4 — refDistance / distance-const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right+const pan = calculatePanning(+ { x: 600, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }, 1000,+); // 0.6 — to the right```### Sound event sourcediff --git a/docs/astro/src/content/docs/assets/localization.mdx b/docs/astro/src/content/docs/assets/localization.mdxindex eef580ccc..b8614d764 100644--- a/docs/astro/src/content/docs/assets/localization.mdx+++ b/docs/astro/src/content/docs/assets/localization.mdx@@ -66,6 +66,7 @@ i18n.t('apples', { count: 3 }); // "3 apples"| `setLocale(locale)` | Set the active locale. || `setFallbackLocale(locale)` | Set the locale used when a key is missing. || `setPluralSelector(locale, selector)` | Custom plural rule for a locale. |+| `setPseudoLocalization(options \| null)` | Opt-in length-stress preview (`expansion`, `accents`); `null` restores ordinary translation. || `availableLocales()` | List registered locales. || `has(key)` | Whether a key exists in the active/fallback locale. |@@ -101,6 +102,17 @@ localization plugin — it fails loud otherwise), preload viaexport cook always ships `.eslocale` files — they load by key, so reachabilitycan't see them and force-includes them instead.+Double-click a `.eslocale` to open the **String Table** editor, which shows every language of+the project side by side: one row per key, one column per table, untranslated cells marked,+a filter, and add and remove for keys (each edit is written to that language's file at once).+It can **Import** an Excel (`.xlsx`), CSV or XLIFF (`.xlf`) file and merge it into the tables by key,+and **Export** every language as one Excel or CSV sheet or as XLIFF 1.2, listing the problems it found+first; a plural entry is edited in the inspector.++To check how a longer language will fit, `i18n.setPseudoLocalization({ expansion: 0.35, accents: true })`+(`@experimental`) stretches and accents every translated string while keeping placeholders, rich-text tags+and newlines intact; `setPseudoLocalization(null)` goes back to the real text.+## Bind UI Text to keysSet `Text.i18nKey` (the **I18n Key** dropdown in the editor's Details panel, listingdiff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdxindex 69852a165..393614fcb 100644--- a/docs/astro/src/content/docs/assets/models.mdx+++ b/docs/astro/src/content/docs/assets/models.mdx@@ -232,6 +232,19 @@ so a track cannot drive the wrong one; that name is what the prefab shows.`LINEAR`, `STEP` and `CUBICSPLINE` all carry across, tangents included.+A `weights` channel (an animation of a model's morph targets) comes too: it becomes a+track per primitive the node draws, with one channel per target, so the clip drives the+`MeshMorph` weights described under [Morph targets](#morph-targets).++## Lights and cameras++A glTF's `KHR_lights_punctual` lights and cameras, and an FBX's point, directional and+spot lights and cameras, become `Light` and `Camera` components on their nodes inside+the prefab, turned to face -Z as the engine's do. Colour, cone angles, reach, field of+view and clip planes carry over; intensity is carried as the file states it, since the+engine's has no photometric unit. An imported camera is never the active one, so a+model cannot take the view away from the scene's own camera.+## SkinningA rigged model comes in rigged: the mesh carries its joint indices, weights and bind pose,@@ -312,18 +325,15 @@ when it runs.| Not imported | Why ||---|---|-| `weights` animation channels | The shapes themselves are imported (see [Morph targets](#morph-targets)); a clip that drives them is not carried yet. |-| A second UV set (`TEXCOORD_1`), `KHR_texture_transform`, an FBX uv transform | UVs are used as authored. |+| A material texture that asks for `TEXCOORD_1`, a `KHR_texture_transform` that offsets, scales or rotates, an FBX uv transform | A material samples the first UV set as authored. (The mesh itself keeps its second UV set, which a lightmap or a material's `v_texCoord1` can read.) || Non-triangle primitives (`mode` ≠ 4) | The renderer draws triangle lists. || `normalTexture.scale` | The map is applied at full strength. || The textures of a shading layer (`clearcoatTexture`, `sheenColorTexture`, `anisotropyTexture`, …), `specularColorFactor`, `attenuationDistance` | Each layer is a constant for the whole material; its factors are kept and the textures are reported. See [Shading layers](/docs/graphics/materials/#shading-layers). |-| Cameras and lights in an FBX | A scene's camera and lighting are the scene's, not the model's. |+| Area and volume lights | Named in the import notes and skipped. (Point, directional and spot lights, and cameras, **are** imported: see [Lights and cameras](#lights-and-cameras).) || Separate FBX metalness/roughness maps, an FBX opacity map | See [FBX](#fbx). |## Limits worth knowing-- Point lights measure distance in the XY plane (the 2D lighting model); **directional- lights are exact**, which is what a shaded model usually wants.- A material that writes its own vertex stage is not redirected onto mesh geometry — itwould ignore the per-object transform. Fragment-only materials work on both.- Geometry with no `NORMAL` attribute still takes light, off the constant normal a 2Ddiff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdxindex 17a2c3d74..958df723c 100644--- a/docs/astro/src/content/docs/assets/overview.mdx+++ b/docs/astro/src/content/docs/assets/overview.mdx@@ -170,7 +170,7 @@ way it can:- **Content-address** — name each shipped file by a hash of its bytes, so URLsare immutable and identical files dedupe to a single copy. On by default forWeb/Desktop.-- **Auto-atlas** — put loose PNGs in a `<name>.atlas/` folder and the cook packs+- **Auto-atlas** — an opt-in cook option (off unless the build asks for it): put loose PNGs in a `<name>.atlas/` folder and the cook packsthem into atlas pages (with the frame UVs written into the manifest), so manysmall sprites ship as one texture and batch in one draw call.diff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdxindex 28a053be4..a3dfd06b1 100644--- a/docs/astro/src/content/docs/assets/textures.mdx+++ b/docs/astro/src/content/docs/assets/textures.mdx@@ -120,10 +120,11 @@ Browser — every sprite that uses the texture inherits them.| **Max Size** | `2048` | Downscale cap applied at cook (a power of two). A source larger than this on its longest side is box-filtered down; a smaller source is untouched. || **Compression** | `Auto` | **GPU compressed** ships a KTX2 (Basis Universal) that stays compressed in video memory — about a quarter of the decoded image — and transcodes per device. **Original image** ships the file as it is: exact, and for flat art far smaller to download, but decoded in full on the GPU. **Auto** is GPU compressed for a texture a mesh draws (directly or through its material) and the original image for sprites and UI. A build does what this row says; it never swaps one for the other because a file came out smaller. || **Compress Format** | `uastc` | `uastc` — high quality, larger. `etc1s` — much smaller, lower quality (good for photographic art). Only used when the texture is GPU compressed. |+| **Mip Maps** | on | Keep a chain of half-size copies so a texture drawn small samples a filtered image instead of shimmering; costs a third more memory. Turn it off for pixel art and UI that is always drawn at its own size. || **Filter** | `linear` | Sampling filter. `nearest` keeps pixel art crisp; `linear` smooths. || **Wrap** | `repeat` | How UVs outside `[0,1]` are addressed: `repeat`, `clamp`, `mirror`. |-| **Premultiply Alpha** | `false` | Multiply RGB by alpha at import. || **sRGB Color** | `true` | The image stores sRGB-encoded color (albedo, UI). Disable for authored-linear data — normal maps, masks. Only meaningful when the project renders in linear color. |+| **Mip Coverage Cutoff** | `0` | For a cutout (leaves, grass, fences): the alpha cutoff its material tests. Each mip level keeps the share of texels above it that the full image has, so the cutout does not thin out with distance. `0` = off; applies to UASTC-compressed textures. || **9-Slice Border** | `0,0,0,0` | Left/right/top/bottom border in **texture pixels**: where the image's corners end. Authored once here, inherited by every `UIVisual` set to Sliced. |<Aside type="tip">diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex ad3cff566..082c37b7b 100644--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx@@ -65,17 +65,21 @@ content stack, in this order:`RenderPipeline`.2. **UI**: `uiPlugins` — the composed UI pipeline (layout, text, text input,masks, render order, interaction, drag, focus, safe area).-3. **Base content**: `timerPlugin`, `lifecyclePlugin`, `animationPlugin`,- `audioPlugin`, `videoPlugin`, `particlePlugin`, `trailPlugin`,- `mesh2dPlugin`, `tilemapPlugin`, `postProcessPlugin`, `timelinePlugin`,- `perceptionPlugin`, `fsmPlugin`, `btPlugin`, `navPlugin`,- `replicationPlugin`.-4. **Spine**: a `SpinePlugin` instance (it pulls its per-version wasm runtime- from `app.sideModules` on demand — nothing loads unless a scene uses Spine).+3. **Base content**: the diagnostics, timer, velocity, lifecycle, animation, audio,+ video, particle, trail, spring-bone, mesh-renderer, static-batch,+ post-processing, event-binding and services plugins.+4. **Optional subsystems, installed by import**: importing a subpath such as+ `esengine/tilemap`, `esengine/timeline`, `esengine/ai` (perception, FSM,+ BT and navigation), `esengine/logic` (script graphs), `esengine/gameplay`,+ `esengine/replication`, `esengine/spine`, `esengine/dragonbones`, or the+ terrain, foliage, water and worldgen subpaths registers that subsystem's plugins,+ and the factory adds whatever has registered. A game that never imports a subpath+ neither installs nor ships its subsystem. Spine pulls its per-version wasm runtime+ from `app.sideModules` on demand — nothing loads unless a scene uses Spine.5. **Your `plugins`**, in the order given.-Physics is **not** in the default set: `Physics2DPlugin` needs the physics wasm-module. The shipped runtime acquires `'physics'` from the side-module host and+Physics is **not** in the default set: `Physics2DPlugin` (and `Physics3DPlugin` for the+3D world) needs its wasm module. The shipped runtime acquires `'physics'` from the side-module host andinstalls the plugin automatically when the project declares physics or thescene contains physics components; when composing manually, construct`Physics2DPlugin` yourself (it and `loadPhysicsModule` are exported from@@ -104,14 +108,14 @@ stop();| `plugins` | `Plugin[]` | Your gameplay plugins, appended after the base set. || `sideModules` | `SideModuleHost` | Optional-native-module acquirer (physics on the server). |-Included: `assetPlugin`, `prefabsPlugin`, `sceneManagerPlugin`, `timerPlugin`,-`lifecyclePlugin`, `audioPlugin` (silent on hosts without a device), and the-gameplay-AI/replication set (`perceptionPlugin`, `fsmPlugin`, `btPlugin`,-`navPlugin`, `replicationPlugin`).+Included: `assetPlugin`, `prefabsPlugin`, `sceneManagerPlugin`, the timer, velocity,+lifecycle, event-binding and services plugins, `audioPlugin` (silent on hosts without a+device), and every optional subsystem the project imported (gameplay AI, script graphs,+replication, …) — the same import-driven set as above.Excluded — everything that exists *to be seen*: `corePlugin` (it wires renderfacades that only exist after `initRenderer()`), UI, particles, tilemap-rendering, post-processing, timeline, Spine, input.+rendering, post-processing, Spine, input.`runHeadless(app, { fps? })` drives the app on a wall-clock `setInterval`(there is no `requestAnimationFrame` on a server), default 60 fps. Delta is@@ -343,8 +347,8 @@ independently.Optional native subsystems ship as **standalone wasm modules** loaded ondemand, so the base engine download stays small: physics (Box2D), the-per-version Spine runtimes, the Basis Universal texture transcoder, and the-software video decoder. Each is an emscripten pair — `<file>.js` glue plus+the Jolt 3D physics world, the per-version Spine runtimes, DragonBones, the Basis+Universal texture transcoder, and the software video decoder. Each is an emscripten pair — `<file>.js` glue plus`<file>.wasm` — acquired uniformly through a `SideModuleHost`; only the*transport* differs per realm.@@ -353,11 +357,13 @@ software video decoder. Each is an emscripten pair — `<file>.js` glue plus| `SideModuleId` | Artifacts | Contents ||---|---|---|| `'physics'` | `physics.js` / `.wasm` | Box2D physics. |-| `'spine:3.8'` / `'spine:4.1'` / `'spine:4.2'` | `spine38` / `spine41` / `spine42` `.js`/`.wasm` | One Spine runtime per skeleton format version. |+| `'physics3d'` | `physics3d.js` / `.wasm` | Jolt 3D physics. |+| `'spine:2.1'` / `'3.8'` / `'4.1'` / `'4.2'` / `'4.3'` | `spine21` … `spine43` `.js`/`.wasm` | One Spine runtime per skeleton format version. |+| `'dragonbones'` | `dragonbones.js` / `.wasm` | The DragonBones runtime (one entry: the format is frozen). || `'basis'` | `basis.js` / `.wasm` | Basis Universal KTX2 transcoder (compressed textures). || `'videodec'` | `videodec.js` / `.wasm` | MPEG-1 software video decoder. |-`SPINE_VERSIONS` is the readonly list `['3.8', '4.1', '4.2']`, and+`SPINE_VERSIONS` is the readonly list `['2.1', '3.8', '4.1', '4.2', '4.3']`, and`spineModuleId(version)` builds the corresponding id.A host answers `acquire(id)` with a promise of the instantiated module (cached@@ -368,17 +374,17 @@ built-in transports:base URL (what `wasmBaseUrl` builds); used by the editor, web, and desktop.- **`createEmbeddedSideModuleHost(...)`** — modules inlined as base64(Playable ads).-- **`createWeChatSideModuleHost(...)`** — WeChat's precompiled module- factories.+- **`createMiniGameSideModuleHost(...)`** (also exported as `createWeChatSideModuleHost`) —+ the mini-game hosts' precompiled module factories.You normally never call `acquire` yourself — set `app.sideModules` (via`wasmBaseUrl` or `sideModules`) and the Spine plugin and physics install pullfrom it when needed.<Aside type="note">- The main `esengine` barrel mirrors exactly the physics/spine **wiring**- layer — `Physics2DPlugin`, `Physics2DEvents`, `Physics`, `loadPhysicsModule`,- `SpinePlugin`, `SpineEvents`, `Spine` — so hosts can register the plugins+ The main `esengine` barrel mirrors the physics/spine **wiring**+ layer — `Physics2DPlugin`, `Physics2DEvents`, `Physics2D`, `loadPhysicsModule`,+ `Physics3DPlugin`, `Physics3D`, `SpinePlugin`, `SpineEvents`, `Spine` — so hosts can register the pluginswithout a subpath import. The full APIs live on the `esengine/physics` and`esengine/spine` subpaths. See [Physics](/docs/gameplay/physics/) and[Spine](/docs/animation/spine/).diff --git a/docs/astro/src/content/docs/core-concepts/components.mdx b/docs/astro/src/content/docs/core-concepts/components.mdxindex bd1c80f19..a0295ca2e 100644--- a/docs/astro/src/content/docs/core-concepts/components.mdx+++ b/docs/astro/src/content/docs/core-concepts/components.mdx@@ -84,7 +84,7 @@ switching it off would stop the wrong thing.## Built-in components-The engine registers 77 components you query alongside your own — `Transform`,+The engine registers more than 150 components you query alongside your own — `Transform`,`Sprite`, `ShapeRenderer`, `Camera`, `Light`, `ParticleEmitter`,`SpineAnimation`, `TilemapLayer`, the UI set, the physics colliders, and more.Each subsystem guide teaches the ones it owns; thediff --git a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdxindex 858597383..209763bc1 100644--- a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx+++ b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx@@ -29,7 +29,7 @@ Every subsystem's imperative API is reached the same way:| Input | `Res(Input)` | [Input](/docs/scripting/input/) || Audio | `Res(Audio)` | [Audio](/docs/assets/audio/) || Assets | `Res(Assets)` | [Assets](/docs/assets/overview/) |-| Tilemaps | `Res(Tilemaps)` | [Tilemaps](/docs/world/tilemaps/) |+| Tilemaps | `Res(Tilemaps)` — from `esengine/tilemap` | [Tilemaps](/docs/world/tilemaps/) || Particles | `Res(Particle)` | [Particles](/docs/world/particles/) || Post-processing | `Res(PostProcess)` | [Post-processing](/docs/graphics/post-processing/) || Scenes | `Res(SceneManager)` | [Scenes](/docs/world/scenes/) |@@ -39,17 +39,19 @@ Every subsystem's imperative API is reached the same way:| Timers | `Res(TimerRes)` | [Scripting](/docs/scripting/overview/) || Timeline | `Res(Timeline)` | [Timeline](/docs/animation/timeline/) || Prefabs | `Res(Prefabs)` | [Prefabs](/docs/world/prefabs/) |-| Navigation / AI | `Res(Nav)` | [Gameplay AI](/docs/gameplay/ai/overview/) |+| Navigation / AI | `Res(Nav)` — from `esengine/ai` | [Gameplay AI](/docs/gameplay/ai/overview/) || Localization | `Res(Localization)` | [Localization](/docs/assets/localization/) || Camera view | `Res(CameraView)` | [Camera](/docs/graphics/camera/) || UI events | `Res(UIEvents)` | [UI](/docs/ui/overview/) |-| Physics | `Res(Physics)` — from `esengine/physics` | [Physics](/docs/gameplay/physics/) |+| 2D physics | `Res(Physics2D)` — from `esengine/physics` | [Physics](/docs/gameplay/physics/) |+| 3D physics | `Res(Physics3D)` — from `esengine/physics3d` | [3D Physics](/docs/gameplay/physics-3d/) || Spine | `Res(Spine)` — from `esengine/spine` | [Spine](/docs/animation/spine/) |-Physics and Spine are **optional side-modules** loaded on demand, so their APIs-live on subpaths to keep the base bundle small; everything else is in the main-`esengine` package. All the base subsystems above ship in the standard app — no-plugin wiring needed.+Physics (2D and 3D) and Spine are **optional side-modules** loaded on demand, and+tilemaps and AI are optional subpath packages, so their APIs live on subpaths to keep+the base bundle small; everything else is in the main `esengine` package. The editor+and the web runtime install the plugins a project uses — no wiring needed; in a bare+`new App()` you add them yourself.Some subsystems also publish **event resources** on the same pattern — aresource whose contents are this frame's events, read the same frame:diff --git a/docs/astro/src/content/docs/core-concepts/transforms.mdx b/docs/astro/src/content/docs/core-concepts/transforms.mdxindex af21b29e1..4eef6ec7d 100644--- a/docs/astro/src/content/docs/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/core-concepts/transforms.mdx@@ -65,7 +65,10 @@ can key them), and `position` / `rotation` / `scale` are replicated by- **World space is Y-up**: `+Y` is up, `+X` is right, angle `0` points along`+X`, and positive angles turn counter-clockwise (`Math.atan2(dy, dx)` givesthe angle toward a target directly).-- **`position.z` is draw-order, not perspective**: 2D rendering orders coarsely+- **`position.z` is draw-order in a 2D scene, a real depth axis in a 3D one**. In a+ 3D scene (meshes, a perspective camera, [3D physics](/docs/gameplay/physics-3d/)) the+ axes stay Y-up and `z` is ordinary space: cameras and lights look down `-Z`, and the+ ground plane is XZ. For 2D sprites, rendering orders coarselyby each renderer's sorting `layer`; within a layer, use `z` for fine ordering(or a [y-sorted layer](/docs/graphics/sprites/#draw-order--sorting-layers) fortop-down depth). It does not foreshorten or scale sprites.diff --git a/docs/astro/src/content/docs/editor/asset-editors.mdx b/docs/astro/src/content/docs/editor/asset-editors.mdxindex e11f05ab7..ec9bd82fe 100644--- a/docs/astro/src/content/docs/editor/asset-editors.mdx+++ b/docs/astro/src/content/docs/editor/asset-editors.mdx@@ -6,8 +6,9 @@ Double-click an asset in the Content Browser to open its editor in a document ta- **Sequencer** — a timeline / curve editor for keyframe animation. See[Timeline](/docs/animation/timeline/).-- **Tilemap mode** — a **Tile Palette** panel beside the Content Browser, with tools in the viewport toolbar for **brush, erase, rectangle, line, bucket, select,- eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**+- **Tilemap mode** — a **Tile Palette** panel beside the Content Browser, with tools in the viewport toolbar for **brush, erase, rectangle, ellipse, line, bucket, select,+ eyedropper**, and **terrain (autotile)**, saved **stamps**, a **Replace tiles…** command (swap one+ tile ID for another across a layer or a selection), plus stamp **flip-H / flip-V / rotate-90°**(`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode** (`D`). Thepalette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps canbe **orthogonal, isometric, staggered, or hexagonal**. Seediff --git a/docs/astro/src/content/docs/editor/content-browser.mdx b/docs/astro/src/content/docs/editor/content-browser.mdxindex 1dd09c9a8..431d86cbe 100644--- a/docs/astro/src/content/docs/editor/content-browser.mdx+++ b/docs/astro/src/content/docs/editor/content-browser.mdx@@ -5,10 +5,21 @@ description: "Your project's asset explorer — creating and importing assets, pThe Content Browser is your project's asset explorer. Its **create** menu makes newassets in place:-- New Scene, New Animation, New Input Map, New Material, New Material Graph,- **New Shader**, New State Machine, New Behavior Tree, **New Script…**, New Folder.-- Context actions per asset type: **Create Tileset** (from a texture), **Create- Tilemap** (from a tileset), **Create Material Instance** (from a material).+- New Scene, New Prefab, **New Script…**, New Animation, New Animation Controller,+ New Input Map, New Locale Table, New Cube Environment (six images), New Material,+ New Material Graph, New Material Subgraph, **New Shader**, New State Machine,+ New Behavior Tree, New Script Graph, New Avatar, Create Sound Event, New World+ Rules, New Terrain Layer, New Folder — plus any asset type a plugin adds.+- Context actions per asset type: **Create Tileset** and **Create Sprite+ Animation** (from a texture), **Create Tilemap** (from a tileset), **Create+ Animated Sprite** (from an animation clip), **Create Material Instance** (from a+ material); a scene also offers **Set as Startup Scene**, and an imported asset+ **Reimport**.++++*The Content Browser **New** menu.*+**New Script…** is the one that writes more than a file: a module nothing imports isnever bundled and its component never reaches Add Component, so the dialog also addsdiff --git a/docs/astro/src/content/docs/editor/history-scatter-health.mdx b/docs/astro/src/content/docs/editor/history-scatter-health.mdxindex 2a90a3f35..29296e2a8 100644--- a/docs/astro/src/content/docs/editor/history-scatter-health.mdx+++ b/docs/astro/src/content/docs/editor/history-scatter-health.mdx@@ -44,7 +44,7 @@ viewport instead of placing each copy by hand. Arm it from the Command Palette (each keeps.3. Drag in the viewport. Each stroke is **one undo step** and reports *Scattered N*.-The **Scatter Around** command fills the spot the selection stands on without a+The **Scatter Around Selection** command fills the spot the selection stands on without astroke — "more of this, here".## Project Healthdiff --git a/docs/astro/src/content/docs/editor/overview.mdx b/docs/astro/src/content/docs/editor/overview.mdxindex 9f3da939b..e25e8eae6 100644--- a/docs/astro/src/content/docs/editor/overview.mdx+++ b/docs/astro/src/content/docs/editor/overview.mdx@@ -16,8 +16,10 @@ When no project is open, the editor shows the **Launcher**:- **Recent** — reopen a project you've worked on, with search and grid/list views.- **New project** — pick a template, give it a name and location, and create it.- Templates come in two groups: **Starters** (the **Blank** template — an empty- scene with a camera) and **Examples** (the bundled sample projects, ready to+ Templates come in two groups: **Starters** (**Blank** — an empty scene with a+ camera — plus ready-to-run beginnings such as a 2D platformer, a top-down+ game, a pixel RPG, a UI game, a 3D starter, an online 3D world, a Playable Ad+ and a WeChat Mini Game) and **Examples** (the bundled sample projects, ready toexplore and edit).A project is a folder on disk. The pieces the editor cares about:@@ -43,7 +45,7 @@ renaming a file doesn't break references.The default layout, from the outside in:- **Activity Bar** — the far-left icon rail: the four **editing modes** (Tilemap / UI / World / Scene), the **Panels** menu (show or hide any docked panel), the Content Drawer, the Agent, and Settings.-- **Menu Bar** — File · Edit · Entity · View · Build · Window · Help. Save is in File; Undo and Redo are in Edit.+- **Menu Bar** — File · Edit · Entity · View · Build · Window · Help, plus a **Tools** menu that appears once a plugin contributes a command to it. Save is in File; Undo and Redo are in Edit.- **Header** — the **Play** controls (Play, Pause, Restart, and the menu that picks where the game runs), **Scan Preview** to run the game on a phone, and **Compile** for your scripts.- **Viewport** (center) — the live WebGL scene view, with its own toolbar: the transform tools, snapping, 2D / 3D, the screen controls, **Show** and **Gizmos**.- **World Outliner** (right) — the scene's entity hierarchy.diff --git a/docs/astro/src/content/docs/editor/play.mdx b/docs/astro/src/content/docs/editor/play.mdxindex 14ea11343..9025ba1fc 100644--- a/docs/astro/src/content/docs/editor/play.mdx+++ b/docs/astro/src/content/docs/editor/play.mdx@@ -10,6 +10,10 @@ The **Play** controls in the toolbar run your game:or **Play In New Window** (a dedicated **Game** tab), and toggles **Maximize Viewport onPlay** — which hands the whole workspace to the running game and restores your layout onStop.+- The same dropdown picks **Single Player** or **2 / 3 / 4 Players (Listen Server)**:+ with more than one, the first realm boots as the listen server and each extra+ player gets a client realm wired to it by in-editor replication, so a networked+ game can be tried without leaving the editor.- A running game reads as a soft accent ring around the viewport (amber, with the framedimmed, when paused) — not a badge over the game.- Shortcuts: **F5** play, **Esc** stop, **F6** pause/resume, **Shift+F5** restart, and@@ -18,6 +22,10 @@ The **Play** controls in the toolbar run your game:Because play uses an isolated realm — the same runtime that ships your game — what yousee in play is what a player gets.+++*The menu beside **Play**.*+## The Outliner while playingThere is one hierarchy, not two. While the game runs the Outliner shows the **runningdiff --git a/docs/astro/src/content/docs/editor/scenes.mdx b/docs/astro/src/content/docs/editor/scenes.mdxindex 4d69d21d0..31434d568 100644--- a/docs/astro/src/content/docs/editor/scenes.mdx+++ b/docs/astro/src/content/docs/editor/scenes.mdx@@ -9,7 +9,9 @@ There are several ways to add an entity:- **Entity → Add Entity** drops a blank Transform entity.- **+ Add → Create entity…** opens a command-palette that spawns entities: the built-ins — **Empty**,**Sprite**, **Camera**, **Particles**, **Light**, **Tilemap**, **Spine**, **Audio**,- **Text**, **Shape**, **Mesh**, **Trail**, and the **UI** widgets (Canvas plus+ **Text**, **Bitmap Text**, **Shape**, **Mesh**, **Trail**, **DragonBones**, **Sound Event**, **Sun**, the+ built-in 3D primitives (cube, sphere and the rest), ready-made **Third Person Character** and+ **Outdoor Environment** setups, and the **UI** widgets (Canvas pluscontrols) — **your own project components**, and any **`.esprefab` prefab** in theproject. Every create path (this menu, drag-and-drop, and the automation surface) runsthe same pipeline, so each spawn is a single undo step.diff --git a/docs/astro/src/content/docs/editor/settings.mdx b/docs/astro/src/content/docs/editor/settings.mdxindex c3b9dfe31..86b102142 100644--- a/docs/astro/src/content/docs/editor/settings.mdx+++ b/docs/astro/src/content/docs/editor/settings.mdx@@ -47,6 +47,10 @@ Settings you set once and then leave alone — screen presets, solver tuning, thcolors, the module switches, the endpoints of your own AI providers — sit under a page's**Advanced** fold, so a page's body is what people actually touch.+++*The Settings window. **Editor** settings are yours and stay on this machine; **Project** settings travel with the project.*+## Runtime**Project → Game → Runtime** holds the engine's own tuning, which used to be reachable onlydiff --git a/docs/astro/src/content/docs/editor/shortcuts.mdx b/docs/astro/src/content/docs/editor/shortcuts.mdxindex 64f8514e1..c9394fa86 100644--- a/docs/astro/src/content/docs/editor/shortcuts.mdx+++ b/docs/astro/src/content/docs/editor/shortcuts.mdx@@ -14,7 +14,7 @@ Settings → Editor → Shortcuts.| Open Project | `mod + O` || Save Scene | `mod + S` || Save Scene As | `mod + shift + S` |-| Undo / Redo | `mod + Z` / `mod + shift + Z` |+| Undo / Redo | `mod + Z` / `mod + shift + Z` (or `mod + Y`) || Duplicate | `mod + D` || Copy / Cut / Paste | `mod + C` / `mod + X` / `mod + V` || Delete | `Delete` / `Backspace` |@@ -30,7 +30,7 @@ Settings → Editor → Shortcuts.| Package Project… | `mod + shift + B` || Go to Anything… | `mod + P` || Command Palette | `mod + shift + P` |-| Content Drawer | `Ctrl + Space` |+| Content Drawer | `mod + Space` || Project Settings | `mod + ,` || Zoom interface in / out / reset | `mod + =` / `mod + -` / `mod + 0` |diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxindex a7f1e63d0..a2b285305 100644--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx@@ -49,7 +49,7 @@ The editor writes a plugin that already runs, and loads it:"id": "acme.level-tools","name": "Level Tools","version": "0.1.0",- "engines": { "editor": "^0.34" },+ "engines": { "editor": "^0.97" },"main": { "editor": "src/editor.ts" }}```@@ -75,7 +75,7 @@ reopens on the new build.<Aside type="tip" title="Let the editor write engines.editor">`engines.editor` is the editor range a plugin claims to work with. Below 1.0 the-**minor is the breaking-change axis** — `^0.34` does not match `0.35`. Creating a+**minor is the breaking-change axis** — `^0.97` does not match `0.98`. Creating aplugin pins it to the editor doing the creating, so copying an older range in fromsomewhere else is how a plugin arrives already marked *incompatible*.</Aside>@@ -112,6 +112,10 @@ inspector sections, asset types, entity templates, menu items — each with its"Why isn't my panel showing up?" is usually answered here: either it isn't in thelist (`activate` never reached that line), or it is, under an id you didn't expect.+++*The Plugins panel: New plugin, Import and Refresh across the top, the plugins on the left, and on the right what the selected one **declares** and **contributes**.*+## Sharing a plugin**Export** in the Plugins panel packs one plugin into a single `.esplugin` file —@@ -525,9 +529,9 @@ Package dialog.## Project native modulesSome runtimes arrive as WASM: a vector-animation player, a solver, anything with-a C++ heritage and an official emscripten build. The engine already loads five of-its own that way — physics, the Basis transcoder, the per-version Spine runtimes-— and a project can add its own on the same terms.+a C++ heritage and an official emscripten build. The engine already loads its own+that way — physics, the Basis transcoder, the DragonBones runtime, the video decoder,+the per-version Spine runtimes — and a project can add its own on the same terms.Fetching one by hand works on the web and nowhere else. A mini-game has no`fetch` and needs the binary *inside* the package; a playable has no files atdiff --git a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/gameplay/ai/advanced.mdxindex f34964c7d..44c79fed1 100644--- a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/advanced.mdx@@ -15,7 +15,7 @@ cells, 4- or 8-connected, with an octile/manhattan heuristic and no cornercutting (a diagonal step needs both shared orthogonal cells open). Drop to itwhen you steer movement yourself, draw a path preview, or compute reachabilityfor turn-based ranges — or when one grid isn't enough, since the `Nav` resource-holds a single grid:+holds one active surface:```typescriptimport { NavGrid, findPath, pathToWorld } from 'esengine/ai';@@ -64,16 +64,17 @@ const grid = navGridFromTiles((x, y) => level.tiles[y][x], {### Perception internals-The perception plugin is a thin wrapper over four exported functions — useful for+The perception plugin is a thin wrapper over exported functions — useful forone-off sight checks from an action, custom senses (memory, hearing, multipletargets), or unit tests against a fake world:-- **`senseTarget(ox, oy, facing, tx, ty, range, halfFov, isBlocked?)`** — the pure- geometry: a range check, a FOV cone check (`halfFov` is *half* the cone in- radians; ≥ π means omnidirectional), then the optional occlusion callback.-- **`quaternionToAngle2D(z, w)`** — 2D facing angle in radians from a `Transform`- rotation quaternion's z/w components.-- **`makeLosCheck(physics)`** — builds the occlusion callback from a physics+- **`senseTarget(observer, facing, target, range, halfFov, isBlocked?)`** — the pure+ geometry, all in 3D (`Vec3` points; a flat scene is the case where `z` is constant): a range+ check, a FOV cone check (`halfFov` is *half* the cone in radians; ≥ π means+ omnidirectional), then the optional occlusion callback.+- **`facingFromRotation(rotation, axis?)`** — the world direction an entity faces, from a+ `Transform` rotation and a `FacingAxis` (`'x'` by default, or `'-z'`).+- **`makeLosCheck(physics)`** — builds the occlusion callback from a 2D physicsraycast: occluded when any hit lands clearly short of the target(`fraction < 0.98` — the last ~2% is the target itself).- **`stepPerception(world, isBlocked?)`** — the exact per-frame step the plugin@@ -81,16 +82,15 @@ targets), or unit tests against a fake world:the nearest visible one, and write the `Perception` component.```typescript-import { quaternionToAngle2D, Transform, registerCondition } from 'esengine';-import { senseTarget } from 'esengine/ai';+import { Transform, registerCondition } from 'esengine';+import { senseTarget, facingFromRotation } from 'esengine/ai';// A one-off sight check against a POINT — no PerceptionTarget needed.registerCondition('seesShrine', (ctx) => {const tf = ctx.get(Transform);- const facing = quaternionToAngle2D(tf.rotation.z, tf.rotation.w);return senseTarget(- tf.position.x, tf.position.y, facing,- SHRINE.x, SHRINE.y,+ tf.position, facingFromRotation(tf.rotation),+ SHRINE, // a { x, y, z } point300, Math.PI / 3, // 300 px range, 120° cone).visible;});@@ -102,16 +102,16 @@ registerCondition('seesShrine', (ctx) => {|---|---|| `visible` | The target is within range, inside the cone, and not occluded. || `distance` | Distance to the target — always set, even when not visible. |-| `dirX` / `dirY` | Unit direction observer → target; `(0, 0)` when not visible. |+| `dir` | Unit direction observer → target as a `Vec3`; zero when not visible. |-The built-in system wires `makeLosCheck` in only when the physics module is-loaded; otherwise sensing is range + FOV only — the AI layer has no hard physics-dependency.+The built-in system wires in a line-of-sight check only when a physics module is+loaded (the 3D solver if the scene has one, otherwise 2D); with neither, sensing+is range + FOV only — the AI layer has no hard physics dependency.## Custom app setup-The perception, FSM, BT, and navigation plugins are part of the default plugin set,-so the **editor and the `esengine` web runtime add them for you**. Only when you build+Importing `esengine/ai` registers the perception, FSM, BT, and navigation plugins, so+the **editor and the `esengine` web runtime add them for you**. Only when you buildan app from a bare `new App()` do you add them explicitly:```typescriptdiff --git a/docs/astro/src/content/docs/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/gameplay/ai/overview.mdxindex bfa1fd800..2b50de86d 100644--- a/docs/astro/src/content/docs/gameplay/ai/overview.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/overview.mdx@@ -34,10 +34,11 @@ in code, then wire them into either an FSM or a BT — graphs authored visuallyeditor, not hardcoded. Perception feeds the decision; the decision drives navigation.<Aside type="note">- Everything here is pure TypeScript in the `esengine` core (no WebAssembly- side-module). All four plugins — perception, FSM, BT, and navigation — are added- automatically by the editor and the web runtime. You only wire plugins yourself in- a bare `new App()` (see [Custom app setup](/docs/gameplay/ai/advanced/#custom-app-setup)).+ Everything here is pure TypeScript in the `esengine/ai` subpath (no WebAssembly+ side-module). All four plugins — perception, FSM, BT, and navigation — are installed+ by importing `esengine/ai`, and the editor and the web runtime add them to the app.+ You only wire plugins yourself in a bare `new App()` (see+ [Custom app setup](/docs/gameplay/ai/advanced/#custom-app-setup)).</Aside>## The shared registry@@ -124,7 +125,7 @@ an FSM hook.### Built-in names-The engine pre-registers a few names, so common glue needs **no code at all** — they+The engine pre-registers a handful of names, so common glue needs **no code at all** — theyappear in the editor palettes next to your own. All of them operate on components ofthe agent entity (the same channel your code and the editor use):@@ -137,6 +138,11 @@ the agent entity (the same channel your code and the editor use):| `spriteAnim.restart` | action | Rewind the flipbook to frame 0 and play (argument switches clip). || `spriteAnim.stop` | action | Pause the flipbook. || `spriteAnim.finished` | condition | True once a one-shot sprite clip has finished. |+| `audio.play` | action | Raise the agent's `AudioSource` play flag; the argument switches to that clip. Already sounding the same clip is a no-op. |+| `audio.stop` | action | Lower the `AudioSource` play flag. |+| `audio.finished` | condition | True once a non-looping clip has ended and is no longer playing. |+| `soundEvent.trigger` / `soundEvent.stop` | action | Start / stop the agent's `SoundEventSource`. |+| `property.set` | action | Write any component field on the agent (or another entity) by `Component.field` path and a value, e.g. `UIVisual.color.a`. |Actions can carry an optional **string argument** — set it next to the actionname in the FSM state inspector (or on a BT action node). Built-ins use it fordiff --git a/docs/astro/src/content/docs/gameplay/ai/perception.mdx b/docs/astro/src/content/docs/gameplay/ai/perception.mdxindex 4d4e2a302..a7ec75541 100644--- a/docs/astro/src/content/docs/gameplay/ai/perception.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/perception.mdx@@ -26,12 +26,18 @@ cmds.spawn()|---|---|---|---|| **`Perceiver`** | `range` | `220` | Sight range in world pixels. || | `fovDegrees` | `360` | Field-of-view cone in degrees (`360` = omnidirectional). |+| | `facingAxis` | `'x'` | Which of the entity's own axes the cone points down: `'x'` is screen-right (a flat scene), `'-z'` is where an imported 3D model faces. |+| | `losLayers` | `0` | 3D only: physics layers the line-of-sight ray may hit (`0` = every layer). || **`Perception`** | `visible` | `false` | A target is currently seen. || | `distance` | `0` | Distance to the seen target. |-| | `targetX`, `targetY` | `0` | Seen target position, world pixels. |-| | `dirX`, `dirY` | `0` | Unit direction from observer to target. |+| | `targetX`, `targetY`, `targetZ` | `0` | Seen target position, world pixels. |+| | `dirX`, `dirY`, `dirZ` | `0` | Unit direction from observer to target. || **`PerceptionTarget`** | *(tag)* | — | Marks an entity as sensable by `Perceiver`s. |-The FOV cone is oriented by the perceiver's `Transform` rotation. `Perception` is a+Sensing is three-dimensional (a flat scene is the case where `z` is constant), so the+cone and the distance work in a 3D scene too. The FOV cone is oriented by the perceiver's+`Transform` rotation along `facingAxis`. When a physics world is present the sight ray is+cast against it, so walls block sight: the 3D solver is used if the scene has one, otherwise+the 2D one; with neither, sensing is range + cone only. `Perception` is atransient, runtime-only component — the plugin rewrites it every frame, so you neverauthor its values.diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdxindex 957fb1345..8e2f3769e 100644--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx@@ -13,6 +13,19 @@ It sits **beside** the [2D physics](/docs/gameplay/physics/), not on top of it.scene keeps the solver, the units and the feel it already has, and a project thatnever asks for a 3D world never loads it.+## Setup++Like the 2D side module, the 3D world loads on its own in the editor and the web+runtime when a scene uses a 3D body. In a custom app, add the plugin yourself; every+option is optional (gravity defaults to `{ x: 0, y: -9.81, z: 0 }`, `fixedTimestep` to+`1/60`, `pixelsPerUnit` to `100`, `maxBodies` to `1024`):++```typescript+import { Physics3DPlugin } from 'esengine/physics3d';++app.addPlugin(new Physics3DPlugin('physics3d.js', { gravity: { x: 0, y: -9.81, z: 0 } }));+```+## BodiesAn entity is in the world when it carries a `RigidBody3D` **and** a shape. A body@@ -32,6 +45,7 @@ cmds.spawn()| `gravityScale` | This body's share of world gravity. `0` is weightlessness, not slow falling. || `linearDamping` / `angularDamping` | How quickly motion bleeds off. || `fixedRotation` | Freezes the orientation the body was given — what keeps a character from toppling. It does not right a body that starts tilted. |+| `layer` | Which of the sixteen [collision layers](#collision-layers) the body is in. || `continuousCollision` | Checks the whole path a step covers rather than where the body ended up. What a bullet needs; off by default, since it costs more. |## Shapes@@ -129,6 +143,10 @@ app.getResource(Physics3DDebugDraw).enabled = true;visible. That is what a debug view is for.</Aside>+A `Planet` with `gravity` above 0 pulls every dynamic body toward its centre instead of+along the world's single gravity vector, so a round world has a down everywhere (see+[Terrain](/docs/graphics/terrain/) for the planet itself).+## CharactersA `CharacterController3D` replaces a `RigidBody3D` rather than accompanying one: adiff --git a/docs/astro/src/content/docs/gameplay/script-graphs.mdx b/docs/astro/src/content/docs/gameplay/script-graphs.mdxindex 41a82c3e1..1016decf0 100644--- a/docs/astro/src/content/docs/gameplay/script-graphs.mdx+++ b/docs/astro/src/content/docs/gameplay/script-graphs.mdx@@ -26,6 +26,10 @@ The asset is referenced by path and preloaded with the scene, so it is ready befthe agent first ticks. Graphs run in **Play** (and in the exported game), in the`Update` schedule beside the state-machine interpreter.+++*The Script Graph Demo example: a bouncer that moves every frame and turns round at an edge. Variables are listed on the left with how many nodes read and write each.*+## Two kinds of wire| Wire | Carries | Direction |@@ -52,7 +56,7 @@ groups (**Events**, **Flow**, **Variables**, **Values**, **Actions**, **Queries*| **Flow** | **Branch**, **Sequence** (configurable pin count), **While**, **Delay**. || **Variables** | **Get variable**, **Set variable**. || **Values** | **Number**, **Boolean**, **String** literals. |-| **Actions** | Nodes with an exec pin that do something: `timeline.play` / `timeline.pause`, `spriteAnim.play` / `restart` / `stop`, `audio.play` / `stop`, `soundEvent.trigger` / `stop`, `property.set`, `entity.despawn`, `debug.log`, `scene.load` / `reload`, `ui.setVisible`, `ui.setPage`, `fsm.fire`, `blackboard.set` — plus every action you register in code. |+| **Actions** | Nodes with an exec pin that do something: `timeline.play` / `timeline.pause`, `spriteAnim.play` / `restart` / `stop`, `audio.play` / `stop`, `soundEvent.trigger` / `stop`, `property.set`, `entity.spawn` (spawns a prefab the graph names, at an x / y and optionally under a parent, and hands the new entity back), `entity.despawn`, `debug.log`, `scene.load` / `reload`, `ui.setVisible`, `ui.setPage`, `fsm.fire`, `blackboard.set` — plus every action you register in code. || **Queries** | Value-only nodes (no exec pin): `math.*` (add, subtract, multiply, divide, min, max, abs, clamp, lerp, random), `compare.*` (equal, less, greater), `logic.*` (and, or, not), `string.concat`, `property.get`, `entity.self`, `entity.byName`, `input.down` / `pressed` / `axis` / `pointer` — plus every registered condition. || **Graphs** | Every other callable graph in the project, to call it with a **Call graph** node (empty until a graph declares an input). |diff --git a/docs/astro/src/content/docs/getting-started/introduction.mdx b/docs/astro/src/content/docs/getting-started/introduction.mdxindex 2e7eeb048..0c2a21c70 100644--- a/docs/astro/src/content/docs/getting-started/introduction.mdx+++ b/docs/astro/src/content/docs/getting-started/introduction.mdx@@ -6,7 +6,7 @@ description: What Estella is and why it exists.Estella is a **2D and 3D game engine** with a TypeScript SDK driven by ahigh-performance **C++/WebAssembly** backend. It ships with a visual editor forscene editing and project management, and exports one project to **the web,-desktop, WeChat MiniGames, playable ads, and native Android / iOS apps**.+desktop, WeChat and other mini-game platforms, playable ads, and native Android / iOS apps**.## Why Estella?@@ -19,7 +19,7 @@ desktop, WeChat MiniGames, playable ads, and native Android / iOS apps**.- **Visual editor** — scene hierarchy, inspector, and asset browser; no JSONediting.- **Cross-platform** — one project, exported to the web, desktop, WeChat- MiniGames, single-file playable ads, and native Android / iOS apps (arm64 ++ and other mini-game platforms, single-file playable ads, and native Android / iOS apps (arm64 +an embedded Dawn, not a WebView).- **Batteries included** — physics, tilemaps, particles, materials & 2D lighting,animation, Spine, audio, UI, and a gameplay AI layer.diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 473e15770..5828fcc49 100644--- a/docs/astro/src/content/docs/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/graphics/drawing.mdx@@ -208,8 +208,9 @@ A whole **scene** goes into one by pointing a camera at it: setof the screen, before the screen cameras and without competing to be the mainview. Its own sorting layers (`Camera.cullingMask`) decide what it sees, so aminimap camera and the player's camera can look at the same world and show-different parts of it. On WebGL2 today; the WebGPU backend cannot yet hand a-render target's texture to a `Sprite`:+different parts of it. A render target reaches a `Sprite` on both backends; the+pixel check of that path runs on WebGL2 only for now (on WebGPU a frame readback+comes back empty when one frame holds both an offscreen and a surface pass):```typescriptimport { RenderTexture, Draw } from 'esengine';@@ -245,6 +246,51 @@ sprite.texture = rt.texture;This is a low-level surface: it doesn't render the scene for you — it redirectswhatever you draw between `begin`/`end`, under a view-projection matrix you build.+## Packing textures onto one canvas: `TextureAtlas`++Sprites that share a texture draw in one batch. When your pictures arrive separately — icons+fetched from a server, a character built from parts, images a player picked — `TextureAtlas.pack`+draws them onto **one** canvas at run time and tells you where each one landed.++++*Each card above is a sprite cut from the same canvas (the small picture on the right is the+canvas itself). The white square at a card's top-left and the dark bar along its bottom show they+came out the right way up.*++```typescript+import { TextureAtlas } from 'esengine';++// In a system in Schedule.Update — the canvas is painted in a pass of its own.+const atlas = TextureAtlas.pack([iconA, iconB, iconC], { padding: 2 });+if (!atlas) return; // the renderer is not up yet: try again next frame++world.insert(entity, Sprite, { ...atlas.sprite(iconB), size: { x: 64, y: 64 } });+```++`sources` are texture handles (what `Sprite.texture` holds). `atlas.sprite(source)` returns+`{ texture, uvOffset, uvScale }` for a `Sprite`; `atlas.get(source)` returns the pixel rectangle+too (`x`, `y` from the top, `width`, `height`).++| Option | Default | Description |+|---|---|---|+| `maxSize` | `2048` | The largest canvas edge to try, in pixels. Packing throws if the textures do not fit. |+| `padding` | `2` | Transparent pixels kept between pictures, so a filtered edge does not pick up its neighbour. |+| `filter` | `'linear'` | How the canvas is sampled: `'linear'` or `'nearest'` (pixel art). |++- The canvas is the smallest power-of-two size that holds everything. Pictures are copied as+ they are, with no blending, so their transparency is kept exactly.+- A handle given twice is packed once.+- **Keep the source textures alive** for as long as the atlas is in use. After a lost graphics+ device the canvas is drawn again from them, automatically.+- `atlas.repaint()` draws the canvas again by hand (after changing a source); `atlas.release()`+ frees it. Neither touches the sources.+- Like `RenderTexture`, it can be shown on a `Sprite`; the pixel check of that path runs on WebGL2+ only for now (a WebGPU frame readback returns nothing when one frame holds an offscreen and a surface pass).++The [Render Texture example](https://github.com/esengine/estella/tree/master/examples/render-texture)+builds four cards and packs them (`src/systems/atlas.ts`).+## See also- [Sprites & Rendering](/docs/graphics/sprites/) — the component path for images and shapes.diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex 611fc6d69..7f6fefbac 100644--- a/docs/astro/src/content/docs/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/graphics/lighting.mdx@@ -92,7 +92,7 @@ follows the lights near a pixel, not the lights in the scene — a hundred lampsWhat to keep in mind:-- **Tiled lights do not cast shadows.** A shadow-casting light that does not make the sixteen is turned away (the Light Status in the editor says so), since the loop is the only+- **Tiled lights do not cast 3D shadows.** (2D lights are different: the 2D shadow mask serves tiled lights too, see [2D shadows](#2d-shadows).) A shadow-casting light that does not make the sixteen is turned away (the Light Status in the editor says so), since the loop is the onlyplace a shadow map is read. Give the lights that matter shadows and let the many be the glow.- **`radius` is the reach.** The tile masks are built from it; a light with a huge radius touches every tile and costs like it.- Planar reflections are drawn with the sixteen only: their camera is not the one the tiles were made for.@@ -413,9 +413,10 @@ own that is never saved with the scene.## Baked light-Sixteen lights reach one frame. The seventeenth is dropped — by brightness, with a-warning naming what was refused — and that ceiling is not a quality setting: a room-with thirty lamps in it cannot be lit in real time here at all.+A frame carries 112 lights: sixteen read for every pixel and 96 tiled (see+[Many lights](#many-lights)). Past that the dimmest are dropped — by brightness, with a+warning naming what was refused — and that ceiling is not a quality setting. Tiled+lights cast no 3D shadows, and every light still costs its share of every pixel it reaches.A **bake** is the way past it. Light that never moves is computed once, offline, andstored as a texture; at run time the surface reads a texel instead of summing lights.diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxindex 7452f661b..f2a646c89 100644--- a/docs/astro/src/content/docs/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/graphics/sprites.mdx@@ -377,7 +377,8 @@ so a sprite at z = -400 is grabbable where it is drawn.- **Flip** a sprite with `flipX` / `flipY` — e.g. face a character left or right withouta separate texture.- **Atlases**: show one cell of a packed sheet by setting `uvOffset` and `uvScale` to- the cell's normalized rectangle. (For frame-by-frame animation, drive these from the+ the cell's normalized rectangle — or pack separate textures onto one canvas at run time with+ [`TextureAtlas`](/docs/graphics/drawing/#packing-textures-onto-one-canvas-textureatlas). (For frame-by-frame animation, drive these from the[Animator](/docs/animation/overview/) instead of by hand.)- **Scrolling**: animate `uvOffset` over time to scroll a texture (water, conveyorbelts), and set `tileSize` to repeat it across a large sprite.diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdxindex 2f37d96d5..18f190681 100644--- a/docs/astro/src/content/docs/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/graphics/terrain.mdx@@ -299,6 +299,6 @@ Set `sea` and the planet has a sea: a translucent, lit sphere at `seaLevel` abov- **No holes, caves or overhangs.** A heightfield has one height at each place. Caves and bridges are meshes placed with it.- **Position only.** The terrain follows its entity's position; its rotation and scale are not taken into account, by `heightAt` or bythe shader that lifts the ground. Keep the entity unrotated and unscaled, and set the ground's size with `sizeX`, `sizeZ` and `height`.-- **An infinite ground is noise only.** It takes no heightmap or splatmap, and its erosion paints no dirt.+- **An infinite ground is made by its provider.** It takes no heightmap or splatmap, and its erosion (the engine's noise) paints no dirt.- **Pages are made a few a frame**, so on the first frames, or after a jump of the eye, the ground is drawn coarse for a moment andsharpens rather than stalling a frame.diff --git a/docs/astro/src/content/docs/graphics/video.mdx b/docs/astro/src/content/docs/graphics/video.mdxindex 82ab5de07..7e4f58841 100644--- a/docs/astro/src/content/docs/graphics/video.mdx+++ b/docs/astro/src/content/docs/graphics/video.mdx@@ -144,6 +144,8 @@ same component, the same handle sharing — only the decoder differs:| Platform | Decoder | Notes ||---|---|---|| Web / Desktop | `HTMLVideoElement` | Any browser-supported codec (H.264 `.mp4`, WebM…). WebGL2 uploads each frame zero-copy; WebGPU via a canvas readback. |+| Native (Android / iOS) | The same engine-owned wasm decoder, acquired as a side module | Plays the cooked `.esv` + `.m4a`; a device has no other video path. |+| Other mini-game platforms | The same engine-owned wasm decoder, by default on every vendor | Host video decoders are absent on desktop clients and unreliable on phones, so the one deterministic path wins. || WeChat | Engine-owned MPEG-1 wasm (`videodec`, pl_mpeg) | Deterministic on every device — `wx.createVideoDecoder` is absent on PC and unreliable on phones. Ships automatically when a scene uses `Video`; plays the cooked `.esv` + `.m4a`. |## Best practicesdiff --git a/docs/astro/src/content/docs/graphics/water.mdx b/docs/astro/src/content/docs/graphics/water.mdxindex 75ec55e7e..588c780db 100644--- a/docs/astro/src/content/docs/graphics/water.mdx+++ b/docs/astro/src/content/docs/graphics/water.mdx@@ -342,8 +342,8 @@ What is not there yet, so nobody is surprised:- One zone is used, the first `WaterZone` found, with one material for all of its water, and one ocean, the first found. Water outside the zone's region is not drawn, except the ocean.A shore or a river is traced at the zone's resolution: a river a texel or two wide, or an outline's detail finer than that, is lost, and a large region wants a high `resolution`.- The surface reaches `cells * cellSize * 2^(rings - 1) / 2` from the camera; with a `WaterZone` of your own, make that cover what should be seen (a zone you did not author grows its cells to do it).-- A river does not carve the ground, and rapids and falls are not foamed by how fast or steep the water runs. A lake's outline is a polygon on a plane: it does not follow a curved- shore, and the waves die toward the shore without breaking on it.+- A river cuts its bed only when `bedDepth` is above zero (see [Its bed](#rivers)); rapids and falls are not foamed by how fast or steep the water runs. A lake's outline is a polygon on a plane: it does not follow a curved+ shore.- Things float (see [Floating](#floating)) and make a wake (see [Ripples](#ripples)); nothing swims yet.- Caustics and shafts follow the first directional light only, from a pattern and not a simulation: the web does not respond to the actual shape of the waves. From above the causticstake what is under the water to face up (the picture holds no normals there), so a wall under the surface is lit as a floor would be.diff --git a/docs/astro/src/content/docs/index.mdx b/docs/astro/src/content/docs/index.mdxindex 18adf6695..4e007bbb7 100644--- a/docs/astro/src/content/docs/index.mdx+++ b/docs/astro/src/content/docs/index.mdx@@ -45,7 +45,7 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';</Card><Card title="Agent-native" icon="comment">The editor is an MCP server, and it ships an agent of its own. Both drive the- same sixty-five tools the UI does — so an agent can build a scene, press play,+ same hundred-odd tools the UI does — so an agent can build a scene, press play,and look at a screenshot of what it made.</Card></CardGrid>diff --git a/docs/astro/src/content/docs/performance/level-of-detail.mdx b/docs/astro/src/content/docs/performance/level-of-detail.mdxindex 495a5a18e..3da44c7e1 100644--- a/docs/astro/src/content/docs/performance/level-of-detail.mdx+++ b/docs/astro/src/content/docs/performance/level-of-detail.mdx@@ -100,6 +100,7 @@ A field at three levels reaches the GPU as roughly three draws, not as one per p- **The sizes must descend.** `lod2Size` below `lod1Size`, and so on.- **`cullSize: 0`** disables culling entirely, so the group is never invisible.- **A group may have no stand-in at all.** With only a `cullSize` it draws the renderer's own mesh while it is big enough and nothing once it is smaller: the right group for a tuft of grass, which has no cheaper version and is not worth drawing past a distance.+- **The levels can be generated at import.** Set **Generate LODs** to 1–3 levels in a model's import settings (or pass `--lods <n>` to `import-model`): each mesh is collapsed into copies with about 50%, 20% and 7% of its triangles, written as `<mesh>_lod<n>.esmesh`, with a `LODGroup` on the entity. Skinned and morphing meshes, and meshes under **LOD Minimum Triangles** (256), keep one level.- **A skinned group must share one skeleton.** Every level of a skinned mesh needsthe same joint count; a level that disagrees is drawn in its bind pose, and theengine says so.@@ -126,4 +127,9 @@ thousand props is shippable at all.system: every level's mesh is resident, nothing is loaded or unloaded, and anobject that is `cullSize`-small is simply not drawn rather than removed from theworld. Combining distant objects into one merged proxy (HLOD) and loading a world-in pieces are separate concerns.+in pieces are separate concerns, and there is no general-purpose HLOD that bakes+arbitrary scene objects into a proxy. What exists is specific: the far versions+of plants (`Foliage`, `PlacedFoliage` — see [Foliage](/docs/graphics/foliage/)),+the terrain's own distance-based quadtree+([Terrain](/docs/graphics/terrain/)), and [static batching](/docs/performance/static-batching/),+which merges different meshes to save draws but does not make them cheaper far away.diff --git a/docs/astro/src/content/docs/publishing/ads-sharing.mdx b/docs/astro/src/content/docs/publishing/ads-sharing.mdxindex 89c449628..18f4d6a9a 100644--- a/docs/astro/src/content/docs/publishing/ads-sharing.mdx+++ b/docs/astro/src/content/docs/publishing/ads-sharing.mdx@@ -57,12 +57,15 @@ there; the devtools simulator shows a test ad.`Ads.available` is `true` where SOME ad source exists — the platform's, or aninstalled provider. Use it to hide the "watch ad" button honestly:-- **WeChat / Douyin builds** — the host's rewarded/interstitial ads, one family- implementation.+- **Mini-game builds** (WeChat, Douyin and the other family hosts) — the host's+ rewarded/interstitial ads, one family implementation. A vendor whose host has no+ ad call reports `available` as `false`.+- **Web exports on a channel with ads** — Poki, CrazyGames and YouTube Playables+ install their own provider (see below).- **The editor's Play mode** — a **mock provider** is installed automatically:`showRewarded` "plays" for a moment and resolves `completed: true`, with thereal pause/audio ceremony running. Your revive flow rehearses at your desk.-- **Web and native builds** — no ad system, `available` is `false`. A native+- **Plain web and native builds** — no ad system, `available` is `false`. A nativeshell that integrates a mediation SDK installs it through the same door theeditor uses: `Ads.setProvider(...)`.@@ -234,9 +237,6 @@ and `submit()` reaches it, so your own row moves.What it cannot rehearse is the part that is genuinely the host's: real friendsand the sandbox they live in. Check that on a device before you ship.-What it cannot rehearse is the part that is genuinely the host's — real friends-and the sandbox they live in. Check that on a device before you ship.-## Signing inA mini-game host signs the player in and hands back a **one-time code**. That@@ -353,6 +353,24 @@ has been checked with the training example's real SDK initialization, loading,play/pause and rewarded completion. Complete the remaining QA modules beforesubmission; these observations do not certify devices or production ad fill.+## CrazyGames Web exports++In the same Web packaging setting select **CrazyGames**, or set+`packaging.platforms.web.channel` to `"crazygames"`. The export connects the official+v3 SDK: it reports loading start and stop, serves rewarded and midgame breaks+through the existing `Ads` resource, stores saves through the SDK's Data API (switch on+**Progress Save** in the CrazyGames developer console; `setItem` is not a cloud-backup+acknowledgment) and follows the host's audio mute. If initialization fails the game+continues with the host services off.++As with Poki, game logic reports the real gameplay start and stop transitions; the+exporter does not infer them. `Scores.submit` can send an encrypted score for an invited+CrazyGames leaderboard — enter the base64 **Encryption Key** from the platform+configuration in Project Settings (never the server API key; it ships in the Web+package), and leave it empty to disable submission. A sent score does not prove the+leaderboard accepted it, and an export is not platform approval: complete the official+checks separately.+## YouTube Playables Web exportsExport checks stored total size below 250 MiB, each file below 30 MiB, at mostdiff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdxindex db8abd59c..917ad3275 100644--- a/docs/astro/src/content/docs/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx@@ -173,6 +173,10 @@ folder holds the finished app:writing a project that cannot link.</Aside>+++*The Android target. Until the runtime template is installed, the dialog says so and offers **Download** or **Install from file**.*+## App identityA native app has OS-level properties the engine never reads — the runtime cannotdiff --git a/docs/astro/src/content/docs/publishing/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdxindex 617bebf01..97a38f6c1 100644--- a/docs/astro/src/content/docs/publishing/hot-update.mdx+++ b/docs/astro/src/content/docs/publishing/hot-update.mdx@@ -144,7 +144,7 @@ never disagree about where an asset ships):## What the build ships-Every Web / Desktop export always writes an **`asset-manifest.json`** (the+Every Web, Desktop, mini-game and native export always writes an **`asset-manifest.json`** (theaddressable manifest) next to the game — that's what a client diffs against for ahot update. When the build has a CDN root, the export also bakes a`hotUpdate` block into `game.config.json`:diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex 6e78879cd..431d774fc 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -5,9 +5,9 @@ description: Ship one project to Web, Desktop, WeChat MiniGame, a single-file Plimport { Aside, Steps } from '@astrojs/starlight/components';-One Estella project ships to six targets — **Web**, **Desktop**, **WeChat-MiniGame**, a single-file **Playable Ad**, and native **Android** / **iOS** apps —-all from the editor. The export uses the **same runtime you played in the editor**,+One Estella project ships to **Web**, **Desktop**, **WeChat MiniGame** and the other+mini-game platforms (Douyin, Kuaishou, Bilibili, quick games, Alipay, Huawei), a+single-file **Playable Ad**, and native **Android** / **iOS** apps — all from the editor. The export uses the **same runtime you played in the editor**,so what you shipped is what you tested (*play == ship*).## Exporting from the editor@@ -76,9 +76,10 @@ and opens it in your browser.| **Web** | A static, self-contained web build. | `dist-web/` | **Preview over http**, or upload the folder to any static host. || **Desktop** | A runnable **native** app per installed desktop template — a `.app` on macOS, a `<Name>/` directory holding `<Name>.exe` on Windows or `<Name>` on Linux. No Chromium and no npm project. | `dist-desktop/` | Double-click it. Selecting the **Steam** channel also writes the depot scripts and a `STEAM.md` with this build's own values — see [Steam](/docs/publishing/steam/). || **WeChat** | A WeChat MiniGame package. | `dist-wechat/` | Open the folder in WeChat DevTools and set your AppID. See [WeChat MiniGame](/docs/publishing/wechat/). |+| **Douyin**, **Kuaishou**, **Bilibili**, **Quick games**, **Alipay**, **Huawei** | A mini-game package for that host (a signed `.rpk` for quick games and Huawei), on the same pipeline as WeChat — see [Mini-game platforms](/docs/publishing/minigame-platforms/). | `dist-douyin/`, `dist-kuaishou/`, `dist-bilibili/`, `dist-quickgame/`, `dist-alipay/`, `dist-huawei/` | Open it in that platform's developer tool (Douyin and Bilibili take an AppID in Project Settings; Kuaishou and Alipay take it in the developer tool; Huawei needs an app registered in AppGallery Connect). || **Playable** | One self-contained `index.html` with everything inlined — no external requests, as ad networks require. | `dist-playable/` | **Preview over http** (its real surface is an ad-network iframe). Pick the [ad network](#playable-ad-networks) so the CTA and the size check match where it ships. |-| **Android** | Content for a **native** arm64 app (Vulkan) — a real APK, not a WebView. | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` wraps it in a signed APK. See [Android & iOS](/docs/publishing/android-ios/). |-| **iOS** | Content for a **native** arm64 app (Metal), plus the Xcode project when the engine is built for iOS here. | `dist-ios/` | Open the generated Xcode project, pick a signing team, Run. See [Android & iOS](/docs/publishing/android-ios/). |+| **Android** | Content for a **native** arm64 app (Vulkan) — a real APK, not a WebView. | `dist-android/` | With the Android runtime template installed, the export writes the signed APK itself (or an Android Studio project, or an App Bundle beside the APK). See [Android & iOS](/docs/publishing/android-ios/). |+| **iOS** | Content for a **native** arm64 app (Metal), plus the Xcode project written around it once the iOS runtime template is installed. | `dist-ios/` | Open the generated Xcode project, pick a signing team, Run. See [Android & iOS](/docs/publishing/android-ios/). |Desktop, Android and iOS export app **content**, not a runnable payload: theengine, the SDK and the game runtime live in the app binary. Each is assembled@@ -114,9 +115,9 @@ selected it is a no-op, so the same scene still runs in the editor and on the we| Network | Limit | Click-through | Notes ||---|---|---|---|-| **Generic** | 2MB | — | No network API. The cap is the strictest we know of, since an unnamed target could be any of them. |-| **Meta** (Facebook / Instagram) | 2MB for `index.html` | `FbPlayableAd.onCTAClick()` | Meta's 5MB figure is the total for a ZIP bundle; a single-file playable is capped by the `index.html` rule. Forbids any HTTP request. |-| **Google Ads** (App campaigns) | 5MB | `ExitApi.exit()` | Its exit API is a Google-hosted script, which the docs require as a literal `<script>` in `<head>` — the export writes it for you. Google uploads a **ZIP**, so compress the `index.html` before uploading. |+| **Generic** | 5MB | — | No network API. The cap is the one every network listed here accepts, since an unnamed target could be any of them. |+| **Meta** (Facebook / Instagram) | 5MB | `FbPlayableAd.onCTAClick()` | Meta caps a playable HTML5 file at 5MB; the 2MB figure often quoted for it is in no Meta specification. Forbids any HTTP request. |+| **Google Ads** (App campaigns) | 5MB | `ExitApi.exit()` | Its exit API is a Google-hosted script, which the docs require as a literal `<script>` in `<head>` — the export writes it for you. Google uploads a **ZIP**, so the export also writes `playable.zip` beside the HTML and measures the limit on that. || **MRAID network** (generic) | 5MB | `mraid.open()` | For any MRAID host. `mraid` is injected by the webview, so nothing goes in `<head>`. || **Unity Ads** | 5MB | `mraid.open()` | The runtime waits for MRAID readiness and viewability, pauses on hidden ads, and removes host listeners on exit. || **AppLovin** | 5MB | `mraid.open()` | Requires every resource embedded — which a single-file playable already is. |@@ -188,16 +189,22 @@ export default {It then appears in the dialog's Ad network dropdown beside the built-in ones, andpackages through the same pipeline.+++*The Playable target. The **Ad network** picks the size limit and the delivery shape the package is held to.*+## Runtime prerequisitesWeb, Desktop and **Playable** all reuse the engine runtime that ships with theeditor, so they export with no setup — a playable inlines that same web runtime(glue as a blob module, wasm as base64) rather than needing a build of its own.**WeChat** is the exception among the web-based targets: its WebAssembly loader-differs, so its runtime is built once:+differs, so it runs on a runtime of its own. The editor download carries that too, with+the side modules WeChat needs, so an installed editor exports to WeChat with no setup. In+an engine source checkout it is built once:```bash-# only before the first WeChat export+# source checkout only, before the first WeChat exportnode build-tools/cli.js build -t wechat```@@ -205,8 +212,8 @@ The Package Project dialog reminds you when a target's runtime is missing, and aWeChat export **fails fast** — naming the exact build command — rather thanproducing a package that breaks at runtime. WeChat also needs a matching sidemodule for each engine feature the game uses (`physics-wechat`, `spine-wechat`,-`basis-wechat` for compressed textures) — see-[WeChat MiniGame](/docs/publishing/wechat/).+`dragonbones-wechat`, `basis-wechat` for compressed textures, `videodec-wechat` for+video) — see [WeChat MiniGame](/docs/publishing/wechat/).The dialog distinguishes **two kinds** of missing prerequisite, because they don'tblock the same amount:@@ -218,11 +225,12 @@ block the same amount:toolchain, and that step can run on another machine — an iOS build always doeswhen the editor is on Windows.-<Aside type="caution" title="Mobile needs an engine checkout">- Android and iOS are the one pair of targets the editor download does not carry- end to end: the native host is built once from an engine source checkout (Dawn +- QuickJS), plus the Android SDK/NDK or macOS with Xcode. See- [Android & iOS](/docs/publishing/android-ios/).+<Aside type="caution" title="Mobile needs a runtime template">+ Android and iOS are the one pair of targets the editor download does not carry:+ the engine's compiled half is a runtime template you download once per editor+ version (the target's row in Package Project offers **Download**). That is all+ Android needs — no engine checkout, SDK, NDK or JDK. iOS additionally needs macOS+ with Xcode to sign and run. See [Android & iOS](/docs/publishing/android-ios/).</Aside>## Content a target cannot render@@ -311,7 +319,7 @@ Resize it (or pad it) to a multiple of 4 to get the compression back. Atlas pageare always whole blocks, so packing small odd-sized sprites is the other way out.:::-**Content addressing** is on by default for Web/Desktop (each file named by a hash+**Content addressing** is on by default (Web, Desktop and the mini-game targets; each file named by a hashof its bytes — immutable URLs, automatic dedupe). **Advanced** holds the CDN rootfor [hot update](/docs/publishing/hot-update/), source maps, and whether to open theoutput folder when the build finishes.@@ -371,7 +379,7 @@ the game for good — the player turns the phone and nothing changes, because thquery was reading the container all along. Playables stay responsive (every networkasks for that), and the orientation is only *declared* to the platform where one wantsit, e.g. Google's `ad.orientation` meta tag. Design for both aspects, or letterbox-with [a camera fit](#) so the framing survives either one.+with [a camera fit](/docs/core-concepts/screen/) so the framing survives either one.See [The Editor](/docs/editor/overview/) for the settings UI.@@ -411,7 +419,7 @@ import { Tilemap } from 'esengine/tilemap';One subsystem has no subpath yet: a project using **Video** takes the whole engine, withevery optional subsystem in it. Nothing else changes — the API is identical either way.-The same goes for the engine binary on WeChat and Douyin. When no scene or prefab has a particle emitter, a post-process volume or a+The same goes for the engine binary on the WeChat-runtime mini-game targets (WeChat, Douyin, Kuaishou, Bilibili). When no scene or prefab has a particle emitter, a post-process volume or atilemap, and no script mentions them, the package carries the **lite engine**: the same engine without those three subsystems, about200 KB smaller against the 4 MB main package. A single mention in a script (`ParticleEmitter`, `PostProcess…`, `Tilemap…`) is enough to carrythe full one, as is naming `esengine/tilemap` as **Include** in Project Settings; a doubt always ships everything.@@ -425,7 +433,7 @@ platform's current docs rather than trusting us:| Target | Limit || --- | --- || WeChat MiniGame | 4MB main package, and 30MB across the main package and all subpackages |-| Playable ad | whatever the chosen network accepts — Meta 2MB for a single `index.html`, Google 5MB for a ZIP, etc. |+| Playable ad | whatever the chosen network accepts — Meta 5MB, Google 5MB for a ZIP, etc. || Web / Desktop / Android / iOS | none published; set your own below |A build over a limit is reported, not blocked — it built and it runs, and whetherdiff --git a/docs/astro/src/content/docs/publishing/wechat.mdx b/docs/astro/src/content/docs/publishing/wechat.mdxindex 6c41ee1be..8a914c53e 100644--- a/docs/astro/src/content/docs/publishing/wechat.mdx+++ b/docs/astro/src/content/docs/publishing/wechat.mdx@@ -5,12 +5,13 @@ description: Build and export a game for WeChat MiniGames, with subpackages.import { Steps, Aside } from '@astrojs/starlight/components';-Estella exports the same project to **WeChat MiniGames**. You build the engine-for the WeChat target, export the game from the editor, and open the result in-WeChat DevTools.+Estella exports the same project to **WeChat MiniGames**. You export the game from+the editor and open the result in WeChat DevTools.## Build the engine for WeChat+The editor download already carries the WeChat engine and its side modules, so an+installed editor needs none of this. In an engine source checkout, build them once.The WeChat target compiles the C++ core with WeChat's `WXWebAssembly` shims:```bash@@ -63,11 +64,16 @@ the side modules your scenes need. Every scene in the build is aDevTools.</Aside>+++*The WeChat target: the size limits under the title, then the target's own settings, then the shared build options.*+## Compressed textures-Enable **Compress textures** in the Package dialog to cook PNGs to KTX2 —-a smaller package and faster first load. Two WeChat-specific details, both-handled automatically:+With the Package dialog's **Compression** set to **By import settings**, textures+cook to KTX2 per their **Compression** import setting (Auto, GPU compressed or+Original image) — a smaller package and faster first load. Two WeChat-specific+details, both handled automatically:- The Basis transcoder ships as the `basis-wechat` side module — build it once(above), or the export fails with the exact command to run.@@ -135,7 +141,7 @@ levels download on demand rather than bloating the initial package:`subpackages/<name>/` — see [Assets](/docs/assets/overview/). The export sets`bigPackageSizeSupport`, so an oversized package still *previews* inDevTools — but upload enforces the cap.-- **Compress textures** — see above; the single biggest package-size win.+- **Compress textures** — see above (leave **Compression** on **By import settings**); the single biggest package-size win.- **Test in WeChat DevTools**, not just the browser — the file system, storage,and socket backends differ from the web.- **Preload the next level's group** (`loadGroup`) during play so thediff --git a/docs/astro/src/content/docs/scripting/events.mdx b/docs/astro/src/content/docs/scripting/events.mdxindex 8d021cd08..8425eda5f 100644--- a/docs/astro/src/content/docs/scripting/events.mdx+++ b/docs/astro/src/content/docs/scripting/events.mdx@@ -16,7 +16,8 @@ click ─▶ ui.setPage(badge, on) on "Card"Wires are deliberately **not** a visual programming language. A row has no branches and noexpressions; when something genuinely needs logic, the row names an action that hands off to-[a state machine](/docs/gameplay/ai/overview/) — the editor Estella already has for graphs.+[a state machine](/docs/gameplay/ai/overview/) — the editor Estella already has for graphs — and logic that is easier to draw can live in a+[script graph](/docs/gameplay/script-graphs/), whose **On event** node listens for the same named entity events.## A wire in the inspectordiff --git a/docs/astro/src/content/docs/scripting/input.mdx b/docs/astro/src/content/docs/scripting/input.mdxindex 5c7118471..1c48707c4 100644--- a/docs/astro/src/content/docs/scripting/input.mdx+++ b/docs/astro/src/content/docs/scripting/input.mdx@@ -129,6 +129,7 @@ bindings, and multiple bindings sum (then clamp), so keyboard and gamepad coexis| `Keys1D(neg, pos)` | axis | Two keys → a signed 1D axis. || `Keys2D(up, down, left, right)` | axis2d | Four keys → a 2D direction. || `Stick('left' \| 'right', pad?)` | axis2d | A gamepad stick (up = +y, matching `Keys2D`). |+| `Virtual(id)` | button / axis / axis2d | A named value the game writes with `input.setVirtual(id, x, y)` — what an on-screen [VirtualJoystick or VirtualButton](/docs/ui/widgets/#virtualjoystick) feeds, so touch controls drive the same action a key does. |### The data model@@ -156,6 +157,7 @@ const jump: ActionDef = {| `keys1d` | `neg`, `pos` | `Keys1D` || `keys2d` | `up`, `down`, `left`, `right` | `Keys2D` || `stick` | `stick: 'left' \| 'right'`, `pad?` | `Stick` |+| `virtual` | `id` | `Virtual` |Because bindings are data, this one model is also the **rebind and persistenceformat**: `toJSON()` / `loadJSON()` round-trip the bindings alone (per-actiondiff --git a/docs/astro/src/content/docs/scripting/math.mdx b/docs/astro/src/content/docs/scripting/math.mdxindex b6fdff16d..5b28aa93a 100644--- a/docs/astro/src/content/docs/scripting/math.mdx+++ b/docs/astro/src/content/docs/scripting/math.mdx@@ -73,6 +73,26 @@ scalar.deg2rad(90); // degrees -> radiansAlso: `clamp`, `inverseLerp`, `rad2deg`, `approximately`, `mod`, `sign`.+## Seeded randomness++`createRng(seed)` returns a seeded generator that draws **the same sequence on every+host** (SFC32 over 32-bit integer arithmetic), so a server that settles an outcome and a+client that previews it agree. `hashSeed` turns a number, string or list into a stable+32-bit hash:++```typescript+import { createRng } from 'esengine';++const rng = createRng(['loot', levelId]);+rng.float(); // [0, 1)+rng.int(1, 6); // 1..6 inclusive, no modulo bias+rng.chance(0.25); // true 25% of the time+rng.pick(items); // one element+rng.weighted(items, (i) => i.weight);+rng.shuffle(items); // a shuffled copy+const drops = rng.fork('drops'); // an independent stream, unmoved by draws on this one+```+## Rotation helpers`Transform.rotation` is a quaternion; in 2D you only ever rotate about Z, and a@@ -99,6 +119,8 @@ const delta = normalizeAngle(targetAngle - facing);| `quaternionToAngle2D(rz, rw)` | Z angle in radians from a quaternion's `z`/`w` (`2 * atan2(z, w)`). || `normalizeAngle(a)` | Wrap any angle to `(-π, π]` for shortest-turn comparisons. |+For full 3D rotations, the `q` namespace has `create`, `mul`, `axis(axis, rad)`, `normalize`, `conjugate`, `rotate(q, v)`, `fromEuler` / `toEuler`, `rotationTo(from, to)`, `setAngleZ` / `angleZ` and more.+For direction *vectors* instead of rotations, stay in `v2`: `fromAngle` /`angle` / `rotate`. A full worked example (turrets facing the cursor) is in[Transforms, Units & Coordinates](/docs/core-concepts/transforms/#rotating-in-2d).diff --git a/docs/astro/src/content/docs/scripting/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdxindex 6073c2944..01d795463 100644--- a/docs/astro/src/content/docs/scripting/networking.mdx+++ b/docs/astro/src/content/docs/scripting/networking.mdx@@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components';Estella ships a **cross-platform WebSocket**. `createSocket` returns the rightimplementation for the platform — a browser `WebSocket` on the web, `wx.connectSocket`-on WeChat MiniGames — behind one API. On top of it, `NetChannel` adds typed messages+on WeChat MiniGames, `ws` under Node, and the native and other mini-game hosts' own sockets — behind one API. On top of it, `NetChannel` adds typed messagesand request/response.## Connect & exchange messages@@ -155,7 +155,7 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // per-tick input uplin- **Reconnect is yours for now**: `Replicated.owner` is a *connection* id, and aplayer who reconnects gets a new one. Nothing in the SDK carries an identityacross a dropped socket, so a stable player id, a session token and a grace- window belong to your game.+ window belong to your game. (The request/reply [session layer](#asynchronous-online-games--sessions) below does redial and keep subscriptions across drops, but it is separate from replication.)See the **Multiplayer Arena** example for the full pattern — replication, per-tick input, and client prediction — in ~130 lines. Its `server/` directory is the dedicated-server half: the same project, headless, behind a real WebSocket.@@ -281,6 +281,52 @@ never re-sends snap back. Owned entities bypass snapshot interpolation.of hard-snapping; add `maxError` so a genuine teleport still snaps. Purelypresentational — the simulation state can't drift.+## Asynchronous online games — sessions++Replication shares a tick between server and clients. A game played **asynchronously**+over a shared world (a city builder, a card game, a gacha) has no shared tick; it needs+requests and replies that survive a bad link. That is the job of `esengine/session`,+independent of replication:++- A **`SessionHost`** on the server authenticates each connection before it serves+ anything, limits frame size and message rate, pings the client, and lets a newer+ connection for the same player replace the older one. It holds no game state: every+ handler receives the player from its context.+- A **`ClientSession`** on the device dials, redials with backoff and jitter when the link+ drops, waits for the server before a request goes out, and keeps event subscriptions+ across reconnects. `retryNow()` redials at once; `serverNow()` is the server's clock.+- Every request carries a **key**, so one whose reply was lost and is sent again is+ answered from memory instead of running twice (a purchase, a departure). Several server+ processes share one `IdempotencyStore`.+- `defineContract` writes every request and event once with the `s` validators+ (`s.object`, `s.int`, `s.string`, …); the server checks each request against it, the+ client checks each reply, and both are typed from it. Its `fingerprint` lets the server+ turn away a client built against another contract.++```typescript+import { defineContract, s, SessionHost, ClientSession, acceptWebSocket } from 'esengine/session';+import { createSocket } from 'esengine';++const api = defineContract({+ requests: { buy: { req: s.object({ item: s.string() }), res: s.object({ gold: s.int() }) } },+ events: { news: s.object({ text: s.string() }) },+});++// SERVER (Node): wire each `ws` socket into a host.+const host = new SessionHost({ authenticate: (cred) => ({ playerId: String((cred as any).id) }) });+api.serve(host, { buy: async ({ item }, ctx) => ({ gold: await purchase(ctx.playerId, item) }) });+// wss.on('connection', (socket) => acceptWebSocket(host, socket));++// CLIENT: one object for the whole run, however often the link drops.+const session = new ClientSession({ connect: () => createSocket({ url: 'wss://example.com/play' }), credentials: () => ({ id: 'p1' }) });+await session.start();+const { gold } = await api.client(session).buy({ item: 'sword' });+```++A session can speak protobuf instead of JSON (`wire: 'pb'` on the client, `wire` on the+host; `proto()` / `protoAs()` bring a `.proto` message into a contract) and still be read+as JSON in a debugger.+## Best practices- **Use `NetChannel`** for anything beyond a trivial socket — routed types and RPCdiff --git a/docs/astro/src/content/docs/ui/interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdxindex a8669c192..8addf0ab7 100644--- a/docs/astro/src/content/docs/ui/interaction.mdx+++ b/docs/astro/src/content/docs/ui/interaction.mdx@@ -199,8 +199,9 @@ const focusDebug = defineSystem([Res(FocusManager)], (focus) => {```<Aside type="note">- Gamepad navigation is not built into the focus system — the ring is driven by- `Tab` / `Enter` / `Space` / `Escape` and the arrow keys. For gamepad menus,+ Gamepad navigation is not built into the focus system — the ring moves with+ `Tab` / `Shift+Tab` only (`Enter` / `Space` / `Escape` and the arrow keys act on the+ focused widget). For gamepad menus,drive selection yourself from an [input map](/docs/scripting/input/) and callwidget state directly.</Aside>diff --git a/docs/astro/src/content/docs/ui/overview.mdx b/docs/astro/src/content/docs/ui/overview.mdxindex 98f2b0a40..10750c487 100644--- a/docs/astro/src/content/docs/ui/overview.mdx+++ b/docs/astro/src/content/docs/ui/overview.mdx@@ -267,8 +267,8 @@ does not move, so the component is inert until there is something to scroll.| `horizontal` / `vertical` | `false` / `true` | Which axes scroll. || `movement` | `Clamped` | `Elastic` overshoots at the ends and springs back. || `wheelSpeed` | `1` | Multiplier on wheel deltas. |-| `dragScroll` | `true` | Drag/touch grabbing, with a kinetic fling. |-| `decelerationRate` | `0.135` | Fling velocity kept per second; `0` stops on release. |+| `dragScroll` | `true` | Drag/touch grabbing; the kinetic fling after release runs only with `Elastic`. |+| `decelerationRate` | `0.135` | Fling velocity kept per second under `Elastic`; `0` stops on release. With `Clamped` the component always stops on release. |```ts// A list that scrolls vertically inside a fixed box.diff --git a/docs/astro/src/content/docs/ui/widgets.mdx b/docs/astro/src/content/docs/ui/widgets.mdxindex 5e3cba512..ca4b5a087 100644--- a/docs/astro/src/content/docs/ui/widgets.mdx+++ b/docs/astro/src/content/docs/ui/widgets.mdx@@ -390,8 +390,10 @@ the caret position, click-to-place and within-line selection track thenewlines).<Aside type="note">- Text input runs in **play mode only** and needs a browser DOM (the hidden- native textarea) — it's inert in the editor's edit view.+ Text input runs in **play mode only** and needs a platform text-editing surface:+ the hidden native textarea on the web, the host's own text model (SDL input and+ IME) in native builds. A headless host renders fields but cannot type into them,+ and the editor's edit view leaves them inert.</Aside>## Lists & scrollingdiff --git a/docs/astro/src/content/docs/world/generation.mdx b/docs/astro/src/content/docs/world/generation.mdxindex 269a8ec06..d96daaae3 100644--- a/docs/astro/src/content/docs/world/generation.mdx+++ b/docs/astro/src/content/docs/world/generation.mdx@@ -103,7 +103,7 @@ A member names a mesh and a material, or a **plant**: an entry in the rules' `pl| `sink` | How far it is sunk into the ground, in world units (a stone's buried underside). || `unit` | World units to a unit of its mesh: 100 for plants modelled in metres in a world of centimetres. A recipe's `scale` is then a size relative to the model. |-Plants are grown a cell at a time by the same machinery as a [placed foliage](/docs/graphics/foliage/#placed-plants): a chunk stands at once and fills in over the frames after it, each mesh a few milliseconds of the frame's budget. The far versions are a layer of their own, laid out as far as the furthest of them goes and shown from past what their kinds draw as themselves, so a layer's `drawDistance` is what its plants draw as themselves and not how far the world is seen. A world on a terrain of an area ends where the terrain does. A plant stands upright; it does not lean with the ground.+Plants are grown a cell at a time by the same machinery as a [placed foliage](/docs/graphics/foliage/#placed-plants): a chunk stands at once and fills in over the frames after it, each mesh a few milliseconds of the frame's budget. The far versions are a layer of their own, laid out as far as the furthest of them goes and shown from past what their kinds draw as themselves, so a layer's `drawDistance` is what its plants draw as themselves and not how far the world is seen. A world on a terrain of an area ends where the terrain does.### Layersdiff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex df1d979f1..763878cec 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -112,9 +112,9 @@ Where particles spawn and their initial direction. See [Emitter shapes](#emitter| Property | Type | Default | Description ||---|---|---|---|-| `shape` | `EmitterShape` | `Cone` | `Point` / `Circle` / `Rectangle` / `Cone`. |-| `shapeRadius` | number | `100` | Radius for `Circle` / `Cone`. |-| `shapeSize` | Vec2 | `{100, 100}` | Box extents for `Rectangle`. |+| `shape` | `EmitterShape` | `Cone` | `Point` / `Circle` / `Box` / `Cone` / `Sphere` / `Hemisphere`. |+| `shapeRadius` | number | `100` | Radius for `Circle` / `Cone` / `Sphere` / `Hemisphere`. |+| `shapeSize` | Vec3 | `{100, 100, 0}` | Box extents for `Box` (a `z` of `0` is the flat rectangle a 2D emitter spawns from). || `shapeAngle` | number | `25` | Cone half-angle (°) for `Cone`. |### Velocity & forces@@ -123,9 +123,9 @@ Where particles spawn and their initial direction. See [Emitter shapes](#emitter|---|---|---|---|| `speedMin` | number | `500` | Slowest initial speed. || `speedMax` | number | `500` | Fastest initial speed. |-| `angleSpreadMin` | number | `0` | Start of the emission-direction arc (°). |-| `angleSpreadMax` | number | `360` | End of the emission-direction arc (°). |-| `gravity` | Vec2 | `{0, 0}` | Constant acceleration applied to every particle. |+| `angleSpreadMin` | number | `0` | Start of the emission-direction arc (°), in the emitter's local XY plane. Read by `Point` and `Box` only. |+| `angleSpreadMax` | number | `360` | End of the emission-direction arc (°). Read by `Point` and `Box` only. |+| `gravity` | Vec3 | `{0, 0, 0}` | Constant acceleration applied to every particle. || `damping` | number | `0` | Velocity drag per second (`0` = none). || `addedVelocityMin` / `addedVelocityMax` | Vec3 | `{0,0,0}` | A velocity each particle carries on top of its own, chosen between the two ends when it is born. Gravity, damping, noise and the speed limit do not act on it. CPU simulation. || `speedLimit` | number | `0` | The fastest a particle may move under its own velocity (`0` = no limit). A faster one is pulled back toward the limit. CPU simulation. |@@ -227,12 +227,17 @@ See [Per-particle trails](#per-particle-trails) below.| Shape | Uses | Behavior ||---|---|---|| `Point` | — | All particles spawn at the entity origin. |-| `Circle` | `shapeRadius` | Spawn inside a disc; direction radiates outward. |-| `Rectangle` | `shapeSize` | Spawn inside a box. |+| `Circle` | `shapeRadius` | Spawn inside a disc in the emitter's own plane; direction radiates outward. |+| `Box` | `shapeSize` | Spawn inside a box (a flat rectangle when `shapeSize.z` is `0`). || `Cone` | `shapeRadius`, `shapeAngle` | Spawn in a cone — a directed spray (fountains, thrusters). |+| `Sphere` | `shapeRadius` | Spawn inside a ball; direction radiates outward. |+| `Hemisphere` | `shapeRadius` | Spawn inside a half ball about local +Y; direction radiates outward. |-The `angleSpreadMin…Max` arc further constrains the launch direction, so you can-aim any shape (e.g. a `Circle` that only emits upward with `0…180`).+Directed shapes point along the emitter's local +Y, so an unrotated emitter sprays up+and rotating the entity aims it, in 3D as well. `Point` and `Box` have no direction of+their own: the `angleSpreadMin…Max` arc (in the emitter's local XY plane) says which way+they launch, so a `Point` that only emits upward uses `0…180`. `Circle`, `Cone`, `Sphere`+and `Hemisphere` carry their direction with them and ignore the arc.## Color & size over life@@ -329,12 +334,13 @@ the parent triggers it. Its `burstCount` sets how many particles each sub-burstspawns. Point the parent's `subEmitter` at that child entity:```typescript-import { SubEmitterTrigger } from 'esengine';+import { EmitterShape, SubEmitterTrigger } from 'esengine';// The burst template — a normal emitter that only fires when triggered.const shell = cmds.spawn().insert(Transform, {}).insert(ParticleEmitter, {+ shape: EmitterShape.Point, // no direction of its own: sparks fly all roundrate: 0, playOnStart: false, burstCount: 44, // 44 sparks per burstlifetimeMin: 0.6, lifetimeMax: 1.1, speedMin: 160, speedMax: 340,startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },@@ -345,6 +351,7 @@ const shell = cmds.spawn()cmds.spawn().insert(Transform, { position: { x: 0, y: -230, z: 0 } }).insert(ParticleEmitter, {+ shape: EmitterShape.Point,rate: 2.5, lifetimeMin: 1.4, lifetimeMax: 1.8, speedMin: 560, speedMax: 660,angleSpreadMin: 84, angleSpreadMax: 96,subEmitter: shell,@@ -455,8 +462,8 @@ splashes fade out instead of skittering forever.<Aside type="note">This is a single horizontal floor — the common case (a ground line). Collision- against arbitrary geometry and tilemaps goes through the physics world and is a- separate, opt-in path. Like force fields, floor collision applies to **world-space**+ against walls, bodies and tilemap colliders goes through the physics world (`Physics2D` /+ `Physics3D`) and is a separate, opt-in path: see [Scene collisions](#scene-collisions). Like force fields, floor collision applies to **world-space**particles only.</Aside>diff --git a/docs/astro/src/content/docs/world/prefabs.mdx b/docs/astro/src/content/docs/world/prefabs.mdxindex 256bca6b4..dfa31f79c 100644--- a/docs/astro/src/content/docs/world/prefabs.mdx+++ b/docs/astro/src/content/docs/world/prefabs.mdx@@ -178,6 +178,7 @@ Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'| `parent` | Entity | Nest the instance under this entity. || `overrides` | override[] | Per-instance component-value changes. || `baseUrl` | string | Base URL for resolving the prefab's assets. |+| `scene` | boolean | Default `true`: what is spawned belongs to the scene live when it landed and goes with it. Pass `false` for something meant to outlive the area it came from. || Result field | Description ||---|---|diff --git a/docs/astro/src/content/docs/world/streaming.mdx b/docs/astro/src/content/docs/world/streaming.mdxindex 17a3d812e..73422f71a 100644--- a/docs/astro/src/content/docs/world/streaming.mdx+++ b/docs/astro/src/content/docs/world/streaming.mdx@@ -130,8 +130,8 @@ because either one points at something residency is entitled to delete.**Residency owns existence; it does not own continuity.** A cell that unloadsloses its runtime state, and reloading rebuilds it from what was authored. Anenemy at 25 health that you walk away from comes back at full health. What does-survive is the entity's authored identity, which is what a save system will be-built on later.+survive is the entity's authored identity, which a save system can be built on+(the engine keeps no per-cell state for you).## Procedural chunks@@ -183,9 +183,17 @@ does not exist look the same from a camera.## What this version does not do-Cells load asynchronously through the same scene loading a game already uses, but-there is no priority, no prefetch and no budget yet: a large cell arriving is a-hitch. There is no HLOD, so a place that is not resident is not represented at-all in the distance. Navigation meshes are not streamed — a world-sized navmesh-stays resident. Neither is texture streaming, and the world origin is never-rebased.+Cells load asynchronously through the same scene loading a game already uses.+They are ordered (a cell a source is walking into goes before one it only might,+nearest first) and can be readied ahead by `prefetchRadius`, but there is no+admission budget: a large cell arriving is still a hitch. There is no+general-purpose HLOD for streamed cells — nothing bakes a cell into a single+far proxy, so a cell that is not resident is not represented at all in the+distance. Some content has a far version of its own: the ground+([Terrain](/docs/graphics/terrain/) is a distance-based quadtree out to+`drawDistance`, a planet is one down to its horizon), and plants (the far+cards of [Foliage](/docs/graphics/foliage/) and `PlacedFoliage`, and of a+generated world's plants) stand over a whole area at once. Navigation meshes are+not streamed — a world-sized navmesh stays resident. Neither is texture+streaming, and the world origin is never rebased (`setRenderOriginStep` keeps+*drawing* precise far from zero, see [Camera](/docs/graphics/camera/)).diff --git a/docs/astro/src/content/docs/zh-cn/agents/built-in.mdx b/docs/astro/src/content/docs/zh-cn/agents/built-in.mdxindex 8611bc213..9123f3957 100644--- a/docs/astro/src/content/docs/zh-cn/agents/built-in.mdx+++ b/docs/astro/src/content/docs/zh-cn/agents/built-in.mdx@@ -91,13 +91,14 @@ import { Aside, Steps } from '@astrojs/starlight/components';## 哪些事它不用问就能做-分级是按**撤销在哪里失效**划的,这也是它值得你知道的原因:+分级是按**撤回在哪里失效**划的,这也是它值得你知道的原因:| 层级 | 例子 | 会发生什么 || --- | --- | --- || 只读 | `get_scene_tree`、`get_inspector`、`capture_viewport` | 直接跑,从不询问。 || 可撤销 | 新建、删除、`set_field`、改父子、刷瓦片 | 直接跑。整一轮外面套着一个检查点,一次**撤销**就能全退。 |-| 不可逆 | 写文件、导出构建、保存、`run_editor_command` | **一定先问**。事后撤销救不了你。 |+| 项目文件 | `write_project_file`、`save_scene`、新建脚本、场景或资产 | 直接跑。编辑器会保存每个文件改动前的样子,所以历史面板里这一轮的**撤回**会把文件和场景一起退回。 |+| 不可逆 | 新建项目、导出构建、`run_editor_command`、探测运行中的游戏 | **一定先问**。事后什么都救不回来。 |所以你给出的许可并不是逐条改动的许可——它就是撤销按钮,而且作用于**整一轮**。一轮跑完且确实改了东西时,记录下面会留一条**撤销 / 保留**的横条;diff --git a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdxindex 68f0563b3..84b9c6eaa 100644--- a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx+++ b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx@@ -9,7 +9,7 @@ Estella 编辑器支持 **Model Context Protocol (MCP)**。任何支持 MCP 的Claude Code、Cursor,或你自己写的代理——都能驱动真实的编辑器:打开或创建项目、打开场景、用与你相同的"创建"菜单目录生成实体、编辑组件字段、在活的引擎 World里验证结果、进入 Play 模式、截图*亲眼看到*它搭出来的东西,并把成品游戏导出-——走的都是 UI 自己的管线,共 65 个工具。+——走的都是 UI 自己的管线,共一百多个工具。<Aside type="tip">代理做的每件事都经过编辑器自己的命令面——创建可撤销、Play 模式不会弄脏编辑@@ -117,11 +117,11 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \| 预制体 | `create_prefab_from_entity`、`edit_prefab` / `exit_prefab_mode`(Prefab Mode)、`apply_prefab`、`revert_prefab`、`unpack_prefab`、`create_prefab_variant` || 零代码行为 | `get_event_bindings` / `set_event_bindings`(给按钮接线)、`add_component` / `remove_component` || 游戏代码 | `read_project_file`、`write_project_file`、`list_project_files` |-| 运行与发布 | `toggle_play` + `get_play_state`、`export_game`(web / desktop / wechat / playable) |+| 运行与发布 | `set_play`(playing / paused / stopped)+ `get_play_state`、`step`、`play_input`、`export_game`(打包对话框列表里的任一目标:web、desktop、wechat、playable、android 等) |典型的代理循环:`open_project` → `open_scene` → `list_entity_templates` →`apply_scene_ops` → `get_diagnostics` → `screenshot` 检查成果 → `save_scene` →-`toggle_play` → 再次 `screenshot` → `export_game`。+`set_play` → 再次 `screenshot` → `export_game`。### 编辑预制体diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex 6ad14d71a..575e6011a 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -391,7 +391,8 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `Animator` 字段 | 类型 | 默认 | 说明 ||---|---|---|---|| `controller` | string | `''` | 一个 `.esanimator` 资产引用(编辑器写入的),或代码里传给 `registerController` 的名字。 |-| `currentState` | string | `''` | 活动状态;嵌套状态机时是 `/` 分隔的路径(从控制器的初始状态种入)。 |+| `avatar` | string | `''` | 一个 `.esavatar` 资产,说明这个骨架如何称呼片段所指名的关节(见[层、遮罩与 IK](#层遮罩与-ik))。 |+| `currentState` | string | `''` | 基础层的活动状态;嵌套状态机时是 `/` 分隔的路径(从控制器的初始状态种入)。 || `enabled` | boolean | `true` | 关掉即冻结状态机。 || `AnimatorController` 方法 | 说明 |@@ -402,8 +403,10 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `resetTrigger(entity, name)` | 在被消费前清除一个 trigger。 || `getFloat(entity, name)` / `getBool(entity, name)` | 读回一个参数。 |-控制器可以同时驱动精灵**和** [Spine](/docs/zh-cn/animation/spine/) 动画,所以一套状态机就能-管一整个角色。+状态的运动可以是精灵片段、[Spine](/docs/zh-cn/animation/spine/) 动画,或+[时间线](/docs/zh-cn/animation/timeline/)片段(蒙皮 3D 骨架就是这样播的),所以一套状态机就能+管一整个角色。转移还可以带 `duration`(秒),从离开的状态交叉淡入进入的状态;只有两端运动都能被采样时才生效,+精灵图集是直接切换,因为两张图之间没有「半途」可言。参数有三种类型(`AnimatorParamType`):`'float'`、`'bool'`、`'trigger'`。条件用`gt` / `lt` / `eq` / `neq` 比较数值(带 `value`),用 `true` / `false` 测试 bool,@@ -417,9 +420,8 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)*一维 blend:float 参数挑出「阈值 ≤ 它」中最高的那个片段——这里随 `speed` 上升在 `idle` / `walk` / `run` 之间切换,彼此不做过渡。*状态可以携带一个 1D **blend** 来代替单个片段:由一个 float 参数在-`AnimatorBlendThreshold` 档位之间做选择。因为精灵通道一次只播一个片段,这里的混合是-按阈值的*选择*——`value` 不超过参数值的档位中取最大者(低于所有档位时播第一个)——-而不是加权姿态混合。每个档位是 `{ value, clip, speed?, loop? }`;档位级的+`AnimatorBlendThreshold` 档位之间做选择。对精灵片段(一次只播一个)来说,这是+按阈值的*选择*——`value` 不超过参数值的档位中取最大者(低于所有档位时播第一个)。每个档位是 `{ value, clip, speed?, loop? }`;档位级的`speed` / `loop` 覆盖状态自己的。选择每帧重算,所以 `speed` 参数上升时idle→walk→run 无需任何转移:@@ -450,10 +452,18 @@ const setup = defineSystem([Res(AnimatorController)], (anim) => {纯函数 `selectBlendClip(blend, value)` 返回某个值会选中的档位——方便做工具或测试。+对可采样的运动(驱动骨架或任意组件字段的时间线片段),blend 不再「挑一个」,而是把参数两侧的档位**混合**起来,+并且按共同的*相位*而不是共同的秒数对齐,所以 2 秒的待机和 0.6 秒的跑步脚步不会打滑。写法是用 `motion`+代替单一类型字段:`{ kind: 'blend1d', parameter, thresholds: [{ value, motion }] }`,档位的运动本身还可以是另一个 blend。+会转向的移动用 `blend2d`,把档位放在两个参数张成的平面上——+`{ kind: 'blend2d', parameterX, parameterY, points: [{ position: { x, y }, motion }] }`——+并混合采样点周围的各点(采样点正落在某个片段上就只播它;落在凸包外则取最近的边)。状态检查器的类型选择里有+无 / 片段 / 1D 混合 / 2D 混合,不必手改文件。+骨骼角色的状态可以改为携带 `spine` 运动(`AnimatorSpineMotion`,`{ animation, loop? }`):进入时控制器设置该 [Spine](/docs/zh-cn/animation/spine/)动画(`loop` 默认 `true`),轨道播放与混合交给 Spine 运行时——完全不碰-`SpriteAnimator`。状态互斥:`clip`、`blend`、`spine`、`stateMachine` 四者取一。+`SpriteAnimator`。状态互斥:`clip`、`blend`、`spine`、`motion`(通用写法:任一已注册类型 `sprite` / `timeline`,或它们之上的 `blend1d` / `blend2d`)、`stateMachine` 五者取一。### 子状态机@@ -522,6 +532,40 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());| `evaluateAnimatorPath(def, path, params, triggers, clipFinished?)` | 对路径做一步纯求值 → `{ nextPath, consumedTriggers }`。 || `STATE_PATH_SEP` | 路径分隔符,`'/'`。 |+### 层、遮罩与 IK++++*第三人称示例的动画控制器。右上角的**图层**叠在基础层之上,各有自己的权重和遮罩;下面的**参数**驱动状态转移。*++++一台状态机只能说角色在跑或者在挥手,不能同时说两件事。控制器可以在基础状态机之上带**层**:每一层是自己的状态机,+有自己的时钟、转移和活动状态,实体最终是整叠层合成后的结果,只写一次。层按顺序合成,调换两层就是另一个角色。++```jsonc+// 在 .esanimator 里,与 "states" 并列+"layers": [{+ "name": "Upper body",+ "weight": 1, // 0 不动下面的层,1 表示本层完整生效+ "blend": "override", // 或 "additive":叠加片段相对其首帧的偏离+ "mask": { "paths": ["Spine"] }, // 本层可写的关节(按 childPath),每条代表它下面的整棵子树+ "initialState": "Rest",+ "states": [ /* ... */ ]+}]+```++`mask` 就是一组片段本来用来指名所动画对象的 `childPath`。没有 mask 就写整个骨架;`paths` 为空数组则什么也不写。+根运动只属于基础层,触发器是所有层都会被告知的同一个事件。编辑器里用层栏切换画布编辑哪一台状态机。++控制器的 `ik` 列表让姿态去够片段不知道的东西:`two-bone` 把肢体末端(`tip`,按 `childPath` 指名的关节)放到 `target` 上,+可选 `pole` 决定朝哪边弯;`look-at` 让某个关节自己的 `axis` 转向目标。两者都有 `weight`,并可由一个 float `parameter` 淡入淡出。+IK 属于控制器而不是某一层,在层叠加的结果上只运行一次。++**Avatar。** 片段按导出者起的名字指名关节,所以两个人绑的两个角色互相用不了对方的片段。`.esavatar`(新建菜单)是骨架自己对这些名字的翻译,+并记录它的绑定姿态;控制器的 `avatar` 指明它的片段是对着哪个 avatar 做的,`Animator` 的 `avatar` 字段填这个骨架自己的。+这样一个控制器就能驱动骨骼名字不同、绑定姿态不同的角色,根运动也会按各自骨架应走的距离缩放。+### 动画事件剪辑可以给自己内部的时刻命名。`.estimeline` 里的 `customEvent` 轨道携带diff --git a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx b/docs/astro/src/content/docs/zh-cn/animation/spine.mdxindex 576b8c3f8..4447ad14e 100644--- a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/spine.mdx@@ -35,8 +35,8 @@ Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画:骨骼、网`animation` 和 `skin` 字段会变成该骨骼实际动画与皮肤的下拉列表。<Aside type="note">- 骨骼选择器只列出 **`.skel`** 文件。**`.json`** 骨骼同样能加载——从内容浏览器- **拖拽**到槽位上即可。+ 骨骼槽位同时接受 **`.skel`** 文件和 **`.json`** 骨骼(`.json` 没有自己的扩展名来表明身份,+ 编辑器靠文件内部的标记认出它,它会和 `.skel` 一起出现在选择器里)。从内容浏览器**拖拽**到槽位上也行。</Aside>## 图集diff --git a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdxindex 7a1483661..f1cf23d9a 100644--- a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx@@ -32,7 +32,7 @@ const attach = defineSystem([Commands()], (cmds) => {| `timeline` | asset | `''` | 时间轴资源(`.estimeline`)。 || `playing` | boolean | `false` | 播放旗标——拉起播放,放下暂停。对已播完的片段拉起 = 从头重播。 || `speed` | number | `1` | 播放速率倍率。 |-| `wrapMode` | string | `'once'` | `'once'`、`'loop'` 或 `'pingPong'`(驼峰写法——其它值会静默地只播一次)。 |+| `wrapMode` | string | `''` | 覆盖片段自带的循环模式:`'once'`、`'loop'` 或 `'pingPong'`(驼峰写法)。留空——以及任何其它字符串,那算笔误——则沿用片段自己声明的模式。 || `finished` | boolean | `false` | `'once'` 片段播完时闩为 true;下次播放时清除。运行时只读。 |组件旗标**就是**播放控制本身:引擎每帧把它们调和进内部时钟,所以任何翻动@@ -183,8 +183,8 @@ const attach = defineSystem([Commands(), Res(Timeline)], (cmds, timeline) => {### 循环模式-播放采用**播放器组件**的 `wrapMode` 字符串;数值型 `WrapMode` 常量用在资产和纯求值-API 里。映射与行为:+片段自己声明数值型 `WrapMode`(在资产和纯求值 API 里);**播放器组件**的 `wrapMode` 字符串只要指了名,+就覆盖它。映射与行为:| `WrapMode` | 播放器字符串 | 越过终点后的行为 ||---|---|---|diff --git a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdxindex 543fc2e4d..a924c49de 100644--- a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx@@ -6,7 +6,7 @@ description: 音频完整指南——音效、音乐、播放句柄、AudioSourcimport { Aside } from '@astrojs/starlight/components';Estella 的音频通过 `Audio` 资源播放一次性音效和循环音乐,用句柄控制单个声音,用总线层级-平衡混音,并用空间音频把声音定位到世界里。它在浏览器上跑 Web Audio 后端,在微信上跑原生后端。+平衡混音,并用空间音频把声音定位到世界里。它在浏览器上跑 Web Audio 后端,在微信等小游戏宿主上每个声音一个播放器,在 iOS 和 Android 应用里用宿主的原生音频引擎(miniaudio)。## 工作原理@@ -104,6 +104,12 @@ if (voice) {### 制作音效事件+++*一个有三个变体的声音事件。每行有波形和权重(占比=权重除以权重之和),**触发试听**按该事件自己的规则在监听器位置播放。*+++在内容浏览器选择 **新建 → 创建音效事件**,或选中音频资源后从右键菜单创建。双击 `.esaudioevent` 打开专用编辑器。将音频拖到空事件面板,会在第一条音频旁创建事件;拖到已打开的事件则添加变体。@@ -182,6 +188,8 @@ shot.onEnd = () => { /* the sound finished */ };| `volume` | number | `1` | 音量,0..1。 || `pitch` | number | `1` | 播放速度 / 音调。 || `loop` | boolean | `false` | 循环片段。 |+| `playing` | boolean | `false` | 播放标志:升起即播放,放下即停止。非循环片段播完时引擎会把它放下。 |+| `finished` | boolean | `false` | 运行时只读:片段已播完;再次升起 `playing` 会重新播放。 || `playOnAwake` | boolean | `false` | 实体启用时自动开始。 || `spatial` | boolean | `false` | 按与监听器的距离衰减。 || `minDistance` | number | `100` | 在此距离内音量为满。 |@@ -206,7 +214,7 @@ audio.muteBus('music', true);用 `AudioSource.bus` 字段把声音路由到某个总线,或让 `playSFX` 默认走 `sfx`。音量设置器有`setMasterVolume`(全局滑条)和 `setMusicVolume` / `setSFXVolume` / `setUIVolume`。`voice`-总线能路由声音但没有音量设置器——用 `muteBus('voice', …)` 开关它。+总线能路由声音,但没有专门命名的设置器:用 `setBusVolume('voice', v)`(它能按名字指到任何总线)设音量,或用 `muteBus('voice', …)` 开关它。### 总线效果与自动闪避(ducking)@@ -244,10 +252,14 @@ audio.setBusDucking('music', null); // 移除`Bitrate` 控制打包时的 WAV → MP3 转码(在打包对话框勾选**压缩音频**)。已压缩格式原样通过。MP3 有少量编码器延迟——需要无缝循环的素材请关闭 `Compress`。+**加载方式(Load Type)** 决定这个片段在 Web 上怎么持有:*自动*把 30 秒及以上的片段按压缩文件流式播放、较短的则解码,+*加载时解压*总是解码(起播即时,三分钟的曲子约占 69 MB),*流式*总是流式播放。流式片段几乎不占内存,走同样的总线、音量与淡入淡出,+但放弃了采样精确的循环点,以及同一片段的第二个并发声音。这个选择会写进导出游戏的音频设置,所以编辑器 Play、导出和试玩广告流式播放的是同一批片段。+## 门面之下`Audio` 是一个门面,其后是 Web Audio 后端组装的三个导出类——`AudioMixer`、`AudioBus`、-`AudioPool`。游戏里很少直接构造它们(微信后端上它们根本不存在,这正是总线 API 在那里+`AudioPool`。游戏里很少直接构造它们(微信和原生后端上它们根本不存在,这正是总线 API 在那里降级为空操作的原因),但它们公开导出是为了两件实事:**内建四条之外的自定义总线**,以及**独立音频管线**——试听工具、自定义 `PlatformAudioBackend`、测试——建在你自己的`AudioContext` 上。@@ -350,15 +362,15 @@ const setupSpatial = defineSystem([Commands()], (cmds) => {`AudioListener` 只有一个字段 `enabled`(默认 `true`)——场景里保持恰好一个启用的监听器。-Estella 的空间管线是诚实的 2D:每帧,音频系统取声源和监听器的世界位置,算出距离,用-`volume × 衰减` 加上**沿 x 轴的立体声声像**(`(sourceX − listenerX) / maxDistance`,-钳制到 ±1)驱动正在播放的句柄。没有 HRTF、多普勒或遮挡。空间声源在没有启用监听器时播放,+空间音频是三维的:每帧,音频系统取声源和监听器的世界位置,按三个轴算出距离,用+`volume × 衰减` 加上**沿监听器自己右方向的立体声声像**(`dot(source − listener, right) / maxDistance`,+钳制到 ±1;没转过的监听器的右方向就是世界 +X,监听器转向后听到的世界也跟着转)驱动正在播放的句柄。没有 HRTF、多普勒或遮挡。空间声源在没有启用监听器时播放,会警告一次并从世界原点量距离。曲线数学以纯函数导出,供工具和测试使用——`calculateAttenuation(distance, config)`配 `SpatialAudioConfig`(`model`、`refDistance`、`maxDistance`、`rolloff`——系统用`AudioSource.minDistance`/`maxDistance`/`rolloff` 填充它),以及-`calculatePanning(sourceX, sourceY, listenerX, listenerY, maxDistance)`:+`calculatePanning(source, listener, right, maxDistance)`(前三个是 `{ x, y, z }`):```typescriptimport { calculateAttenuation, calculatePanning, AttenuationModel } from 'esengine';@@ -366,7 +378,9 @@ import { calculateAttenuation, calculatePanning, AttenuationModel } from 'esengiconst gain = calculateAttenuation(250, {model: AttenuationModel.Inverse, refDistance: 100, maxDistance: 1000, rolloff: 1,}); // 0.4 — refDistance / distance-const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right+const pan = calculatePanning(+ { x: 600, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }, 1000,+); // 0.6 — to the right```### 音效事件源diff --git a/docs/astro/src/content/docs/zh-cn/assets/localization.mdx b/docs/astro/src/content/docs/zh-cn/assets/localization.mdxindex 62fc6b36a..714d07a9d 100644--- a/docs/astro/src/content/docs/zh-cn/assets/localization.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/localization.mdx@@ -60,6 +60,7 @@ i18n.t('apples', { count: 3 }); // "3 apples"| `t(key, params?)` | 查找 + 插值一个字符串。 || `setLocale(locale)` | 设置当前 locale。 || `setFallbackLocale(locale)` | 设置 key 缺失时使用的 locale。 |+| `setPseudoLocalization(options \| null)` | 可选的长度压力预览(`expansion`、`accents`);`null` 恢复正常翻译。 || `setPluralSelector(locale, selector)` | 为某 locale 设自定义复数规则。 || `availableLocales()` | 列出已注册的 locale。 || `has(key)` | key 是否存在于当前/回退 locale。 |@@ -93,6 +94,13 @@ i18n.t('apples', { count: 3 }); // "3 apples"[下面的 Text 绑定](#把-ui-text-绑到-key)全自动加载。导出 cook 永远会把 `.eslocale`打进包里——它们按 key 加载,可达性分析看不见它们,所以强制收入。+双击 `.eslocale` 会打开**字符串表**编辑器,把项目的所有语言并排显示:每个 key 一行、每张表一列,未翻译的格子有标记,+带筛选,可以添加和删除 key(每次编辑立即写入对应语言的文件)。它能**导入** Excel(`.xlsx`)、CSV 或 XLIFF(`.xlf`)文件,+按 key 合并进各张表;也能把所有语言**导出**成一张 Excel 或 CSV 表,或 XLIFF 1.2,并先列出发现的问题;复数条目在检查器里编辑。++想看更长的语言排版会不会放不下,可以用 `i18n.setPseudoLocalization({ expansion: 0.35, accents: true })`+(`@experimental`):它把每条译文拉长并加上重音符号,同时保留占位符、富文本标签和换行;`setPseudoLocalization(null)` 恢复真实文本。+## 把 UI Text 绑到 key设置 `Text.i18nKey`(编辑器细节面板里的 **I18n Key** 下拉,列出项目全部表里的 key 及其diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdxindex 7514c1029..b50b34d45 100644--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx@@ -201,6 +201,15 @@ API,它就开始播。`LINEAR`、`STEP`、`CUBICSPLINE` 都会带过来,含切线。+`weights` 通道(模型 morph target 的动画)也会带过来:它变成该节点所绘制的每个 primitive 一条轨道、每个 target 一个通道,+这样剪辑就能驱动 [Morph target](#morph-target) 一节说的 `MeshMorph` 权重。++## 灯光与相机++glTF 的 `KHR_lights_punctual` 灯光和相机,以及 FBX 的点光、方向光、聚光灯和相机,会变成 prefab 里对应节点上的 `Light` 和+`Camera` 组件,并像引擎自己的那样转成朝向 -Z。颜色、锥角、照射范围、视场角与裁剪面都会带过来;强度按文件所写原样带入,+因为引擎的强度没有光度学单位。导入的相机从不是活动相机,所以模型夺不走场景自己相机的画面。+## 蒙皮绑定好的模型会带着绑定进来:mesh 携带它的骨骼索引、权重和绑定姿态,prefab 给实体挂一个@@ -272,17 +281,15 @@ Physical、Blender 的 Principled 最终都落到[材质](#材质)那一节列| 不导入 | 为什么 ||---|---|-| `weights` 动画通道 | 形状本身会被导入(见 [Morph target](#morph-target));驱动它们的剪辑还没有被带过来。 |-| 第二套 UV(`TEXCOORD_1`)、`KHR_texture_transform`、FBX 的 uv transform | UV 按作者写的原样使用。 |+| 材质贴图要求用 `TEXCOORD_1`、带偏移/缩放/旋转的 `KHR_texture_transform`、FBX 的 uv transform | 材质按作者写的原样读第一套 UV。(mesh 本身保留第二套 UV,光照贴图或材质的 `v_texCoord1` 可以读它。) || 非三角形 primitive(`mode` ≠ 4) | 渲染器画的是三角形列表。 || `normalTexture.scale` | 法线贴图按全强度应用。 || 着色层的贴图(`clearcoatTexture`、`sheenColorTexture`、`anisotropyTexture` 等)、`specularColorFactor`、`attenuationDistance` | 每一层对整个材质是一个常量;系数保留,贴图只做报告。见[着色层](/docs/zh-cn/graphics/materials/#着色层)。 |-| FBX 里的相机与灯光 | 场景的相机与灯光属于场景,不属于模型。 |+| 面光与体积光 | 在导入提示里点名并跳过。(点光、方向光、聚光灯以及相机**会**导入:见[灯光与相机](#灯光与相机)。) || FBX 分离的金属度/粗糙度贴图、FBX 的不透明度贴图 | 见 [FBX](#fbx)。 |## 值得知道的限制-- 点光的距离在 XY 平面上算(2D 光照模型固有);**方向光是精确的**,而那通常正是着色一个模型需要的。- 自己写了 vertex stage 的材质**不会**被重定向到 mesh 几何上 —— 那样它会无视 per-object transform。只写 fragment 的材质两边都能用。- 没有 `NORMAL` 属性的几何仍然会受光,落在 2D 表面那个常量法线上 —— 平,但不是黑的。diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxindex fa5584484..e73b78be4 100644--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx@@ -147,7 +147,7 @@ const { failed } = await assets.preload(打包对话框的**资源压缩**开关只选择遵循还是全部跳过这些设置。- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。Web/桌面默认开启。-- **自动图集** —— 把零散的 PNG 放进 `<name>.atlas/` 文件夹,烘焙时会把它们打包成图集页+- **自动图集** —— 烘焙的可选项(构建不要求就不开):把零散的 PNG 放进 `<name>.atlas/` 文件夹,烘焙时会把它们打包成图集页(帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。diff --git a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx b/docs/astro/src/content/docs/zh-cn/assets/textures.mdxindex 25325b468..8af1497fa 100644--- a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx@@ -110,10 +110,11 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而| **Max Size** | `2048` | cook 时的降采样上限(2 的幂)。最长边超过它的源图会被 box 滤波缩下来;更小的源图原样保留。 || **Compression** | `Auto` | **GPU compressed**(GPU 压缩)发布 KTX2(Basis Universal),在显存里保持压缩——约为解码后的四分之一——并按设备转码。**Original image**(原图)按原文件发布:画质无损,平涂美术下载体积小得多,但在 GPU 上是完整解码的大小。**Auto**(自动)对网格用到的贴图(直接引用或经由材质)用 GPU 压缩,对精灵和 UI 用原图。构建严格按这一项执行,不会因为哪个文件更小就擅自替换。 || **Compress Format** | `uastc` | `uastc` —— 质量高、体积大。`etc1s` —— 小得多、质量低(适合照片类/低频美术)。仅在贴图使用 GPU 压缩时生效。 |+| **Mip Maps** | 开 | 保留一串逐级减半的副本,让画得很小的贴图采样的是滤波后的图而不是闪烁;多占三分之一内存。始终以原尺寸绘制的像素美术和 UI 可以关掉。 || **Filter** | `linear` | 采样过滤。`nearest` 保持像素锐利;`linear` 平滑。 || **Wrap** | `repeat` | `[0,1]` 之外的 UV 如何寻址:`repeat`、`clamp`、`mirror`。 |-| **Premultiply Alpha** | `false` | 导入时把 RGB 乘上 alpha。 || **sRGB Color** | `true` | 图片存的是 sRGB 编码的颜色(albedo、UI)。法线图、遮罩这类本来就是线性的数据要关掉。仅在项目按线性色渲染时有意义。 |+| **Mip Coverage Cutoff** | `0` | 用于镂空(树叶、草、栅栏):材质测试的 alpha 阈值。每一级 mip 都保留与完整图像相同比例的高于阈值的像素,镂空就不会随距离变稀。`0` = 关;对 UASTC 压缩贴图生效。 || **9-Slice Border** | `0,0,0,0` | 左/右/上/下边框,单位是**纹理像素**:图片的角在哪里结束。在这里授权一次,每个设成 Sliced 的 `UIVisual` 都继承。 |<Aside type="tip">diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdxindex ac52eeb86..2d4894d63 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx@@ -60,16 +60,16 @@ await app.run();`RenderPipeline`。2. **UI**:`uiPlugins`——组合好的 UI 管线(布局、文本、文本输入、遮罩、渲染排序、交互、拖拽、焦点、安全区)。-3. **基础内容**:`timerPlugin`、`lifecyclePlugin`、`animationPlugin`、- `audioPlugin`、`videoPlugin`、`particlePlugin`、`trailPlugin`、- `mesh2dPlugin`、`tilemapPlugin`、`postProcessPlugin`、`timelinePlugin`、- `perceptionPlugin`、`fsmPlugin`、`btPlugin`、`navPlugin`、- `replicationPlugin`。-4. **Spine**:一个 `SpinePlugin` 实例(按需从 `app.sideModules` 拉取对应版本- 的 wasm 运行时——场景不用 Spine 就什么也不加载)。+3. **基础内容**:诊断、计时器、速度、生命周期、动画、音频、视频、粒子、拖尾、弹簧骨骼、网格渲染、+ 静态合批、后处理、事件绑定与服务这些插件。+4. **随导入安装的可选子系统**:导入某个子路径——如 `esengine/tilemap`、`esengine/timeline`、+ `esengine/ai`(感知、FSM、BT 与导航)、`esengine/logic`(脚本图)、`esengine/gameplay`、+ `esengine/replication`、`esengine/spine`、`esengine/dragonbones`,以及地形、植被、水体、世界生成这几个子路径——+ 就会注册该子系统的插件,工厂把已注册的都加上。游戏从不导入某个子路径,就既不安装也不携带它的子系统。+ Spine 按需从 `app.sideModules` 拉取对应版本的 wasm 运行时——场景不用 Spine 就什么也不加载。5. **你的 `plugins`**,按给出顺序。-物理**不在**默认集合里:`Physics2DPlugin` 需要物理 wasm 模块。发行运行时会在项目+物理**不在**默认集合里:`Physics2DPlugin`(3D 世界是 `Physics3DPlugin`)需要各自的 wasm 模块。发行运行时会在项目声明了物理、或场景含有物理组件时,自动从侧模块 host 获取 `'physics'` 并安装插件;手动组装时请自己构造 `Physics2DPlugin`(它和 `loadPhysicsModule` 都从 `esengine`导出;完整 API 在 `esengine/physics` 子路径上)。@@ -96,13 +96,12 @@ stop();| `plugins` | `Plugin[]` | 你的玩法插件,追加在基础集合之后。 || `sideModules` | `SideModuleHost` | 可选原生模块获取器(服务器上的物理)。 |-包含:`assetPlugin`、`prefabsPlugin`、`sceneManagerPlugin`、`timerPlugin`、-`lifecyclePlugin`、`audioPlugin`(无音频设备的宿主上静音),以及游戏 AI /-复制集合(`perceptionPlugin`、`fsmPlugin`、`btPlugin`、`navPlugin`、-`replicationPlugin`)。+包含:`assetPlugin`、`prefabsPlugin`、`sceneManagerPlugin`,计时器、速度、生命周期、事件绑定与服务这些插件,+`audioPlugin`(无音频设备的宿主上静音),以及项目导入过的每个可选子系统(游戏 AI、脚本图、复制 ……)——+与上面同样是随导入决定的那一组。不包含——一切*为了被看见*而存在的东西:`corePlugin`(它接线的渲染 facade 只在-`initRenderer()` 之后才存在)、UI、粒子、tilemap 渲染、后处理、时间轴、Spine、+`initRenderer()` 之后才存在)、UI、粒子、tilemap 渲染、后处理、Spine、输入。`runHeadless(app, { fps? })` 用挂钟 `setInterval` 驱动应用(服务器上没有@@ -311,7 +310,7 @@ for (const s of app.subsystems.getStatuses()) {## 侧模块可选的原生子系统以**独立 wasm 模块**按需加载,让基础引擎下载体积保持小:物理-(Box2D)、逐版本的 Spine 运行时、Basis Universal 纹理转码器、软件视频解码器。+(Box2D)、Jolt 3D 物理世界、逐版本的 Spine 运行时、DragonBones、Basis Universal 纹理转码器、软件视频解码器。每个都是一对 emscripten 产物——`<file>.js` 胶水加 `<file>.wasm`——统一经由`SideModuleHost` 获取;各 realm 之间只有*传输方式*不同。@@ -320,11 +319,13 @@ for (const s of app.subsystems.getStatuses()) {| `SideModuleId` | 产物 | 内容 ||---|---|---|| `'physics'` | `physics.js` / `.wasm` | Box2D 物理。 |-| `'spine:3.8'` / `'spine:4.1'` / `'spine:4.2'` | `spine38` / `spine41` / `spine42` 的 `.js`/`.wasm` | 每个骨骼格式版本一份 Spine 运行时。 |+| `'physics3d'` | `physics3d.js` / `.wasm` | Jolt 3D 物理。 |+| `'spine:2.1'` / `'3.8'` / `'4.1'` / `'4.2'` / `'4.3'` | `spine21` … `spine43` 的 `.js`/`.wasm` | 每个骨骼格式版本一份 Spine 运行时。 |+| `'dragonbones'` | `dragonbones.js` / `.wasm` | DragonBones 运行时(只有一项:格式已冻结)。 || `'basis'` | `basis.js` / `.wasm` | Basis Universal KTX2 转码器(压缩纹理)。 || `'videodec'` | `videodec.js` / `.wasm` | MPEG-1 软件视频解码器。 |-`SPINE_VERSIONS` 是只读列表 `['3.8', '4.1', '4.2']`,`spineModuleId(version)`+`SPINE_VERSIONS` 是只读列表 `['2.1', '3.8', '4.1', '4.2', '4.3']`,`spineModuleId(version)`构造对应的 id。host 用 `acquire(id)` 应答,返回已实例化模块的 promise(按 id 缓存,失败也以@@ -333,15 +334,15 @@ host 用 `acquire(id)` 应答,返回已实例化模块的 promise(按 id 缓存,- **`createFetchSideModuleHost(baseUrl)`**——从基址 fetch 胶水与 wasm(`wasmBaseUrl` 构建的就是它);编辑器、Web 与桌面使用。- **`createEmbeddedSideModuleHost(...)`**——模块以 base64 内联(Playable 广告)。-- **`createWeChatSideModuleHost(...)`**——微信的预编译模块工厂。+- **`createMiniGameSideModuleHost(...)`**(同时以 `createWeChatSideModuleHost` 导出)——小游戏宿主的预编译模块工厂。你通常永远不用自己调 `acquire`——设置好 `app.sideModules`(经 `wasmBaseUrl`或 `sideModules`),Spine 插件和物理安装会在需要时从中拉取。<Aside type="note">- 主 `esengine` barrel 恰好镜像了物理/Spine 的**接线**层——`Physics2DPlugin`、- `Physics2DEvents`、`Physics`、`loadPhysicsModule`、`SpinePlugin`、- `SpineEvents`、`Spine`——宿主无需子路径导入即可注册这些插件。完整 API 在+ 主 `esengine` barrel 镜像了物理/Spine 的**接线**层——`Physics2DPlugin`、+ `Physics2DEvents`、`Physics2D`、`loadPhysicsModule`、`Physics3DPlugin`、`Physics3D`、+ `SpinePlugin`、`SpineEvents`、`Spine`——宿主无需子路径导入即可注册这些插件。完整 API 在`esengine/physics` 与 `esengine/spine` 子路径上。见[物理](/docs/zh-cn/gameplay/physics/)与 [Spine](/docs/zh-cn/animation/spine/)。</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdxindex c814a725a..462bc2898 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx@@ -76,7 +76,7 @@ const Turret = defineComponent('Turret', {## 内置组件-引擎注册了 77 个组件,与你自己的组件一起查询——`Transform`、`Sprite`、+引擎注册了 150 多个组件,与你自己的组件一起查询——`Transform`、`Sprite`、`ShapeRenderer`、`Camera`、`Light`、`ParticleEmitter`、`SpineAnimation`、`TilemapLayer`、UI 组件族、物理碰撞体等等。每个子系统指南讲它自己那一批;[组件参考](/docs/zh-cn/reference/components/core/)则逐个列出全部组件的字段、类型与diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdxindex 9dd7c85ed..8f01f88cc 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx@@ -27,7 +27,7 @@ defineSystem([Res(Audio)], (audio) => {| 输入 | `Res(Input)` | [输入](/docs/zh-cn/scripting/input/) || 音频 | `Res(Audio)` | [音频](/docs/zh-cn/assets/audio/) || 资源 | `Res(Assets)` | [资源](/docs/zh-cn/assets/overview/) |-| 瓦片地图 | `Res(Tilemaps)` | [瓦片地图](/docs/zh-cn/world/tilemaps/) |+| 瓦片地图 | `Res(Tilemaps)` —— 来自 `esengine/tilemap` | [瓦片地图](/docs/zh-cn/world/tilemaps/) || 粒子 | `Res(Particle)` | [粒子](/docs/zh-cn/world/particles/) || 后处理 | `Res(PostProcess)` | [后处理](/docs/zh-cn/graphics/post-processing/) || 场景 | `Res(SceneManager)` | [场景](/docs/zh-cn/world/scenes/) |@@ -37,15 +37,17 @@ defineSystem([Res(Audio)], (audio) => {| 计时器 | `Res(TimerRes)` | [脚本](/docs/zh-cn/scripting/overview/) || 时间轴 | `Res(Timeline)` | [时间轴](/docs/zh-cn/animation/timeline/) || 预制体 | `Res(Prefabs)` | [预制体](/docs/zh-cn/world/prefabs/) |-| 导航 / AI | `Res(Nav)` | [游戏 AI](/docs/zh-cn/gameplay/ai/overview/) |+| 导航 / AI | `Res(Nav)` —— 来自 `esengine/ai` | [游戏 AI](/docs/zh-cn/gameplay/ai/overview/) || 本地化 | `Res(Localization)` | [本地化](/docs/zh-cn/assets/localization/) || 相机视图 | `Res(CameraView)` | [相机](/docs/zh-cn/graphics/camera/) || UI 事件 | `Res(UIEvents)` | [UI](/docs/zh-cn/ui/overview/) |-| 物理 | `Res(Physics)` —— 来自 `esengine/physics` | [物理](/docs/zh-cn/gameplay/physics/) |+| 2D 物理 | `Res(Physics2D)` —— 来自 `esengine/physics` | [物理](/docs/zh-cn/gameplay/physics/) |+| 3D 物理 | `Res(Physics3D)` —— 来自 `esengine/physics3d` | [3D 物理](/docs/zh-cn/gameplay/physics-3d/) || Spine | `Res(Spine)` —— 来自 `esengine/spine` | [Spine](/docs/zh-cn/animation/spine/) |-物理和 Spine 是**可选 side-module**,按需加载,因此它们的 API 放在子路径上以保持基础-包精简;其余都在主 `esengine` 包里。上表的基础子系统都随标准 App 附带——无需接线。+物理(2D 与 3D)和 Spine 是**可选 side-module**,按需加载;瓦片地图和 AI 是可选的子路径包。+它们的 API 放在子路径上以保持基础包精简;其余都在主 `esengine` 包里。编辑器和 Web 运行时会替项目+装上用到的插件——无需接线;只有从裸的 `new App()` 起步时才需要自己添加。有些子系统还按同一范式发布**事件资源**——内容是本帧事件、当帧读取的资源:`Res(Physics2DEvents)`(碰撞接触)、`Res(SpineEvents)`(动画事件)、diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdxindex 63f6bb458..ce278fdf4 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx@@ -57,8 +57,10 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {- **世界空间 Y 轴向上**:`+Y` 朝上,`+X` 朝右,角度 `0` 指向 `+X`,正角度逆时针(`Math.atan2(dy, dx)` 可直接得到指向目标的角度)。-- **`position.z` 是绘制顺序,不是透视**:2D 渲染先按各渲染器的排序层 `layer` 粗排;- 同一层内用 `z` 做精细排序(俯视角深度请用+- **`position.z` 在 2D 场景里是绘制顺序,在 3D 场景里是真正的深度轴**。3D 场景+ (网格、透视相机、[3D 物理](/docs/zh-cn/gameplay/physics-3d/))里坐标轴仍是 Y 向上,+ `z` 就是普通空间轴:相机与灯光朝 `-Z` 看,地面是 XZ 平面。对 2D 精灵,渲染先按各渲染器的排序层+ `layer` 粗排;同一层内用 `z` 做精细排序(俯视角深度请用[y 排序层](/docs/zh-cn/graphics/sprites/#绘制顺序与排序层))。它不会使精灵产生透视缩放。- **屏幕空间 Y 轴向下**:指针坐标(`Input.mouseX/mouseY`、UI 命中测试)是从画布diff --git a/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdx b/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdxindex 62f189f65..be59ab038 100644--- a/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdx@@ -5,7 +5,8 @@ description: "双击资产打开的各个文档编辑器:Sequencer、瓦片地在内容浏览器里双击一个资产,即可在文档标签里打开它的编辑器。- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/animation/timeline/)。-- **瓦片地图模式** — 内容浏览器旁的**瓦片调色板**面板,视口工具栏里有**画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,+- **瓦片地图模式** — 内容浏览器旁的**瓦片调色板**面板,视口工具栏里有**画笔、擦除、矩形、椭圆、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,+ 还有可保存的**图章**、能在整层或选区内把一种图块 ID 换成另一种的**批量替换图块…**命令,外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个**随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是**正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/world/tilemaps/)。diff --git a/docs/astro/src/content/docs/zh-cn/editor/content-browser.mdx b/docs/astro/src/content/docs/zh-cn/editor/content-browser.mdxindex 3e36c265e..9cae302d8 100644--- a/docs/astro/src/content/docs/zh-cn/editor/content-browser.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/content-browser.mdx@@ -4,9 +4,18 @@ description: "项目的资产浏览器——新建与导入资产、按资产类---内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:-- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、**新建脚本…**、新建文件夹。-- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、- **创建材质实例**(从材质)。+- 新建场景、新建预制体、**新建脚本…**、新建动画、新建动画控制器、新建输入映射、新建本地化表、+ 新建六面环境(六张图)、新建材质、新建材质图、新建材质子图、**新建着色器**、新建状态机、+ 新建行为树、新建脚本图、新建骨架映射、创建音效事件、新建世界规则、新建地形层、新建文件夹——+ 插件添加的资产类型也会出现在这里。+- 按资产类型的上下文动作:**创建瓦片集**和**创建精灵动画**(从纹理)、**创建瓦片地图**(从瓦片集)、+ **创建动画精灵**(从动画片段)、**创建材质实例**(从材质);场景还有**设为启动场景**,+ 导入的资产有**重新导入**。++++*内容浏览器的**新建**菜单。*+**新建脚本…** 是唯一一个不止写一个文件的:没人 import 的模块永远不会被打包,它的组件也永远进不了 Add Component,所以对话框还会在项目的脚本入口里加上够到它的那一行——加到diff --git a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx b/docs/astro/src/content/docs/zh-cn/editor/overview.mdxindex 44fc2b9cd..9341cffb1 100644--- a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/overview.mdx@@ -15,8 +15,9 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可- **最近** — 重新打开你做过的项目,带搜索和网格/列表视图。- **新建项目** — 选一个模板,起名字、选位置,创建。模板分两组:**Starters**- (**Blank** 模板——只有一个相机的空场景)和 **Examples**(随附的示例项目,- 可直接探索和修改)。+ (**Blank**——只有一个相机的空场景——以及可直接运行的起步项目,如 2D 平台跳跃、+ 俯视角、像素 RPG、UI 游戏、3D 起步、在线 3D 世界、试玩广告和微信小游戏)和+ **Examples**(随附的示例项目,可直接探索和修改)。一个项目就是磁盘上的一个文件夹。编辑器关心的几块:@@ -40,7 +41,7 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可从外到内的默认布局:- **活动栏(Activity Bar)** — 最左侧的图标竖条:四种**编辑模式**(瓦片地图 / UI / 世界 / 场景)、**面板**菜单(显示或隐藏任何停靠面板)、内容抽屉、Agent 和设置。-- **菜单栏** — 文件 · 编辑 · 实体 · 视图 · 构建 · 窗口 · 帮助。保存在“文件”里,撤销和重做在“编辑”里。+- **菜单栏** — 文件 · 编辑 · 实体 · 视图 · 构建 · 窗口 · 帮助;插件往“工具”菜单里加了命令后,会多出一个**工具**菜单。保存在“文件”里,撤销和重做在“编辑”里。- **顶栏** — **运行**控制(运行、暂停、重新运行,以及选择游戏在哪里运行的菜单)、**扫码预览**(在手机上运行游戏)、**编译**(编译脚本)。- **视口**(中央) — 实时 WebGL 场景视图,自带工具栏:变换工具、吸附、2D / 3D、屏幕控制、**显示**和 **Gizmo**。- **World Outliner**(右) — 场景的实体层级。diff --git a/docs/astro/src/content/docs/zh-cn/editor/play.mdx b/docs/astro/src/content/docs/zh-cn/editor/play.mdxindex 8844a0e60..aa8b2d8d5 100644--- a/docs/astro/src/content/docs/zh-cn/editor/play.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/play.mdx@@ -7,11 +7,17 @@ description: "在隔离 realm 里于编辑器内运行游戏、运行模式选- **运行**启动游戏;运行时同一个按钮变成**停止**,旁边是**重启**和**暂停/继续**侧键。- 运行模式下拉选择**在视口中运行**(游戏托管在视口上)或**在新窗口运行**(专门的 **Game** 标签),并可切换**运行时最大化视口**——把整个工作区让给运行中的游戏,停止时还原你的布局。+- 同一个下拉还能选**单人**或 **2 / 3 / 4 名玩家(监听服务器)**:多于一人时,第一个 realm 作为监听服务器启动,+ 每多一名玩家就多一个客户端 realm,经编辑器内的复制连到它,联机游戏不用离开编辑器就能试。- 运行中的游戏在视口四周显示一圈柔和的强调色边框(暂停时转琥珀色并压暗画面),而不是盖在游戏上的角标。- 快捷键:**F5** 运行,**Esc** 停止,**F6** 暂停/继续,**Shift+F5** 重启,**F11** 随时最大化/还原视口。因为运行用的是隔离 realm——正是发布你游戏的那套运行时——你在运行里看到的,就是玩家会得到的。+++*运行模式菜单,在**运行**按钮旁。*+## 运行时的大纲层级只有一个,不是两个。游戏运行时大纲显示的是**运行中的世界**,而来自你场景的行会保留它在diff --git a/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdxindex 2ad7729d8..0122e17f7 100644--- a/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx@@ -8,7 +8,8 @@ description: "创建实体、World Outliner,以及 Details 检视器——含它- **实体 → 添加实体**放下一个空白 Transform 实体。- **+ 添加 → 创建实体…** 打开一个生成实体的命令面板:内置类型——**空**、**精灵**、**相机**、**粒子**、- **光**、**瓦片地图**、**Spine**、**音频**、**文本**、**形状**、**网格**、**拖尾**,以及+ **光**、**瓦片地图**、**Spine**、**音频**、**文本**、**位图文本**、**形状**、**网格**、**拖尾**、**DragonBones**、**音效事件**、**太阳光**、+ 内置 3D 基本体(立方体、球体等)、现成的**第三人称角色**和**户外环境**,以及**UI** 控件(画布加控件)——**你自己项目里定义的组件**,还有项目中任意 **`.esprefab` 预制体**。所有创建入口(此菜单、拖拽、自动化接口)都走同一条管线,因此每次生成都是一步撤销。- **在 Outliner 里右键**在上下文里做同样的事,外加文件夹、父子关系和预制体创建。diff --git a/docs/astro/src/content/docs/zh-cn/editor/settings.mdx b/docs/astro/src/content/docs/zh-cn/editor/settings.mdxindex 9335e3318..d507d241a 100644--- a/docs/astro/src/content/docs/zh-cn/editor/settings.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/settings.mdx@@ -33,6 +33,10 @@ description: "编辑器偏好,以及写入 project.esproject 的项目级设置设一次就不再动的设置——屏幕预设、解算器调参、主题的各个颜色、模块开关、你自己的 AI 提供方接口——收在页面的**高级**折叠下,这样页面主体就是大家真正会碰的东西。+++*设置窗口。**编辑器**设置属于你、留在这台机器上;**项目**设置随项目走。*+## 运行时**项目 → 游戏 → 运行时**放的是引擎自己的调参,以前只能从代码里改。项目文件只保存与引擎默认值不同的部分,diff --git a/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdxindex 4aa2d978c..feea78eb8 100644--- a/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx@@ -13,7 +13,7 @@ import { Aside } from '@astrojs/starlight/components';| 打开项目 | `mod + O` || 保存场景 | `mod + S` || 场景另存为 | `mod + shift + S` |-| 撤销 / 重做 | `mod + Z` / `mod + shift + Z` |+| 撤销 / 重做 | `mod + Z` / `mod + shift + Z`(或 `mod + Y`) || 复制(duplicate) | `mod + D` || 拷贝 / 剪切 / 粘贴 | `mod + C` / `mod + X` / `mod + V` || 删除 | `Delete` / `Backspace` |@@ -29,7 +29,7 @@ import { Aside } from '@astrojs/starlight/components';| 打包项目… | `mod + shift + B` || 快速跳转… | `mod + P` || 命令面板 | `mod + shift + P` |-| 内容抽屉 | `Ctrl + Space` |+| 内容抽屉 | `mod + Space` || 项目设置 | `mod + ,` || 放大 / 缩小 / 重置界面 | `mod + =` / `mod + -` / `mod + 0` |diff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdxindex afb1c2d53..6c901eee9 100644--- a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx+++ b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx@@ -43,7 +43,7 @@ import { Aside, Steps, FileTree } from '@astrojs/starlight/components';"id": "acme.level-tools","name": "Level Tools","version": "0.1.0",- "engines": { "editor": "^0.34" },+ "engines": { "editor": "^0.97" },"main": { "editor": "src/editor.ts" }}```@@ -68,7 +68,7 @@ export default definePlugin({<Aside type="tip" title="engines.editor 由编辑器写,别照抄">`engines.editor` 是插件声称适配的编辑器版本区间。1.0 之前,**次版本号是破坏性-变更的轴**——`^0.34` 不匹配 `0.35`。新建插件时编辑器按**当前自己的版本**写这一行,+变更的轴**——`^0.97` 不匹配 `0.98`。新建插件时编辑器按**当前自己的版本**写这一行,所以从别处抄一个旧区间过来,插件一装上就是"版本不兼容"。</Aside>@@ -101,6 +101,10 @@ export default definePlugin({"我的面板怎么没出来"通常在这里就有答案:它要么不在列表里(`activate` 没跑到那一行),要么在列表里但 id 和你以为的不一样。+++*插件面板:顶部是新建插件、导入和刷新,左边是插件列表,右边是所选插件**声明**和**贡献**的内容。*+## 分享插件插件面板上的**导出**把一个插件打包成单个 `.esplugin` 文件(就是 ZIP,改名成@@ -460,8 +464,8 @@ export default definePlugin({ activate: () => {} });## 项目原生模块有些运行时是以 WASM 形态存在的:矢量动画播放器、各种求解器,凡是出身 C++、并且有-官方 emscripten 构建的东西都算。引擎自己就以这种方式加载着五个——物理、Basis 转码-器、各版本 Spine 运行时——项目也可以按同样的规则加自己的。+官方 emscripten 构建的东西都算。引擎自己就以这种方式加载着它的模块——物理、Basis 转码+器、DragonBones 运行时、视频解码器、各版本 Spine 运行时——项目也可以按同样的规则加自己的。自己 `fetch` 一个只在网页上行得通,别处都不行:小游戏没有 `fetch`,二进制必须**在包里**;试玩广告根本没有文件这个概念。而**项目模块**得到的是引擎自家模块同等的待diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdxindex cf5fd43da..f0abd50a4 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx@@ -12,7 +12,7 @@ description: "组件层之下的原语——手动寻路、感知内幕,以及`findPath` 就是导航插件用的那个 A\*:在 `NavGrid` 格子上做均匀代价搜索,4 连通或8 连通,octile/曼哈顿启发式,且不切角(走对角线要求两个共享的正交格子都可通行)。当你要自己驱动移动、画路径预览、或计算可达性(回合制的移动范围)时下沉到它——-或者当一张网格不够用时,因为 `Nav` 资源只持有一张网格:+或者当一张网格不够用时,因为 `Nav` 资源只持有一个当前表面:```typescriptimport { NavGrid, findPath, pathToWorld } from 'esengine/ai';@@ -60,32 +60,31 @@ const grid = navGridFromTiles((x, y) => level.tiles[y][x], {### 感知内幕-感知插件是四个导出函数之上的薄封装——适合在动作里做一次性视线检查、做自定义感官+感知插件是若干导出函数之上的薄封装——适合在动作里做一次性视线检查、做自定义感官(记忆、听觉、多目标),或对着一个假 world 做单元测试:-- **`senseTarget(ox, oy, facing, tx, ty, range, halfFov, isBlocked?)`**——纯几何:- 先查距离,再查视野锥(`halfFov` 是锥角的*一半*,弧度;≥ π 表示全向),最后走可选的- 遮挡回调。-- **`quaternionToAngle2D(z, w)`**——从 `Transform` 旋转四元数的 z/w 分量求 2D 朝向角- (弧度)。-- **`makeLosCheck(physics)`**——用物理射线构建遮挡回调:任何命中明显落在目标之前+- **`senseTarget(observer, facing, target, range, halfFov, isBlocked?)`**——纯几何,全部按 3D+ 计算(参数是 `Vec3` 点;平面场景只是 `z` 恒定的特例):先查距离,再查视野锥(`halfFov`+ 是锥角的*一半*,弧度;≥ π 表示全向),最后走可选的遮挡回调。+- **`facingFromRotation(rotation, axis?)`**——由 `Transform` 旋转和 `FacingAxis`(默认 `'x'`,+ 或 `'-z'`)求实体朝向的世界方向。+- **`makeLosCheck(physics)`**——用 2D 物理射线构建遮挡回调:任何命中明显落在目标之前(`fraction < 0.98`——最后约 2% 是目标自己)即视为遮挡。- **`stepPerception(world, isBlocked?)`**——插件每帧在 `PreUpdate` 跑的那一步:对每个 `Perceiver`,感知全部 `PerceptionTarget`,留下最近的可见者,写入`Perception` 组件。```typescript-import { quaternionToAngle2D, Transform, registerCondition } from 'esengine';-import { senseTarget } from 'esengine/ai';+import { Transform, registerCondition } from 'esengine';+import { senseTarget, facingFromRotation } from 'esengine/ai';-// A one-off sight check against a POINT — no PerceptionTarget needed.+// 对一个"点"做一次性视线检查——不需要 PerceptionTarget。registerCondition('seesShrine', (ctx) => {const tf = ctx.get(Transform);- const facing = quaternionToAngle2D(tf.rotation.z, tf.rotation.w);return senseTarget(- tf.position.x, tf.position.y, facing,- SHRINE.x, SHRINE.y,- 300, Math.PI / 3, // 300 px range, 120° cone+ tf.position, facingFromRotation(tf.rotation),+ SHRINE, // 一个 { x, y, z } 点+ 300, Math.PI / 3, // 300 px 范围,120° 视野锥).visible;});```@@ -96,14 +95,14 @@ registerCondition('seesShrine', (ctx) => {|---|---|| `visible` | 目标在范围内、在锥内、且未被遮挡。 || `distance` | 到目标的距离——即使不可见也总是被设置。 |-| `dirX` / `dirY` | 观察者 → 目标的单位方向;不可见时为 `(0, 0)`。 |+| `dir` | 观察者 → 目标的单位方向(`Vec3`);不可见时为零向量。 |-内置系统只在物理模块已加载时才接入 `makeLosCheck`;否则感知只做距离 + 视野锥——-AI 层没有对物理的硬依赖。+内置系统只在物理模块已加载时才接入视线检查(场景有 3D 求解器就用 3D 的,否则用 2D 的);+两者都没有时感知只做距离 + 视野锥——AI 层没有对物理的硬依赖。## 自定义应用-感知、FSM、BT、导航这四个插件是默认插件集的一部分,所以**编辑器和 `esengine` Web 运行时会替你+导入 `esengine/ai` 会注册感知、FSM、BT、导航这四个插件,所以**编辑器和 `esengine` Web 运行时会替你加上它们**。只有当你从一个裸的 `new App()` 构建应用时,才需要显式加:```typescriptdiff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdxindex e26a4500c..e00e8c03d 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx@@ -29,9 +29,9 @@ Estella 的 AI 层把一个实体变成会**感知**、会**决策**、会**移感知喂给决策,决策驱动导航。<Aside type="note">- 这里的一切都是 `esengine` 内核里的纯 TypeScript(没有 WebAssembly 侧模块)。感知、FSM、BT、- 导航这四个插件都由编辑器和 Web 运行时**自动**加入。只有当你从一个裸的 `new App()` 起步时,- 才需要自己加插件(见[自定义应用](/docs/zh-cn/gameplay/ai/advanced/#自定义应用))。+ 这里的一切都是 `esengine/ai` 子路径里的纯 TypeScript(没有 WebAssembly 侧模块)。感知、FSM、BT、+ 导航这四个插件在你的游戏导入 `esengine/ai` 时安装,编辑器和 Web 运行时会把它们加进应用。+ 只有当你从一个裸的 `new App()` 起步时,才需要自己加插件(见[自定义应用](/docs/zh-cn/gameplay/ai/advanced/#自定义应用))。</Aside>## 共享注册表@@ -122,6 +122,11 @@ export enum Status { Success = 'success', Failure = 'failure', Running = 'runnin| `spriteAnim.restart` | 动作 | 回卷到第 0 帧并播放(参数可切换剪辑)。 || `spriteAnim.stop` | 动作 | 暂停翻页动画。 || `spriteAnim.finished` | 条件 | 一次性精灵剪辑播完后为真。 |+| `audio.play` | 动作 | 拉起该实体 `AudioSource` 的播放旗标;参数可切换到指定剪辑。已在播放同一剪辑时不会重播。 |+| `audio.stop` | 动作 | 放下 `AudioSource` 的播放旗标。 |+| `audio.finished` | 条件 | 非循环剪辑播完且已停止播放时为真。 |+| `soundEvent.trigger` / `soundEvent.stop` | 动作 | 触发 / 停止该实体的 `SoundEventSource`。 |+| `property.set` | 动作 | 按 `Component.field` 路径与取值写入代理实体(或另一实体)的任意组件字段,例如 `UIVisual.color.a`。 |动作可携带一个可选**字符串参数**——在 FSM 状态检查器的动作名旁(或 BT 动作节点上)填写。内置动作用它承载组件无法按状态携带的数据,比如 `spriteAnim.play` 要切换到哪个剪辑;diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdxindex 04aa066a7..ab4b7db1f 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx@@ -25,11 +25,16 @@ cmds.spawn()|---|---|---|---|| **`Perceiver`** | `range` | `220` | 视野范围(世界像素)。 || | `fovDegrees` | `360` | 视野锥角度(`360` = 全向)。 |+| | `facingAxis` | `'x'` | 视野锥沿实体自身哪根轴指向:`'x'` 是屏幕右方(平面场景),`'-z'` 是导入 3D 模型的朝向。 |+| | `losLayers` | `0` | 仅 3D:视线射线可命中的物理层(`0` = 所有层)。 || **`Perception`** | `visible` | `false` | 当前是否看见一个目标。 || | `distance` | `0` | 到所见目标的距离。 |-| | `targetX`、`targetY` | `0` | 所见目标位置(世界像素)。 |-| | `dirX`、`dirY` | `0` | 从观察者指向目标的单位方向。 |+| | `targetX`、`targetY`、`targetZ` | `0` | 所见目标位置(世界像素)。 |+| | `dirX`、`dirY`、`dirZ` | `0` | 从观察者指向目标的单位方向。 || **`PerceptionTarget`** | *(标签)* | — | 把实体标记为可被 `Perceiver` 感知。 |-视野锥的朝向由感知者的 `Transform` 旋转决定。`Perception` 是一个瞬态、仅运行时的组件——+感知是三维的(平面场景只是 `z` 恒定的特例),所以视野锥和距离在 3D 场景里同样适用。+视野锥的朝向由感知者的 `Transform` 旋转沿 `facingAxis` 决定。场景里有物理世界时,+视线射线会对它投射,墙体因此能挡住视线:有 3D 求解器就用 3D 的,否则用 2D 的;两者都没有时,+感知只做距离 + 视野锥。`Perception` 是一个瞬态、仅运行时的组件——插件每帧重写它,所以你从不需要手写它的值。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdxindex 19fff54c9..ea54ca8d4 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx@@ -11,6 +11,18 @@ import { Aside } from '@astrojs/starlight/components';它与 [2D 物理](/docs/zh-cn/gameplay/physics/)**并存**,不是取代:2D 场景保留它已经有的求解器、单位和手感,而一个从不索取 3D 世界的项目也从不加载它。+## 配置++与 2D 侧模块一样,在编辑器和 Web 运行时里,场景用到 3D 刚体时 3D 世界会自动加载。自定义应用则自己加插件,+所有选项都可省略(重力默认 `{ x: 0, y: -9.81, z: 0 }`,`fixedTimestep` 默认 `1/60`,`pixelsPerUnit` 默认 `100`,+`maxBodies` 默认 `1024`):++```typescript+import { Physics3DPlugin } from 'esengine/physics3d';++app.addPlugin(new Physics3DPlugin('physics3d.js', { gravity: { x: 0, y: -9.81, z: 0 } }));+```+## 刚体一个实体同时带着 `RigidBody3D` **和**一个形状时才在世界里。没有形状的刚体没有任何@@ -29,6 +41,7 @@ cmds.spawn()| `gravityScale` | 这个刚体分担的重力比例。`0` 是失重,不是「掉得慢」。 || `linearDamping` / `angularDamping` | 运动衰减的快慢。 || `fixedRotation` | 冻结刚体被给定的朝向——让角色不会倒下的那个开关。它不会把一个一开始就歪的刚体扶正。 |+| `layer` | 刚体所在的十六个[碰撞层](#碰撞层)之一。 || `continuousCollision` | 检查这一步走过的整条路径,而不只是它最后停在哪。子弹需要它;默认关闭,因为它更贵。 |## 形状@@ -115,6 +128,9 @@ app.getResource(Physics3DDebugDraw).enabled = true;这层覆盖**不参与深度测试**,所以埋在墙里的形状照样看得见。调试视图就是要这样。</Aside>+带有 `gravity` 大于 0 的 `Planet` 会把每个动态刚体拉向自己的中心,而不是沿世界唯一的重力向量,+圆形世界因此处处有"下"(行星本身见[地形](/docs/zh-cn/graphics/terrain/))。+## 角色`CharacterController3D` **取代** `RigidBody3D` 而不是与它并存:被求解器推的刚体diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdxindex f9e38f0b8..93b21fd3f 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx@@ -18,6 +18,10 @@ description: 用节点和连线可视化编写玩法逻辑,保存为 .esgraph资产按路径引用并随场景预加载,所以在代理第一次 tick 之前就已就绪。图在 **Play**(以及导出的游戏)中运行,位于 `Update` 阶段,和状态机解释器并列。+++*脚本图示例:一个每帧移动、碰到边缘就折返的物体。左侧列出变量,以及各有多少个节点读取和写入它。*+## 两种连线| 连线 | 携带 | 方向 |@@ -41,7 +45,7 @@ description: 用节点和连线可视化编写玩法逻辑,保存为 .esgraph| **流程** | **分支**、**顺序**(引脚数可配)、**循环**、**延迟**。 || **变量** | **读取变量**、**设置变量**。 || **常量** | **数字**、**布尔**、**字符串**字面量。 |-| **动作** | 带执行引脚、会做事的节点:`timeline.play` / `timeline.pause`、`spriteAnim.play` / `restart` / `stop`、`audio.play` / `stop`、`soundEvent.trigger` / `stop`、`property.set`、`entity.despawn`、`debug.log`、`scene.load` / `reload`、`ui.setVisible`、`ui.setPage`、`fsm.fire`、`blackboard.set`——以及你在代码里注册的所有动作。 |+| **动作** | 带执行引脚、会做事的节点:`timeline.play` / `timeline.pause`、`spriteAnim.play` / `restart` / `stop`、`audio.play` / `stop`、`soundEvent.trigger` / `stop`、`property.set`、`entity.spawn`(生成图里指定的预制体,可给 x / y 与父实体,并返回新实体)、`entity.despawn`、`debug.log`、`scene.load` / `reload`、`ui.setVisible`、`ui.setPage`、`fsm.fire`、`blackboard.set`——以及你在代码里注册的所有动作。 || **取值** | 只产出值的节点(没有执行引脚):`math.*`(add、subtract、multiply、divide、min、max、abs、clamp、lerp、random)、`compare.*`(equal、less、greater)、`logic.*`(and、or、not)、`string.concat`、`property.get`、`entity.self`、`entity.byName`、`input.down` / `pressed` / `axis` / `pointer`——以及所有已注册的条件。 || **图** | 项目里其他可调用的图,用**调用图**节点来调用(在有图声明了入参之前为空)。 |diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdxindex 0b813e952..8dc00ff56 100644--- a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx+++ b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx@@ -5,7 +5,7 @@ description: Estella 是什么,以及它为什么存在。Estella 是一个 **2D 与 3D 游戏引擎**:上层是 TypeScript SDK,底层由高性能的**C++/WebAssembly** 内核驱动。它自带一个用于场景编辑与项目管理的可视化编辑器,-把一个项目导出到 **Web、桌面、微信小游戏、Playable 广告,以及原生 Android / iOS 应用**。+把一个项目导出到 **Web、桌面、微信等小游戏平台、Playable 广告,以及原生 Android / iOS 应用**。## 为什么选择 Estella?@@ -14,7 +14,7 @@ Estella 是一个 **2D 与 3D 游戏引擎**:上层是 TypeScript SDK,底层`Query`。- **数据导向** —— Entity-Component-System 架构,游戏逻辑可规模化扩展。- **可视化编辑器** —— 场景层级、检视面板、资源浏览器,无需手写 JSON。-- **跨平台** —— 一个项目,导出到 Web、桌面、微信小游戏、单文件 Playable 广告,+- **跨平台** —— 一个项目,导出到 Web、桌面、微信等小游戏平台、单文件 Playable 广告,以及原生 Android / iOS 应用(arm64 + 内嵌 Dawn,不是 WebView)。- **开箱即用** —— 物理、瓦片地图、粒子、材质与 2D 光照、动画、Spine、音频、UI,以及一套游戏 AI 层。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex 59338ab89..963231e50 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx@@ -192,8 +192,8 @@ registerDrawCallback('custom-mesh', () => {要把**整个场景**画进去,让一台相机指向它:把 `Camera.renderTarget` 设成目标的句柄,那台相机就画到那里而不是屏幕——在屏幕相机之前渲染,也不参与「谁是主视图」的竞争。它看见什么由自己的排序层(`Camera.cullingMask`)决定,所以小地图相机和玩家相机可以-看同一个世界、显示不同的部分。目前仅 WebGL2:WebGPU 后端还不能把渲染目标的纹理-交给 `Sprite`:+看同一个世界、显示不同的部分。渲染目标在两个后端上都能交给 `Sprite`;这条路径的+像素验证目前只在 WebGL2 上跑(WebGPU 上,一帧同时含离屏和屏幕通道时,帧回读返回空):```typescriptimport { RenderTexture, Draw } from 'esengine';@@ -229,6 +229,45 @@ sprite.texture = rt.texture;这是低层接口:它不会替你渲染场景——只是把你在 `begin`/`end` 之间画的东西,在你构建的 view-projection 矩阵下重定向到目标。+## 把多张纹理合到一张画布:`TextureAtlas`++共用同一张纹理的精灵会合成一个批次绘制。当图片是分开来的——从服务器取的图标、由部件拼成的角色、+玩家选的图片——`TextureAtlas.pack` 会在运行时把它们画到**一张**画布上,并告诉你每张落在哪里。++++*上图每张卡片都是从同一张画布上切出来的精灵(右侧的小图就是画布本身)。卡片左上角的白色方块和+底边的深色条说明它们方向没有翻转。*++```typescript+import { TextureAtlas } from 'esengine';++// 在 Schedule.Update 的系统里调用——画布在自己独立的一趟里绘制。+const atlas = TextureAtlas.pack([iconA, iconB, iconC], { padding: 2 });+if (!atlas) return; // 渲染器还没起来:下一帧再试++world.insert(entity, Sprite, { ...atlas.sprite(iconB), size: { x: 64, y: 64 } });+```++`sources` 是纹理句柄(`Sprite.texture` 里存的那种)。`atlas.sprite(source)` 返回可直接给 `Sprite`+用的 `{ texture, uvOffset, uvScale }`;`atlas.get(source)` 还会给出像素矩形(`x`、`y` 从顶边算起,+以及 `width`、`height`)。++| 选项 | 默认 | 说明 |+|---|---|---|+| `maxSize` | `2048` | 最大尝试的画布边长(像素)。放不下时 pack 会抛错。 |+| `padding` | `2` | 图片之间留的透明像素,避免过滤时边缘采到邻居。 |+| `filter` | `'linear'` | 画布的采样方式:`'linear'` 或 `'nearest'`(像素风)。 |++- 画布取能装下全部图片的最小 2 的幂尺寸。图片按原样拷贝、不做混合,所以透明度完全保留。+- 同一个句柄传两次只会打包一次。+- 图集在用期间**不要释放源纹理**:图形设备丢失后,画布会用它们自动重画。+- `atlas.repaint()` 手动重画(改了源之后);`atlas.release()` 释放画布。两者都不动源纹理。+- 和 `RenderTexture` 一样,可以用在 `Sprite` 上;这条路径的像素验证目前只在 WebGL2 上跑(WebGPU 上一帧同时含离屏和屏幕通道时,帧回读返回空)。++[Render Texture 示例](https://github.com/esengine/estella/tree/master/examples/render-texture)+里建了四张卡片并打包(`src/systems/atlas.ts`)。+## 参见- [精灵与渲染](/docs/zh-cn/graphics/sprites/) —— 图像与形状的组件路径。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex 4cd5736d3..b1dc9036b 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx@@ -84,7 +84,7 @@ const addSun = defineSystem([Commands()], (cmds) => {需要记住的:-- **分块光不投射阴影。** 没挤进 16 盏的投影光会被拒绝(编辑器里的 Light Status 会说明),因为阴影图只在这个循环里读取。让重要的光有阴影,让大量的光做氛围。+- **分块光不投射 3D 阴影。**(2D 光不同:2D 阴影遮蔽图对分块光同样有效。)没挤进 16 盏的投影光会被拒绝(编辑器里的 Light Status 会说明),因为阴影图只在这个循环里读取。让重要的光有阴影,让大量的光做氛围。- **`radius` 就是够得着的范围。** 分块掩码由它生成;半径巨大的光会碰到每个格子,开销也就像它那么大。- 平面反射只用那 16 盏绘制:它的相机不是分块所对应的那个相机。- 2D 光也走同一个集合,所以有五十支火把的 2D 场景同样被照亮。@@ -323,8 +323,8 @@ cmds.spawn()## 烘焙光照-一帧最多 16 盏灯。第 17 盏会被丢掉——按亮度取舍,并打出一条说明丢了谁的警告——这个天花板不是画质-选项:一个摆了三十盏灯的房间,在这里根本无法实时点亮。+一帧最多携带 112 盏灯:16 盏对每个像素都读取,96 盏分块(见「多盏光」)。超出的会被丢掉——按亮度取舍,+并打出一条说明丢了谁的警告——这个天花板不是画质选项。分块光不投射 3D 阴影,而且每盏灯在它照到的每个像素上仍有开销。**烘焙**是绕过它的办法。不会移动的光离线算一次,存成一张纹理;运行时表面读一个纹素,而不是把所有光加起来。于是一百盏灯的代价正好等于一盏,而这个代价是一次采样。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxindex 1cd65b641..a21e62116 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx@@ -318,7 +318,7 @@ world.applyEntityOrder([other, another, card]);## 翻转、图集与滚动- 用 `flipX` / `flipY` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。-- **图集**:把 `uvOffset` 和 `uvScale` 设为某个单元格的归一化矩形,显示打包图集里的一格。(逐帧动画+- **图集**:把 `uvOffset` 和 `uvScale` 设为某个单元格的归一化矩形,显示打包图集里的一格;分散的纹理可以用 [`TextureAtlas`](/docs/zh-cn/graphics/drawing/) 在运行时合到一张画布上。(逐帧动画请用 [Animator](/docs/zh-cn/animation/overview/) 驱动这些,而非手动。)- **滚动**:随时间改 `uvOffset` 来滚动纹理(水面、传送带),并设 `tileSize` 把它在大精灵上重复平铺。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex e5741a9c7..a40d3c7ff 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx@@ -207,5 +207,5 @@ registerTerrainProvider(planet);- **上色精度就是页的精度。** 图层权重和高度一起采样,每格两个,所以近处比这更细的 splatmap 会被平均,远处更粗。- **没有洞、洞穴或悬挑。** 高度场在每个位置只有一个高度。洞穴和桥是和它放在一起的网格。- **只有位置。** 地形跟随实体的位置;它的旋转和缩放不被考虑,`heightAt` 不考虑,抬起地面的着色器也不考虑。让实体保持不旋转、不缩放,用 `sizeX`、`sizeZ` 和 `height` 设定地面大小。-- **无限地面只有噪声。** 它不接受高度图或 splatmap,它的侵蚀也不画泥土。+- **无限地面由它的生成器(provider)生成。** 它不接受高度图或 splatmap,它的侵蚀(引擎自带噪声的)也不画泥土。- **页每帧只做几个**,所以在最初几帧,或视点突然跳远之后,地面会先粗一会儿再变清晰,而不是卡住某一帧。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx b/docs/astro/src/content/docs/zh-cn/graphics/video.mdxindex e22bd7886..78bfc5f5f 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/video.mdx@@ -130,6 +130,8 @@ const playIntro = defineSystem([Res(VideoPlayer)], (video) => {| 平台 | 解码器 | 说明 ||---|---|---|| Web / 桌面 | `HTMLVideoElement` | 任何浏览器支持的编解码(H.264 `.mp4`、WebM……)。WebGL2 逐帧零拷贝上传;WebGPU 走 canvas 回读。 |+| 原生(Android / iOS) | 同一个引擎自带的 wasm 解码器,作为侧模块取得 | 播放烹饪后的 `.esv` + `.m4a`;设备上没有别的视频路径。 |+| 其他小游戏平台 | 同一个引擎自带的 wasm 解码器,在每个厂商上都是默认路径 | 宿主自带的视频解码器在 PC 客户端上缺失、在手机上不可靠,所以取唯一确定的那条路径。 || 微信 | 引擎自带 MPEG-1 wasm(`videodec`,pl_mpeg) | 每个设备上都确定——`wx.createVideoDecoder` 在 PC 上缺失、在手机上不可靠。场景一旦用到 `Video` 就自动随包;播放烹饪后的 `.esv` + `.m4a`。 |## 最佳实践diff --git a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx b/docs/astro/src/content/docs/zh-cn/graphics/water.mdxindex e1e896100..8df462ebb 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx@@ -217,7 +217,7 @@ Details 只显示水体这种形态用得到的字段:湖有尺寸和边界,河- 水是水平的:水体可以绕自己的上方向旋转,但不能倾斜;水面在每一处只有一个高度,所以没有水上之水。- 只使用一个区域,即找到的第一个 `WaterZone`,它的所有水共用一个材质;也只使用一个海洋,即找到的第一个。区域范围之外的水不画,海洋除外。岸线和河流按区域的分辨率描出:只有一两个纹素宽的河,或比这更细的轮廓细节会丢失,大的区域需要高的 `resolution`。- 水面从相机伸出 `cells * cellSize * 2^(rings - 1) / 2` 远;自己放了 `WaterZone` 时,要让这个距离覆盖应该看到的范围(不是你放的区域会自己把格子变大来做到这一点)。-- 河流不会切削地面,急流和瀑布不会按水流的快慢或陡度起泡沫。湖泊的轮廓是平面上的多边形:它不跟随弯曲的岸线,波浪向岸边消失而不是在岸上破碎。+- 河流只有在 `bedDepth` 大于零时才会切削地面(见上文「河床」);急流和瀑布不会按水流的快慢或陡度起泡沫。湖泊的轮廓是平面上的多边形:它不跟随弯曲的岸线。- 东西可以漂浮(见[漂浮](#漂浮)),也会激起尾迹(见[涟漪](#涟漪));还没有东西能游泳。- 焦散和光束只跟随第一盏平行光,来自一个图案而不是模拟:这张网并不响应波浪的真实形状。从上面看时,焦散把水下的东西当作朝上的面(画面里那里没有法线),所以水面下的一面墙会像地板一样被照亮。- 从下面看的镜子是屏幕空间的:它只显示帧里在屏幕上的东西,射线离开画面或什么也没碰到时,找到的是水自己的颜色。diff --git a/docs/astro/src/content/docs/zh-cn/index.mdx b/docs/astro/src/content/docs/zh-cn/index.mdxindex 6f83c2457..2e6d377d6 100644--- a/docs/astro/src/content/docs/zh-cn/index.mdx+++ b/docs/astro/src/content/docs/zh-cn/index.mdx@@ -40,7 +40,7 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';一个项目,导出到 Web、桌面、微信小游戏、单文件 Playable 广告,以及原生 Android / iOS 应用。</Card><Card title="为智能体而生" icon="comment">- 编辑器本身就是一个 MCP 服务器,还自带一个智能体。两者驱动的都是 UI 用的那 65 个工具——+ 编辑器本身就是一个 MCP 服务器,还自带一个智能体。两者驱动的都是 UI 用的那一百多个工具——所以智能体能搭好场景、按下运行,再看一眼自己做出来的截图。</Card></CardGrid>diff --git a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdxindex 0c77b325e..ff2b0ba6a 100644--- a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx@@ -82,6 +82,7 @@ world.insert(rock, LODGroup, {一律到不了(引擎会告警)。- **尺寸必须递减。** `lod2Size` 小于 `lod1Size`,依此类推。- **`cullSize: 0`** 完全关掉剔除,于是这一组永远不会消失。+- **各级可以在导入时生成。** 在模型的导入设置里把 **Generate LODs** 设为 1–3 级(或给 `import-model` 传 `--lods <n>`):每个网格会被塌缩成约 50%、20%、7% 三角形的副本,写成 `<mesh>_lod<n>.esmesh`,并在实体上加一个 `LODGroup`。蒙皮和变形网格,以及三角形少于 **LOD Minimum Triangles**(256)的网格,只保留一级。- **蒙皮的一组必须共用一副骨架。** 蒙皮网格的每一级都要有相同的关节数;对不上的那一级会画成绑定姿势,引擎会说出来。@@ -103,4 +104,7 @@ world.insert(rock, LODGroup, {`LODGroup` 讲的是**同一个物体在不同尺寸下**的事。它不是流式加载:每一级的网格都常驻,不会加载也不会卸载;小到 `cullSize` 以下的物体只是不画,并没有从世界里移走。-把远处的物体合并成一个代理(HLOD),以及把世界分块加载,都是另外的题目。+把远处的物体合并成一个代理(HLOD),以及把世界分块加载,都是另外的题目;引擎里没有把任意场景物体烘成代理的通用 HLOD。+现有的是针对具体内容的:植物的远景版本(`Foliage`、`PlacedFoliage`,见[植被](/docs/zh-cn/graphics/foliage/))、+地形自己按距离切分的四叉树([地形](/docs/zh-cn/graphics/terrain/)),以及[静态合批](/docs/zh-cn/performance/static-batching/)+(把不同网格合并以省绘制调用,但不会让它们在远处变便宜)。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdxindex 8e2f03785..b321b2839 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx@@ -53,10 +53,12 @@ const reviveSystem = defineSystem([Res(Ads), GetWorld()], (ads, world) => {`Ads.available` 在**存在某个广告源**时为 true——平台自带的,或安装进来的 provider。用它诚实地隐藏"看广告"按钮:-- **微信 / 抖音构建**——宿主的激励/插屏广告,同一份家族实现。+- **小游戏构建**(微信、抖音和其他同族宿主)——宿主的激励/插屏广告,同一份家族实现。+ 宿主没有广告接口的厂商,`available` 为 false。+- **带广告的渠道 Web 导出**——Poki、CrazyGames 和 YouTube Playables 会安装各自的 provider(见下文)。- **编辑器 Play 模式**——自动安装 **mock provider**:`showRewarded`"播放"片刻后resolve `completed: true`,真实的暂停/音频仪式照常运行。复活流程在工位上就能排练。-- **Web 与原生构建**——没有广告系统,`available` 为 false。接入聚合 SDK 的原生壳+- **普通 Web 与原生构建**——没有广告系统,`available` 为 false。接入聚合 SDK 的原生壳走编辑器同一扇门:`Ads.setProvider(...)`。## 分享@@ -313,6 +315,18 @@ Inspector 会提供测试上下文。训练示例的真实 SDK 初始化、加和奖励完成已通过这条入口核实;提交前仍须逐项完成其余 QA 模块,不能把这些观察等同于设备验收或正式投放的广告填充保证。+## CrazyGames Web 导出++在同一个 Web 打包设置里选择 **CrazyGames**,或设置 `packaging.platforms.web.channel`+为 `"crazygames"`。导出会接入官方 v3 SDK:上报加载开始与结束,奖励广告和中插广告走现有的+`Ads` 资源,存档通过 SDK 的 Data API 保存(须在 CrazyGames 开发者后台开启 **Progress Save**;+`setItem` 不代表云备份确认),并跟随宿主的静音设置。初始化失败时,游戏继续运行,宿主服务关闭。++与 Poki 一样,由游戏逻辑上报真实的 gameplay 开始与结束;导出器不会去推断。`Scores.submit`+可以向已获邀请的 CrazyGames 分数榜发送加密后的分数——在项目设置里填平台配置中的+Base64 **Encryption Key**(切勿填服务器 API Key;它会随 Web 包发布),留空则禁用提交。+发送了分数不代表榜单接受它,导出也不是平台审核:官方检查须另行完成。+## YouTube Playables Web 导出导出检查总包低于 250 MiB、单文件低于 30 MiB、最多 8000 个文件,以及diff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdxindex 280779cf8..b57e5fc04 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx@@ -140,6 +140,10 @@ Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,而不是写出一个链接不起来的工程。</Aside>+++*Android 目标页。运行时模板装好之前,对话框会这样提示,并给出**下载**和**从文件安装**。*+## 应用身份原生应用有一些引擎永远不读的系统级属性——运行时转不动手机,而应用商店会永久沿用 bundle iddiff --git a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdxindex b217c185c..2cb8d2af5 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx@@ -112,7 +112,7 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回## 构建产出了什么-每次 Web / 桌面导出都会在游戏旁写出一份 **`asset-manifest.json`**(可寻址清单)——那正是客户端做热更新 diff 的依据。当这次构建有 CDN 根地址时,导出还会把一段 `hotUpdate` 烘进 `game.config.json`:+每次 Web、桌面、小游戏和原生导出都会在游戏旁写出一份 **`asset-manifest.json`**(可寻址清单)——那正是客户端做热更新 diff 的依据。当这次构建有 CDN 根地址时,导出还会把一段 `hotUpdate` 烘进 `game.config.json`:```json{diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 2e2593512..2ea574e2f 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -5,8 +5,8 @@ description: 从编辑器的"打包项目"对话框把一个项目发布到 Webimport { Aside, Steps } from '@astrojs/starlight/components';-一个 Estella 项目可发布到六个目标——**Web**、**桌面**、**微信小游戏**、单文件 **Playable 广告**,-以及原生 **Android** / **iOS** 应用——全部从编辑器完成。导出用的是**你在编辑器里运行的同一套运行时**,+一个 Estella 项目可发布到 **Web**、**桌面**、**微信小游戏**和其他小游戏平台(抖音、快手、B 站、快游戏、+支付宝、华为快游戏)、单文件 **Playable 广告**,以及原生 **Android** / **iOS** 应用——全部从编辑器完成。导出用的是**你在编辑器里运行的同一套运行时**,所以你发布的就是你测过的(*play == ship*)。## 从编辑器导出@@ -64,9 +64,10 @@ import { Aside, Steps } from '@astrojs/starlight/components';| **Web** | 一个静态、自包含的 Web 构建。 | `dist-web/` | **Preview over http**,或把文件夹上传到任意静态托管。 || **桌面** | 每装了一个桌面运行时模板,就出一个可直接运行的**原生**应用——macOS 上是 `.app`,Windows 与 Linux 上是 `<Name>/` 目录(其中分别是 `<Name>.exe` 和 `<Name>`)。没有 Chromium,也没有 npm 工程。 | `dist-desktop/` | 双击即可。选了 **Steam** 渠道还会写出 depot 脚本和一份带本次构建确切取值的 `STEAM.md`——见 [Steam](/docs/zh-cn/publishing/steam/)。 || **微信** | 一个微信小游戏包。 | `dist-wechat/` | 在微信开发者工具里打开该文件夹并设置你的 AppID。见 [微信小游戏](/docs/zh-cn/publishing/wechat/)。 |+| **抖音**、**快手**、**B 站**、**快游戏**、**支付宝**、**华为快游戏** | 对应宿主的小游戏包(快游戏和华为是已签名的 `.rpk`),走与微信同一条管线——见[小游戏平台](/docs/zh-cn/publishing/minigame-platforms/)。 | `dist-douyin/`、`dist-kuaishou/`、`dist-bilibili/`、`dist-quickgame/`、`dist-alipay/`、`dist-huawei/` | 在该平台的开发者工具里打开(抖音和 B 站的 AppID 填在项目设置里,快手和支付宝在开发者工具里填;华为需要在 AppGallery Connect 注册应用)。 || **Playable** | 一个自包含的 `index.html`,一切内联——无外部请求(广告平台的要求)。 | `dist-playable/` | **Preview over http**(它的真实宿主是广告平台的 iframe)。先选好[广告平台](#试玩广告平台),CTA 与体积检查才对得上投放目标。 |-| **Android** | **原生** arm64 应用(Vulkan)的内容——真 APK,不是 WebView。 | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` 把它包成已签名的 APK。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |-| **iOS** | **原生** arm64 应用(Metal)的内容;若本机已为 iOS 构建过引擎,还会附带 Xcode 工程。 | `dist-ios/` | 打开生成的 Xcode 工程,选签名 Team,Run。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |+| **Android** | **原生** arm64 应用(Vulkan)的内容——真 APK,不是 WebView。 | `dist-android/` | 装好 Android 运行时模板后,导出本身就写出已签名的 APK(也可以写 Android Studio 工程,或在 APK 旁再写一个 App Bundle)。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |+| **iOS** | **原生** arm64 应用(Metal)的内容;装好 iOS 运行时模板后,还会围着它写出 Xcode 工程。 | `dist-ios/` | 打开生成的 Xcode 工程,选签名 Team,Run。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |桌面、Android 与 iOS 导出的是应用**内容**而非可直接运行的载荷:引擎、SDK 和游戏运行时都住在应用二进制里。三者都由编辑器安装的运行时模板组装而成,所以打包本身不需要任何工具链——见下文的@@ -97,9 +98,9 @@ playableCta();| 平台 | 上限 | 点击跳转 | 说明 ||---|---|---|---|-| **通用** | 2MB | — | 不接任何平台接口。上限取我们已知里最严的一档——毕竟未指名的目标可能是其中任何一家。 |-| **Meta**(Facebook / Instagram) | `index.html` 2MB | `FbPlayableAd.onCTAClick()` | Meta 的 5MB 是 ZIP 包的总量;单文件试玩受 `index.html` 那条约束。禁止任何 HTTP 请求。 |-| **Google Ads**(应用广告系列) | 5MB | `ExitApi.exit()` | 它的退出接口是 Google 托管的脚本,官方要求以字面 `<script>` 写在 `<head>` 里——导出会帮你写好。Google 上传 **ZIP**,所以要先把 `index.html` 压缩。 |+| **通用** | 5MB | — | 不接任何平台接口。上限取这里列出的各平台都接受的那一档——毕竟未指名的目标可能是其中任何一家。 |+| **Meta**(Facebook / Instagram) | 5MB | `FbPlayableAd.onCTAClick()` | Meta 把一个 HTML5 试玩文件限制在 5MB;常被引用的 2MB 不在 Meta 的任何规范里。禁止任何 HTTP 请求。 |+| **Google Ads**(应用广告系列) | 5MB | `ExitApi.exit()` | 它的退出接口是 Google 托管的脚本,官方要求以字面 `<script>` 写在 `<head>` 里——导出会帮你写好。Google 上传 **ZIP**,所以导出还会在 HTML 旁写一个 `playable.zip`,体积上限按它来量。 || **MRAID 平台**(通用) | 5MB | `mraid.open()` | 适用于任何 MRAID 宿主。`mraid` 由宿主 webview 注入,`<head>` 无需任何内容。 || **Unity Ads** | 5MB | `mraid.open()` | 运行时自动等待 MRAID ready 和 viewable,隐藏时暂停游戏及音频,退出时释放宿主监听。 || **AppLovin** | 5MB | `mraid.open()` | 要求所有资源内嵌——单文件试玩本来就是。 |@@ -164,20 +165,25 @@ export default {它随后就会和内置平台并列出现在对话框的"广告平台"下拉里,并走同一条导出管线。+++*Playable 目标页。**广告网络**决定包要遵守的体积上限和交付形式。*+## 运行时前置条件Web、桌面与 **Playable** 都复用随编辑器附带的引擎运行时,所以导出无需准备——试玩包内联的就是同一份 web 运行时(glue 作为 blob 模块、wasm 以 base64 传入),不需要单独构建。在这些基于-网页的目标里 **微信**是例外:它的 WebAssembly 加载器不同,运行时需先构建一次:+网页的目标里 **微信**是例外:它的 WebAssembly 加载器不同,用的是自己的运行时。编辑器下载包也自带这份运行时,+连同微信需要的侧模块,所以装好的编辑器导出微信无需任何准备;在引擎源码检出里则需先构建一次:```bash-# 仅在首次微信导出前+# 仅源码检出,首次微信导出前node build-tools/cli.js build -t wechat```当某个目标的运行时缺失时,打包项目对话框会提醒你,而微信导出会**直接失败**并给出确切的构建命令——而不是产出一个运行时才崩的包。微信还需要为游戏用到的每个引擎特性构建对应的-侧模块(`physics-wechat`、`spine-wechat`,压缩纹理用 `basis-wechat`)——见+侧模块(`physics-wechat`、`spine-wechat`、`dragonbones-wechat`,压缩纹理用 `basis-wechat`,视频用 `videodec-wechat`)——见[微信小游戏](/docs/zh-cn/publishing/wechat/)。对话框区分**两类**缺失的前置条件,因为它们挡住的程度并不一样:@@ -187,9 +193,10 @@ node build-tools/cli.js build -t wechat可安装应用那一步需要工具链,而那一步可以在另一台机器上跑——编辑器在 Windows 上时,iOS 构建本来就得如此。-<Aside type="caution" title="移动端需要引擎源码检出">- Android 和 iOS 是唯一一对编辑器下载包没有端到端自带的目标:原生宿主需要先从引擎源码- 检出构建一次(Dawn + QuickJS),再加上 Android SDK/NDK,或装有 Xcode 的 macOS。见+<Aside type="caution" title="移动端需要运行时模板">+ Android 和 iOS 是唯一一对编辑器下载包没有自带的目标:引擎编译好的那一半是**运行时模板**,+ 每个编辑器版本下载一次(打包对话框里该目标的那一行有**下载**按钮)。Android 只需要这个——+ 不需要引擎源码检出、SDK、NDK 或 JDK。iOS 另外需要装有 Xcode 的 macOS 来签名和运行。见[Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。</Aside>@@ -261,7 +268,7 @@ which a block-compressed texture must be打进图集是另一条出路。:::-**内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。+**内容寻址** 默认开启(Web、桌面和小游戏目标;每个文件按字节哈希命名——URL 不可变、自动去重)。**高级**里放着[热更新](/docs/zh-cn/publishing/hot-update/)的 CDN 根地址、source map,以及构建结束后是否打开输出目录。@@ -296,7 +303,7 @@ which a block-compressed texture must be方向是**一个项目级设置**,而非逐平台:**设置 → 项目 → 游戏 → 显示(Display) → 屏幕方向**(竖屏或横屏),就在设计分辨率旁边。所有目标都遵循它——微信 `game.json` 的 `deviceOrientation`、Web 构建的"请旋转设备"提示(以及尽力而为的 `screen.orientation.lock`)、桌面窗口的宽高比,以及原生应用的 `app.config.json`(引擎能 letterbox,却转不动手机)。留空则**从设计分辨率的宽高比推导**(更宽或方形 ⇒ 横屏,更高 ⇒ 竖屏),因此横屏设计零配置即在各处横屏发布。-**试玩包是有意的例外**:它从不锁定页面方向。在广告 SDK 里,容器尺寸由 SDK 决定,因此"请旋转设备"这类遮罩可能把游戏永久挡住——玩家转了手机却毫无变化,因为那条 media query 一直在读容器而不是设备。试玩包保持自适应(各平台都要求如此),方向只在平台需要时**声明**出去,例如 Google 的 `ad.orientation` meta 标签。请为两种比例都设计,或用[相机适配](#)做 letterbox,让构图在任一比例下都成立。+**试玩包是有意的例外**:它从不锁定页面方向。在广告 SDK 里,容器尺寸由 SDK 决定,因此"请旋转设备"这类遮罩可能把游戏永久挡住——玩家转了手机却毫无变化,因为那条 media query 一直在读容器而不是设备。试玩包保持自适应(各平台都要求如此),方向只在平台需要时**声明**出去,例如 Google 的 `ad.orientation` meta 标签。请为两种比例都设计,或用[相机适配](/docs/zh-cn/core-concepts/screen/)做 letterbox,让构图在任一比例下都成立。设置界面见 [编辑器](/docs/zh-cn/editor/overview/)。@@ -329,7 +336,7 @@ import { Tilemap } from 'esengine/tilemap';只有一个子系统暂时没有子路径:用到 **Video** 的项目会拿整份引擎,包含全部可选子系统。其他什么都不变——两种情况下 API 完全一样。-微信和抖音上的引擎二进制也是同样的道理。当没有任何场景或预制体里有粒子发射器、后处理体积或瓦片地图,脚本里也没有提到它们时,包里带的是+用微信运行时的小游戏目标(微信、抖音、快手、B 站)上的引擎二进制也是同样的道理。当没有任何场景或预制体里有粒子发射器、后处理体积或瓦片地图,脚本里也没有提到它们时,包里带的是**精简引擎**:同一个引擎去掉这三个子系统,在 4 MB 主包限制下小约 200 KB。脚本里只要出现一次(`ParticleEmitter`、`PostProcess…`、`Tilemap…`)就会带完整版,在项目设置里把 `esengine/tilemap` 设为**包含**也一样;拿不准时总是全带。@@ -340,7 +347,7 @@ import { Tilemap } from 'esengine/tilemap';| 目标 | 上限 || --- | --- || 微信小游戏 | 主包 4MB,主包与所有分包合计 30MB |-| 试玩广告 | 取决于所选平台 —— Meta 单个 `index.html` 2MB、Google ZIP 5MB 等 |+| 试玩广告 | 取决于所选平台 —— Meta 5MB、Google ZIP 5MB 等 || 网页 / 桌面 / Android / iOS | 无公开上限;可用下面的方式自定 |超出上限只报告、不阻断——它构建成功也能跑,是否卡发布由你决定(见下面的[用体积卡构建](#用体积卡构建))。超过上限的 90% 后进度条转为琥珀色,因为再来一轮美术就该破线了。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdxindex 8f99100d2..5e8886149 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx@@ -5,12 +5,13 @@ description: 为微信小游戏构建和导出游戏,并使用分包。import { Steps, Aside } from '@astrojs/starlight/components';-Estella 能把同一个项目导出为**微信小游戏**。你为微信目标构建引擎,从编辑器导出游戏,+Estella 能把同一个项目导出为**微信小游戏**。你从编辑器导出游戏,再用微信开发者工具打开结果。## 为微信构建引擎-微信目标用微信的 `WXWebAssembly` 垫片编译 C++ 内核:+编辑器下载包已经自带微信引擎和它的侧模块,装好的编辑器不需要做这一步。在引擎源码检出里,+需要先构建一次。微信目标用微信的 `WXWebAssembly` 垫片编译 C++ 内核:```bashnode build-tools/cli.js build -t wechat@@ -54,9 +55,14 @@ node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码实例化,改名会让游戏在开发者工具里直接挂掉。</Aside>+++*微信小游戏目标页:标题下是体积上限,然后是该目标自己的设置,再往下是通用的构建选项。*+## 压缩纹理-在打包对话框勾选**压缩纹理**,把 PNG 烘焙为 KTX2 —— 包更小、首屏更快。两个微信+打包对话框的**资源压缩**选**按导入设置**时,纹理按各自导入设置里的**压缩**+(自动、GPU 压缩或原图)烘焙为 KTX2 —— 包更小、首屏更快。两个微信特有的细节,都已自动处理:- Basis 转码器以 `basis-wechat` 侧模块的形式随包发布——构建一次(见上),否则@@ -103,7 +109,7 @@ node build-tools/cli.js build -t wechat-glx- **保持在 4 MB 主包限制以内**:把按需内容移到 `subpackages/<name>/`——见[资源](/docs/zh-cn/assets/overview/)。导出会设置 `bigPackageSizeSupport`,超限的包在开发者工具里仍可*预览*——但上传照样卡限制。-- **压缩纹理** —— 见上文;这是包体最大的一笔节省。+- **压缩纹理** —— 见上文(让**资源压缩**保持**按导入设置**);这是包体最大的一笔节省。- **在微信开发者工具里测试**,而不只是浏览器——文件系统、存储与套接字后端都与 Web 不同。- **在游玩中预加载下一关的分组**(`loadGroup`),让分包下载不卡过渡。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdxindex d6e6122ad..f618d1879 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx@@ -15,7 +15,8 @@ click ─▶ ui.setPage(badge, on) 目标「Card」```连线**刻意不是**可视化编程语言。一行里没有分支、没有表达式;真的需要逻辑时,这行会指向一个-把控制权交给[状态机](/docs/zh-cn/gameplay/ai/overview/)的动作——Estella 已经有图编辑器了。+把控制权交给[状态机](/docs/zh-cn/gameplay/ai/overview/)的动作——Estella 已经有图编辑器了;更适合画出来的逻辑+也可以放进[脚本图](/docs/zh-cn/gameplay/script-graphs/),它的 **On event** 节点监听的是同一批具名实体事件。## 检视器里的一根线diff --git a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdxindex 3886c70e1..d8a9a7b58 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx@@ -122,6 +122,7 @@ if (Controls.pressed('Jump')) { /* 本帧边沿 */ }| `Keys1D(neg, pos)` | axis | 两个键 → 带符号的 1D 轴。 || `Keys2D(up, down, left, right)` | axis2d | 四个键 → 2D 方向。 || `Stick('left' \| 'right', pad?)` | axis2d | 一根手柄摇杆(上 = +y,与 `Keys2D` 一致)。 |+| `Virtual(id)` | button / axis / axis2d | 游戏用 `input.setVirtual(id, x, y)` 写入的具名值——屏幕上的[虚拟摇杆与虚拟按键](/docs/zh-cn/ui/widgets/#virtualjoystick)喂的就是它,触屏控件因此和按键驱动同一个动作。 |### 数据模型@@ -149,6 +150,7 @@ const jump: ActionDef = {| `keys1d` | `neg`、`pos` | `Keys1D` || `keys2d` | `up`、`down`、`left`、`right` | `Keys2D` || `stick` | `stick: 'left' \| 'right'`、`pad?` | `Stick` |+| `virtual` | `id` | `Virtual` |因为绑定就是数据,这一份模型同时也是**改键与持久化格式**:`toJSON()` / `loadJSON()`只往返绑定本身(每动作一个 `Binding[]`),而 `toAsset()` 序列化整张映射——连动作类型diff --git a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdxindex ab5ef2c54..850e6da3b 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx@@ -71,6 +71,24 @@ scalar.deg2rad(90); // degrees -> radians还有:`clamp`、`inverseLerp`、`rad2deg`、`approximately`、`mod`、`sign`。+## 带种子的随机数++`createRng(seed)` 返回一个带种子的生成器,**在每个宿主上抽出相同的序列**(基于 32 位整数运算的 SFC32),+所以裁定结果的服务器和做预览的客户端能得到一致的数。`hashSeed` 把数字、字符串或列表变成稳定的 32 位哈希:++```typescript+import { createRng } from 'esengine';++const rng = createRng(['loot', levelId]);+rng.float(); // [0, 1)+rng.int(1, 6); // 1..6(含两端),无取模偏差+rng.chance(0.25); // 25% 概率为 true+rng.pick(items); // 随机取一个元素+rng.weighted(items, (i) => i.weight);+rng.shuffle(items); // 洗牌后的副本+const drops = rng.fork('drops'); // 独立的随机流,不受本流抽取次数影响+```+## 旋转辅助`Transform.rotation` 是四元数;2D 下只会绕 Z 轴旋转,几个导出就覆盖了@@ -97,6 +115,8 @@ const delta = normalizeAngle(targetAngle - facing);| `quaternionToAngle2D(rz, rw)` | 由四元数的 `z`/`w` 求 Z 角度(弧度,`2 * atan2(z, w)`)。 || `normalizeAngle(a)` | 把任意角度归一到 `(-π, π]`,用于最短转向比较。 |+完整的 3D 旋转用 `q` 命名空间:`create`、`mul`、`axis(axis, rad)`、`normalize`、`conjugate`、`rotate(q, v)`、`fromEuler` / `toEuler`、`rotationTo(from, to)`、`setAngleZ` / `angleZ` 等。+如果需要的是方向*向量*而不是旋转,留在 `v2` 里就好:`fromAngle` / `angle` /`rotate`。完整的工作示例(炮塔朝向光标)见[变换、单位与坐标系](/docs/zh-cn/core-concepts/transforms/#2d-旋转)。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdxindex c4e4cdc0d..d4e9ca9e7 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx@@ -6,7 +6,7 @@ description: 联网完整指南——跨平台 WebSocket(createSocket)与类型import { Aside } from '@astrojs/starlight/components';Estella 附带一个**跨平台 WebSocket**。`createSocket` 为平台返回正确的实现——Web 上是浏览器-`WebSocket`,微信小游戏上是 `wx.connectSocket`——都在一套 API 之后。在它之上,`NetChannel`+`WebSocket`,微信小游戏上是 `wx.connectSocket`,Node 下是 `ws`,原生与其他小游戏宿主用各自的 socket——都在一套 API 之后。在它之上,`NetChannel`增加类型化消息与请求/响应。## 连接与收发消息@@ -144,7 +144,7 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // 每 tick 输入上再用 `flushPendingRegistrations(app)` 装上项目在模块作用域注册的东西(与正式 Web运行时同一道门),权威端跑的就是项目自己的系统,而不是它的副本。- **重连目前由你负责**:`Replicated.owner` 是*连接* id,玩家重连会拿到新的一个。- SDK 没有任何身份能跨越断开的 socket,所以稳定玩家 id、会话令牌和宽限期都归你的游戏。+ SDK 没有任何身份能跨越断开的 socket,所以稳定玩家 id、会话令牌和宽限期都归你的游戏。(下面的请求/应答[会话层](#异步在线游戏会话层)确实会重连并保留订阅,但它与状态复制是两套东西。)完整范式(复制、每 tick 输入、客户端预测)见 **Multiplayer Arena** 示例(约 130 行)。它的 `server/` 目录就是专用服务器那一半:同一个项目,无头运行,后面是一条真实的 WebSocket。@@ -251,6 +251,44 @@ clientNet.client.sendInput({ move: { x: 1, y: 0 } }); // pawn 立刻动渐出(视觉误差每 `halfLife` 秒减半)而不是硬 snap;加 `maxError` 让真正的传送仍然瞬移。纯表现层——模拟状态不可能因此漂移。+## 异步在线游戏——会话层++状态复制让服务器与客户端共享一个 tick。而**异步**玩共享世界的游戏(城建、卡牌、抽卡)没有共享 tick,+需要的是在糟糕网络下仍然成立的请求与应答。这是 `esengine/session` 的职责,它独立于状态复制:++- 服务器端的 **`SessionHost`** 在服务任何请求之前先认证每个连接,限制帧大小与消息速率,给客户端发心跳,+ 并让同一玩家的新连接顶替旧连接。它不持有游戏状态:每个处理函数都从上下文里拿到玩家。+- 设备端的 **`ClientSession`** 负责拨号、断线后带退避与抖动地重连、请求发出前先等服务器就绪,+ 并让事件订阅跨重连保留。`retryNow()` 立刻重拨;`serverNow()` 给出服务器时钟。+- 每个请求都带一个**键**,所以应答丢了之后重发的请求会从记忆里应答,而不是再执行一遍+ (购买、出征)。多个服务器进程共用同一个 `IdempotencyStore`。+- `defineContract` 用 `s` 校验器(`s.object`、`s.int`、`s.string` ……)把每个请求与事件只写一次:+ 服务器据此校验每个请求,客户端校验每个应答,两端的类型也由它推出。它的 `fingerprint` 能让服务器+ 拒绝按另一份契约构建的客户端。++```typescript+import { defineContract, s, SessionHost, ClientSession, acceptWebSocket } from 'esengine/session';+import { createSocket } from 'esengine';++const api = defineContract({+ requests: { buy: { req: s.object({ item: s.string() }), res: s.object({ gold: s.int() }) } },+ events: { news: s.object({ text: s.string() }) },+});++// 服务器(Node):把每个 `ws` socket 交给 host。+const host = new SessionHost({ authenticate: (cred) => ({ playerId: String((cred as any).id) }) });+api.serve(host, { buy: async ({ item }, ctx) => ({ gold: await purchase(ctx.playerId, item) }) });+// wss.on('connection', (socket) => acceptWebSocket(host, socket));++// 客户端:整局游戏只有这一个对象,不管链路断多少次。+const session = new ClientSession({ connect: () => createSocket({ url: 'wss://example.com/play' }), credentials: () => ({ id: 'p1' }) });+await session.start();+const { gold } = await api.client(session).buy({ item: 'sword' });+```++会话可以用 protobuf 代替 JSON(客户端 `wire: 'pb'`,host 端同名 `wire`;`proto()` / `protoAs()` 把 `.proto`+消息带进契约),调试时仍可按 JSON 读。+## 最佳实践- 超出简单套接字的场景**用 `NetChannel`**——按类型路由和 RPC 胜过一个巨大的 `'message'` 处理器 switch。diff --git a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdxindex e391c9b1c..c671a0922 100644--- a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx@@ -185,8 +185,8 @@ const focusDebug = defineSystem([Res(FocusManager)], (focus) => {```<Aside type="note">- 手柄导航未内置于焦点系统——焦点环由 `Tab` / `Enter` / `Space` / `Escape` 和- 方向键驱动。手柄菜单请用[输入映射](/docs/zh-cn/scripting/input/)自行驱动选择,+ 手柄导航未内置于焦点系统——焦点环只随 `Tab` / `Shift+Tab` 移动+ (`Enter` / `Space` / `Escape` 与方向键作用于当前聚焦的控件)。手柄菜单请用[输入映射](/docs/zh-cn/scripting/input/)自行驱动选择,直接调用控件状态。</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdxindex 7b1270024..647ced23d 100644--- a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx@@ -241,8 +241,8 @@ world.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvent| `horizontal` / `vertical` | `false` / `true` | 哪些轴可滚。 || `movement` | `Clamped` | `Elastic` 会在两端过冲再弹回。 || `wheelSpeed` | `1` | 滚轮增量的倍率。 |-| `dragScroll` | `true` | 拖拽/触摸抓取,带惯性甩动。 |-| `decelerationRate` | `0.135` | 甩动速度每秒保留的比例;`0` 表示松手即停。 |+| `dragScroll` | `true` | 拖拽/触摸抓取;松手后的惯性甩动只在 `Elastic` 下生效。 |+| `decelerationRate` | `0.135` | `Elastic` 下甩动速度每秒保留的比例;`0` 表示松手即停。`Clamped` 下该组件松手即停。 |```ts// 一个在固定盒子里纵向滚动的列表。diff --git a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdxindex fc923c117..8bb5b5858 100644--- a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx@@ -351,8 +351,9 @@ world.insert(field, TextInput, { placeholder: 'Name', font: gameFont, textAlign:超出盒宽的内容**裁剪到盒内并横向滚动**,输入时光标始终可见。<Aside type="note">- 文本输入只在**播放模式**运行,且需要浏览器 DOM(它驱动一个隐藏的原生 textarea- 以支持 IME)——在编辑器的编辑视图中是惰性的。+ 文本输入只在**播放模式**运行,且需要平台提供的文本编辑面:Web 上是隐藏的原生+ textarea(用于 IME),原生构建里是宿主自己的文本模型(SDL 输入与 IME)。无界面宿主+ 会渲染输入框但无法输入,编辑器的编辑视图中也是惰性的。</Aside>## 列表与滚动diff --git a/docs/astro/src/content/docs/zh-cn/world/generation.mdx b/docs/astro/src/content/docs/zh-cn/world/generation.mdxindex 49bac35eb..28c2f7704 100644--- a/docs/astro/src/content/docs/zh-cn/world/generation.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/generation.mdx@@ -80,7 +80,7 @@ registerWorldRules({| `sink` | 下沉进地面多深,世界单位(石头埋在土里的底面)。 || `unit` | 一个网格单位对应多少世界单位:按米建模的植物放在厘米世界里就是 100。配方的 `scale` 这时是相对模型的大小。 |-植物由与[手摆植物](/docs/zh-cn/graphics/foliage/#手摆植物)相同的机制按格子生长:区块立刻出现,之后几帧里逐步填满,每个网格只占帧预算里的几毫秒。远景版本是单独的一个图层,一直铺到它们中最远的那个,在镜头比其种类自身绘制距离更远时显示,所以图层的 `drawDistance` 是它的植物以本来面目绘制的距离,不是世界能看多远。建在区域型地形上的世界到地形边缘为止。植物是直立的,不随地面倾斜。+植物由与[手摆植物](/docs/zh-cn/graphics/foliage/#手摆植物)相同的机制按格子生长:区块立刻出现,之后几帧里逐步填满,每个网格只占帧预算里的几毫秒。远景版本是单独的一个图层,一直铺到它们中最远的那个,在镜头比其种类自身绘制距离更远时显示,所以图层的 `drawDistance` 是它的植物以本来面目绘制的距离,不是世界能看多远。建在区域型地形上的世界到地形边缘为止。### 层diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex b331a2af5..e4786e35d 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -103,9 +103,9 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {| 属性 | 类型 | 默认 | 说明 ||---|---|---|---|-| `shape` | `EmitterShape` | `Cone` | `Point` / `Circle` / `Rectangle` / `Cone`。 |+| `shape` | `EmitterShape` | `Cone` | `Point` / `Circle` / `Box` / `Cone` / `Sphere` / `Hemisphere`。 || `shapeRadius` | number | `100` | `Circle` / `Cone` 的半径。 |-| `shapeSize` | Vec2 | `{100, 100}` | `Rectangle` 的盒子范围。 |+| `shapeSize` | Vec3 | `{100, 100, 0}` | `Box` 的盒子范围(`z` 为 `0` 就是 2D 发射器用的平面矩形)。 || `shapeAngle` | number | `25` | `Cone` 的锥半角(°)。 |### 速度与力 (Velocity & forces)@@ -114,9 +114,9 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {|---|---|---|---|| `speedMin` | number | `500` | 最慢初速度。 || `speedMax` | number | `500` | 最快初速度。 |-| `angleSpreadMin` | number | `0` | 发射方向弧的起始(°)。 |-| `angleSpreadMax` | number | `360` | 发射方向弧的结束(°)。 |-| `gravity` | Vec2 | `{0, 0}` | 施加到每个粒子的恒定加速度。 |+| `angleSpreadMin` | number | `0` | 发射方向弧的起始(°),在发射器局部 XY 平面内。只对 `Point` 和 `Box` 生效。 |+| `angleSpreadMax` | number | `360` | 发射方向弧的结束(°)。只对 `Point` 和 `Box` 生效。 |+| `gravity` | Vec3 | `{0, 0, 0}` | 施加到每个粒子的恒定加速度。 || `damping` | number | `0` | 每秒速度阻尼(`0` = 无)。 || `addedVelocityMin` / `addedVelocityMax` | Vec3 | `{0,0,0}` | 每个粒子在自身速度之上额外带的速度,出生时在两端之间随机取值。重力、阻尼、噪声和速度上限都不作用于它。仅 CPU 模拟。 || `speedLimit` | number | `0` | 粒子凭自身速度能达到的最快速度(`0` = 不限)。更快的会被拉回到上限附近。仅 CPU 模拟。 |@@ -218,12 +218,15 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {| 形状 | 使用 | 行为 ||---|---|---|| `Point` | — | 所有粒子在实体原点生成。 |-| `Circle` | `shapeRadius` | 在圆盘内生成;方向向外辐射。 |-| `Rectangle` | `shapeSize` | 在矩形盒内生成。 |+| `Circle` | `shapeRadius` | 在发射器自己所在平面的圆盘内生成;方向向外辐射。 |+| `Box` | `shapeSize` | 在盒内生成(`shapeSize.z` 为 `0` 时是平面矩形)。 || `Cone` | `shapeRadius`、`shapeAngle` | 在锥内生成——一束有方向的喷射(喷泉、推进器)。 |+| `Sphere` | `shapeRadius` | 在球内生成;方向向外辐射。 |+| `Hemisphere` | `shapeRadius` | 在以局部 +Y 为轴的半球内生成;方向向外辐射。 |-`angleSpreadMin…Max` 弧进一步约束发射方向,所以任何形状都能定向(例如一个只向上发射的-`Circle`,用 `0…180`)。+有方向的形状沿发射器局部 +Y 指向,所以没旋转的发射器向上喷,旋转实体就能给它瞄准,3D 里也一样。`Point` 和 `Box` 自己没有方向:+由 `angleSpreadMin…Max` 弧(在发射器局部 XY 平面内)决定朝哪边发射,所以只向上发射的 `Point` 用 `0…180`。`Circle`、`Cone`、`Sphere`、+`Hemisphere` 自带方向,会忽略这条弧。## 随生命的颜色与尺寸@@ -309,12 +312,13 @@ const recolor = defineSystem([Res(Particle)], (particles) => {决定每次子爆发生成多少粒子。把父级的 `subEmitter` 指向那个子实体:```typescript-import { SubEmitterTrigger } from 'esengine';+import { EmitterShape, SubEmitterTrigger } from 'esengine';// 爆发模板 —— 一个只在被触发时才发射的普通发射器。const shell = cmds.spawn().insert(Transform, {}).insert(ParticleEmitter, {+ shape: EmitterShape.Point, // 自己没有方向:火星四散rate: 0, playOnStart: false, burstCount: 44, // 每次爆发 44 颗火星lifetimeMin: 0.6, lifetimeMax: 1.1, speedMin: 160, speedMax: 340,startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },@@ -325,6 +329,7 @@ const shell = cmds.spawn()cmds.spawn().insert(Transform, { position: { x: 0, y: -230, z: 0 } }).insert(ParticleEmitter, {+ shape: EmitterShape.Point,rate: 2.5, lifetimeMin: 1.4, lifetimeMax: 1.8, speedMin: 560, speedMax: 660,angleSpreadMin: 84, angleSpreadMax: 96,subEmitter: shell,@@ -419,8 +424,8 @@ cmds.spawn()射渐隐而不是永远蹦跳。<Aside type="note">- 这是单一水平地面 —— 最常见的情形(一条地平线)。对任意几何体和瓦片地图的碰撞走物理- 世界,是另一条可选路径。和力场一样,地面碰撞只作用于**世界空间**粒子。+ 这是单一水平地面 —— 最常见的情形(一条地平线)。对墙体、刚体和瓦片地图碰撞体的碰撞走物理+ 世界(`Physics2D` / `Physics3D`),是另一条可选路径:见[场景碰撞](#场景碰撞)。和力场一样,地面碰撞只作用于**世界空间**粒子。</Aside>## 模拟空间diff --git a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdxindex 5ac9b970e..d96b934f6 100644--- a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx@@ -153,6 +153,7 @@ id——在此之前它是被静默丢弃的,唯一的症状就是每个实例| `parent` | Entity | 把实例嵌套到该实体下。 || `overrides` | override[] | 逐实例的组件值改动。 || `baseUrl` | string | 解析预制体资源的基 URL。 |+| `scene` | boolean | 默认 `true`:生成出来的东西属于落地时处于活动的场景,随它卸载。想让它比所在区域活得久就传 `false`。 || 结果字段 | 说明 ||---|---|diff --git a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx b/docs/astro/src/content/docs/zh-cn/world/streaming.mdxindex e0e8b2ec0..d52cd37c3 100644--- a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/streaming.mdx@@ -110,7 +110,7 @@ main.esscene ──cook──▶ main.esscene 持久世界**Residency 拥有"存在",不拥有"延续"。** 卸载的格子会丢掉运行时状态,重新加载会按编排内容重建。你走开时只剩 25 点血的敌人,回来时是满血的。真正留下来的是实体的编排身份,-以后的存档系统会建在它上面。+存档系统可以建在它上面(引擎不替你保存每个格子的状态)。## 程序化区块@@ -150,6 +150,10 @@ report.loadCount; // 启动以来带进来过多少个地方## 这一版不做什么-格子通过游戏本来就在用的场景加载路径异步到达,但还没有优先级、预取和预算:一个大格子-到达时就是一次卡顿。没有 HLOD,所以不常驻的地方在远处根本没有任何表示。导航网格不流送-——世界尺寸的 navmesh 一直常驻。纹理流送同样没有,世界原点也从不重定基准。+格子通过游戏本来就在用的场景加载路径异步到达。它们有先后(来源正要走进的格子先于只是可能走进的,近的先)+,也可以用 `prefetchRadius` 提前准备,但没有准入预算:一个大格子到达时仍然是一次卡顿。+对流送的格子没有通用的 HLOD——没有东西把一个格子烘成一个远景代理,所以不常驻的格子在远处根本没有任何表示。+有些内容自带远景版本:地面([地形](/docs/zh-cn/graphics/terrain/)是按距离切分的四叉树,画到 `drawDistance`;+星球一直画到地平线),以及植物([植被](/docs/zh-cn/graphics/foliage/)和 `PlacedFoliage` 的远景交叉面片,+还有生成世界里植物的远景版本),它们让整片区域一次就立起来。导航网格不流送——世界尺寸的 navmesh 一直常驻。+纹理流送同样没有,世界原点也从不重定基准(`setRenderOriginStep` 让远离原点处的*绘制*保持精确,见[相机](/docs/zh-cn/graphics/camera/))。diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex d1a977a39..9f30c446d 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -122,7 +122,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {UIVisual: { category: 'ui', summary: 'What a UI node actually paints — a colour, a texture, or a nine-sliced sprite.', doc: 'ui/overview', anchor: 'uivisual-and-uimask', anchorZh: 'uivisual-与-uimask' },UIMask: { category: 'ui', summary: "Clips descendants to this node's rect, with an optional alpha cutoff.", doc: 'ui/lists', anchor: 'clipping--uimask', anchorZh: '裁剪--uimask' },ContentRect: { category: 'ui', summary: 'The rectangle world content occupies — a size and the pivot the transform sits on — that its sprite, text and clip mask follow.', doc: 'ui/overview', anchor: 'contentrect--a-rectangle-for-world-content', anchorZh: 'contentrect--世界内容的矩形' },- RectAnchors: { category: 'ui', summary: 'Pins content placed by its transform to the edges or the centre of its parent\'s ContentRect, or of the screen: each axis stretched, pinned to an edge, or centred, with margins in units or as a fraction.', doc: null },+ RectAnchors: { category: 'ui', summary: 'Pins content placed by its transform to the edges or the centre of its parent\'s ContentRect, or of the screen: each axis stretched, pinned to an edge, or centred, with margins in units or as a fraction.', doc: 'ui/overview', anchor: 'rectanchors--world-content-that-follows-its-parent', anchorZh: 'rectanchors--跟随父级的世界内容' },UIScroll: { category: 'ui', summary: 'Scrollable content inside a clipped viewport, with momentum and scrollbars.', doc: 'ui/overview', anchor: 'scrolling', anchorZh: '滚动' },FlexContainer: { category: 'ui', summary: 'Lays children out along an axis — direction, justification, alignment, wrapping and gaps.', doc: 'ui/layout', anchor: 'flexcontainer--laying-out-children', anchorZh: 'flexcontainer排布子项' },Interactable: { category: 'ui', summary: 'Makes a UI node hit-testable, so pointer events can land on it.', doc: 'ui/interaction', anchor: 'hit-testing-interactable--uiinteraction', anchorZh: '命中测试interactable--uiinteraction' },