Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs(editor): a manual chapter was hiding behind one sidebar link

yhhd35589aa8923
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index a12fd8886..d1acced3c 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -137,7 +137,14 @@ export default defineConfig({
translations: { 'zh-CN': '编辑器' },
collapsed: true,
items: [
- { label: 'The Editor', translations: { 'zh-CN': '编辑器' }, slug: 'editor/overview' },
+ { label: 'Overview', translations: { 'zh-CN': '总览' }, slug: 'editor/overview' },
+ { label: 'Viewport & Editing Modes', translations: { 'zh-CN': '视口与编辑模式' }, slug: 'editor/viewport' },
+ { label: 'Building a Scene', translations: { 'zh-CN': '搭建场景' }, slug: 'editor/scenes' },
+ { label: 'Content Browser', translations: { 'zh-CN': '内容浏览器' }, slug: 'editor/content-browser' },
+ { label: 'Play in the Editor', translations: { 'zh-CN': '编辑器内运行' }, slug: 'editor/play' },
+ { label: 'Asset Editors', translations: { 'zh-CN': '专用编辑器' }, slug: 'editor/asset-editors' },
+ { label: 'Project Settings', translations: { 'zh-CN': '项目设置' }, slug: 'editor/settings' },
+ { label: 'Keyboard Shortcuts', translations: { 'zh-CN': '键盘快捷键' }, slug: 'editor/shortcuts' },
],
},
{
diff --git a/docs/astro/scripts/verify-doc-links.mjs b/docs/astro/scripts/verify-doc-links.mjs
index c51c03506..4fe726941 100644
--- a/docs/astro/scripts/verify-doc-links.mjs
+++ b/docs/astro/scripts/verify-doc-links.mjs
@@ -21,6 +21,8 @@ import { dirname, join, relative, sep } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const DIST = join(here, '..', 'dist');
const BASE = '/docs';
+/** Root-relative paths that legitimately sit outside the docs base. */
+const EXTERNAL_ROOTS = ['/favicon', '/_astro/', '/pagefind/', '/sitemap'];
/** Every .html file the build emitted. */
function htmlFiles(dir) {
@@ -73,6 +75,18 @@ function main() {
// every locale it gets mirrored into (hence a segment test, not a prefix).
if (relative(DIST, page).split(sep).includes('api-ts')) continue;
const html = readFileSync(page, 'utf8');
+ // Every page on this site lives under /docs. A root-relative href that does
+ // not is a typo that no amount of resolving will fix — `/zh-cn/docs/x/` for
+ // `/docs/zh-cn/x/` renders as a link off the site, and checking only
+ // well-formed ones is how two of those survived.
+ for (const m of html.matchAll(/href="(\/(?!docs\/)[^"?:]*)"/g)) {
+ const target = m[1];
+ if (target === '/' || EXTERNAL_ROOTS.some((p) => target.startsWith(p))) continue;
+ checked++;
+ const problem = `${target} (root-relative, but every page is under ${BASE})`;
+ if (!dead.has(problem)) dead.set(problem, new Set());
+ dead.get(problem).add(relative(DIST, page).replaceAll(sep, '/'));
+ }
for (const m of html.matchAll(/href="(\/docs\/[^"?]*)"/g)) {
const [path, fragment] = m[1].split('#');
checked++;
diff --git a/docs/astro/src/content/docs/editor/asset-editors.mdx b/docs/astro/src/content/docs/editor/asset-editors.mdx
new file mode 100644
index 000000000..b024252bb
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/asset-editors.mdx
@@ -0,0 +1,32 @@
+---
+title: Asset editors
+description: "The document editors behind a double-click: the Sequencer, the tilemap painter, the tileset editor, and the state-machine, behavior-tree and material graphs."
+---
+Double-click an asset in the Content Browser to open its editor in a document tab.
+
+- **Sequencer** — a timeline / curve editor for keyframe animation. See
+ [Timeline](/docs/animation/timeline/).
+- **Tilemap painter** — tools for **brush, erase, rectangle, line, bucket, select,
+ eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**
+ (`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode** (`D`). The
+ palette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps can
+ be **orthogonal, isometric, staggered, or hexagonal**. See
+ [Tilemaps](/docs/world/tilemaps/).
+- **Tileset editor** — author per-tile **collision** (box, circle, polygon, slope
+ presets; one-way / sensor / material modifiers) with **direct-manipulation** shape
+ editors on a magnified tile: drag a circle's **centre or radius**, **click-add / drag /
+ click-delete** a polygon's **vertices**, and pick a **one-way** platform's solid side
+ (top / bottom / left / right) — resizing keeps the sensor / material / density modifiers.
+ Also **terrain** sets for autotiling (edge/corner peering or multi-color **corner
+ Wang**), per-tile **probability** weights and properties, and **animated tiles** — drag
+ frame thumbnails to **reorder**, or set the whole loop to **one uniform duration**, with
+ a live preview.
+- **State Machine** (`.esfsm`) and **Behavior Tree** (`.esbt`) editors — visual graphs
+ for AI. See [Gameplay AI](/docs/gameplay/ai/).
+- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See
+ [Materials & Shaders](/docs/graphics/materials/).
+
+The State Machine and Behavior Tree editors share a common node canvas: **middle-drag**
+to pan, **wheel** to zoom toward the cursor, drag an output handle onto another node to
+connect them, click to select a node or edge, **Delete** to remove it, and right-click
+the canvas to add a node at the cursor.
diff --git a/docs/astro/src/content/docs/editor/content-browser.mdx b/docs/astro/src/content/docs/editor/content-browser.mdx
new file mode 100644
index 000000000..1dd09c9a8
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/content-browser.mdx
@@ -0,0 +1,31 @@
+---
+title: The Content Browser
+description: "Your project's asset explorer — creating and importing assets, per-asset actions, and Find Usages."
+---
+The Content Browser is your project's asset explorer. Its **create** menu makes new
+assets 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 Script…** is the one that writes more than a file: a module nothing imports is
+never bundled and its component never reaches Add Component, so the dialog also adds
+the one line in your project's script entry that pulls it in — which entry depending
+on whether you're making a component or a system. See
+[Scripting](/docs/scripting/overview/#the-new-script-dialog).
+
+**Import** by dragging files in from Finder / Explorer, or via Import…. Each asset gets
+a `.meta` sidecar the first time it's seen. Per-asset context actions include Rename,
+Duplicate, Copy Path, Copy Reference, **Find Usages**, Show in Explorer, and Delete.
+Rename, move, and duplicate each post a toast with an **Undo** action — and renaming or
+moving an asset rewrites its references in every open document, so nothing dangles.
+**Delete** first lists every scene, prefab, and asset that references the file (so you
+know exactly what breaks), then moves it to the OS trash — still recoverable with Undo.
+The folder tree is fully keyboard-driven — arrows walk and collapse/expand, Enter opens
+a folder.
+
+**Find Usages** — right-click an asset, or click the reference count in the Inspector's
+asset details — lists everywhere a texture, material, prefab, or scene is referenced,
+across the on-disk dependency graph *and* the unsaved open scene.
diff --git a/docs/astro/src/content/docs/editor/overview.mdx b/docs/astro/src/content/docs/editor/overview.mdx
index 5432003e8..0eaac832b 100644
--- a/docs/astro/src/content/docs/editor/overview.mdx
+++ b/docs/astro/src/content/docs/editor/overview.mdx
@@ -3,7 +3,7 @@ title: The Editor
description: A tour of the Estella editor — the docked workspace, the viewport and its transform gizmos, building scenes with the Outliner and Details panels, the Content Browser, play-in-editor, the specialized asset editors, and project settings.
---
-import { Aside } from '@astrojs/starlight/components';
+import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';
The Estella editor is a desktop application (Electron + React) with a UE5-style
**dockable workspace**. You build scenes visually, tune components in an inspector,
@@ -61,367 +61,20 @@ from anywhere with **Ctrl / ⌘ + Space** (the *Content Drawer*).
can't mutate your edit-mode world. Stopping returns you to exactly the scene you had.
</Aside>
-## The viewport
+## The rest of this chapter
-The viewport is where you place and manipulate entities.
+The tour above is the shape of the tool. The pages below are the parts you come
+back to.
-**Navigation**
-
-- **Pan** — drag with the middle or right mouse button.
-- **Zoom** — scroll the mouse wheel (zooms toward the cursor).
-- **Frame Selected** — press **F** to center and fit the selection.
-
-**Selecting**
-
-- **Click** an entity to select it; **Shift-click** to toggle it in a multi-selection.
-- Drag on **empty space** to **marquee** box-select everything inside.
-- Press **Esc** to cancel an in-progress drag, then to clear the selection.
-
-**Transforming** — pick a tool from the toolbar (or its shortcut) and drag a gizmo
-handle:
-
-| Tool | Shortcut | Gizmo |
-|---|---|---|
-| Select | `Q` | Pick / marquee only, no transform handles. |
-| Move | `W` | Axis arrows (X / Y) plus a center plane for free move. |
-| Rotate | `E` | A rotation ring. |
-| Scale | `R` | Axis boxes plus a uniform-scale center. |
-
-Dragging a handle transforms the whole selection as one, about a shared pivot, and
-each drag is a single undo step. **Alt-drag** a selection to duplicate it and drag the
-copies. Nudge the selection with the **arrow keys** (one grid step; hold **Shift** for
-×10).
-
-**Align & distribute** — select two or more entities and a strip of alignment buttons
-appears in the viewport overlay: align **left / centre / right** edges and **top / middle /
-bottom** edges. With three or more selected, two **distribute** buttons even out horizontal
-or vertical spacing. Each is a single undo step and works across every entity kind (sprites,
-UI nodes, gizmo-only entities alike).
-
-**Snapping** — toggle snapping from the viewport's Snap dropdown and set the grid step,
-rotation angle, and scale increment.
-
-**Show Flags** — a viewport dropdown toggles the Grid, Gizmos, Physics, and the perf
-overlay, plus World/Local axis orientation and Pivot-vs-Center. Entities that don't
-render — Cameras, `Light2D`, colliders, joints, particle emitters — are drawn as
-gizmos in edit mode (icon, view rect, light reach/cone, collider outline, joint
-anchor links) so you can see and place them; many carry drag handles that write
-their fields directly (light radius, collider size, emitter shape, joint anchors).
-
-## Editing modes
-
-The Activity Bar's top three icons switch the **editing mode** — **Scene**, **UI**, or
-**Tilemap**. The mode also *follows your selection*: pick a `Canvas` or `UINode` and the
-editor suggests **UI** mode, a `TilemapLayer` suggests **Tilemap** — switching that mode's
-tools and viewport aids **without** disturbing your panel layout. To open a mode's
-companion panels (UI Widgets, the Tilemap painter), click its Activity Bar icon or the
-viewport's mode chip; that also **pins** the mode as a sticky lock that ordinary selection
-clicks won't clear — re-click it to go back to following the selection.
-
-**The design frame + device preview.** A scene is authored against a **design resolution** —
-a fixed reference size (e.g. `1920 × 1080` landscape or `750 × 1334` portrait). This is a
-**project-level** value (Project Settings → Display), not a UI-layer one: the viewport's
-**Design** and **Device** controls work in **every** editor mode (Scene / UI / Tilemap), so
-you can preview a gameplay-only scene on a real device **without** a UI Canvas. When the
-scene has a Canvas, UI additionally lays out inside the frame per its scale mode.
-
-- **Design** dropdown (viewport toolbar) — sets the design resolution and reframes to it
- (undoable). With a Canvas it edits that Canvas; otherwise it edits the project value.
-- **Device** dropdown — picks the **target screen** (iPhone / iPad / 1080p …) in any mode.
- While editing it draws that screen's aspect as letterbox bars + safe-area insets over
- your scene; when you press **Play** the running game is letterboxed to the same shape,
- in the viewport and in the **Game** panel alike. It never changes your design
- resolution — it changes what you are looking at it *through*.
-- **Orientation** (same dropdown) — swaps the device's width and height. It applies to a
- **device**, so it is disabled while `Design` is selected: with no screen simulated
- there is nothing to rotate.
-- **Camera Fit** (Project Settings → Display) — how the **main camera** scales the design
- resolution, independent of any UI Canvas. `None` (default) keeps the camera's own
- orthoSize; any other mode letterboxes the game the same way on every device, and the
- device preview then shows the **real** framing (WYSIWYG for gameplay, not just UI).
-
-**One screen, edit and run.** The `Design` entry is the "no simulation" choice: the game
-fills whatever space the panel has, which is what authoring for desktop wants. Pick any
-real device and both the edit overlay and the running game commit to its shape — so a
-project authored for a phone is never only ever *run* at whatever aspect the dock
-happened to be dragged to.
-
-![A scene running in the viewport, framed to the selected target screen rather than to the panel's own shape](../../../assets/guides/en/game-target-screen.png)
-
-### Project screen presets
-
-The built-in device list is a guess. A team that ships to specific hardware corrects it
-in **Project Settings → Display → Screen presets**: add a row with an id, a name and the
-portrait size, and it joins the dropdown for everyone who opens the project.
-
-- **Id** is what a saved selection resolves through, so keep it stable. Reusing a built-in
- id (`iphone`, `ipad`, `1080p`, `720p`) **replaces** that built-in rather than sitting
- beside it — which is how a studio makes "iPhone" mean the exact handset it tests on.
-- **Sizes are stored portrait** (width ≤ height), like the built-ins, so the orientation
- toggle means the same thing for every screen.
-- **Safe area** (the row's ▸ expander) sets the notch / home-indicator insets in device
- pixels. Leave them at zero and nothing is written to the project file — the viewport's
- *Safe area* overlay then has nothing to draw for that screen.
-
-![Project Settings showing a screen preset row with its safe-area insets expanded](../../../assets/guides/en/settings-screen-presets.png)
-
-Presets live in `project.esproject`, so they are shared through version control:
-
-```json title="project.esproject"
-{
- "screenPresets": [
- { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
- {
- "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
- "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }
- }
- ]
-}
-```
-
-## Building a scene
-
-### Creating entities
-
-There are several ways to add an entity:
-
-- **Entity → Add Entity** (or the toolbar) drops a blank Transform entity.
-- **Create…** 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
- controls) — **your own project components**, and any **`.esprefab` prefab** in the
- project. Every create path (this menu, drag-and-drop, and the automation surface) runs
- the same pipeline, so each spawn is a single undo step.
-- **Right-click in the Outliner** for the same actions in context, plus folders,
- parenting, and prefab creation.
-- **Drag from the Content Browser** — drop an image to spawn a Sprite, or a `.esprefab`
- to instantiate it.
-
-### The World Outliner
-
-The Outliner is the scene's hierarchy. You can:
-
-- Reparent by dragging entities onto one another, and organize with **folders**.
-- **Type to jump** — with the tree focused, type the first letters of a name to
- jump to the matching entity.
-- **Rename** with `F2`, **Duplicate** with Ctrl/⌘ + D, **Delete** with Delete.
-- **Hide/Show** and **Lock/Unlock** entities (independent of whether the component is
- enabled at runtime). Hiding takes the entity out of the edit viewport — sprites,
- skeletons, tilemaps, particles, lights and all — without editing the scene the game
- loads. Locking leaves it visible and selectable but gives it no handles: the
- viewport won't pick it, and the transform gizmo won't appear for it.
-- **Create Prefab** from a selection, then drop instances back into the scene.
-
-### The Details panel
-
-Details is the inspector for the selection. It lists every component on the entity and
-its fields — driven by the engine's reflection metadata, so ranges, units, enums, and
-tooltips come straight from the component definition. Add components, edit values, and
-they're written back to the scene live. Fields enforce their constraints as you edit: a
-**required** field is flagged when left empty, a numeric field is clamped to its
-declared range on write, and dropping an asset onto a slot is rejected unless its type
-matches.
-
-Each component is a **collapsible section**, and the panel remembers what you fold —
-across reselects *and* editor restarts — so an inspector stays as tidy as you leave it.
-Rarely-touched "chrome" (a widget's `Focusable` and `ThemeStyle` tags) starts folded.
-
-Where a visual control beats a row of raw numbers, Details shows a **purpose-built
-widget** — most of them for UI nodes:
-
-- an **anchor** control for absolutely-positioned `UINode`s: a clickable **3×3 grid** for
- the nine point anchors (Left / Centre / Right × Top / Middle / Bottom) plus a **Stretch**
- toggle per axis;
-- a **flex** (auto-layout) widget for `FlexContainer`s: **Direction** (row / column and
- their reverses), a **3×3 alignment grid** that sets main- and cross-axis alignment in one
- click, main-axis **Distribute** (Packed / Between / Around / Evenly), and **Wrap** /
- **Stretch** toggles — with **padding** edited as a four-edge `sides` control;
-- an inline **Controllers** strip that pulls per-node state authoring into the inspector:
- pick a state page and *gear* a field to bind it, all without leaving the panel (see
- [UI controllers](/docs/ui/controllers/));
-- for a **material**, a **Shader** picker to swap the bound shader — a built-in template or
- a project `.esshader` — see
- [Materials & Shaders](/docs/graphics/materials/#choosing--sharing-shaders-in-the-editor).
-
-![The Details panel showing the anchor grid and layout controls for a UI node](../../../assets/guides/en/inspector-flex.png)
-
-*A UI node's inspector: the **In Layout / Absolute** toggle, the clickable **3×3 anchor grid** (with per-axis Stretch), and `Display: Flex` — visual controls in place of raw numbers.*
-
-Details also serves as the **asset inspector**: select an asset in the Content Browser to
-edit its import settings or, for a material, its parameters.
-
-**Dragging a 9-slice border.** A texture's slice border decides where a `NineSlice` panel
-keeps its corners crisp, and typing four numbers means guessing at them. Select the
-texture and drag the four guides directly on the preview instead — the numeric fields stay
-in sync, so you can nudge one edge exactly after eyeballing the rest.
-
-Import settings describe the **asset**, not the scene that happens to use it, and they now
-reach every place the texture is drawn: the edit viewport, Play (in the viewport and in
-the Game panel), and a packaged build. A frame that slices correctly while you author it
-slices correctly in the shipped game.
-
-![Dragging the 9-slice border guides on a texture in the asset inspector](../../../assets/guides/en/nine-slice-drag.png)
-
-## The Content Browser
-
-The Content Browser is your project's asset explorer. Its **create** menu makes new
-assets 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 Script…** is the one that writes more than a file: a module nothing imports is
-never bundled and its component never reaches Add Component, so the dialog also adds
-the one line in your project's script entry that pulls it in — which entry depending
-on whether you're making a component or a system. See
-[Scripting](/docs/scripting/overview/#the-new-script-dialog).
-
-**Import** by dragging files in from Finder / Explorer, or via Import…. Each asset gets
-a `.meta` sidecar the first time it's seen. Per-asset context actions include Rename,
-Duplicate, Copy Path, Copy Reference, **Find Usages**, Show in Explorer, and Delete.
-Rename, move, and duplicate each post a toast with an **Undo** action — and renaming or
-moving an asset rewrites its references in every open document, so nothing dangles.
-**Delete** first lists every scene, prefab, and asset that references the file (so you
-know exactly what breaks), then moves it to the OS trash — still recoverable with Undo.
-The folder tree is fully keyboard-driven — arrows walk and collapse/expand, Enter opens
-a folder.
-
-**Find Usages** — right-click an asset, or click the reference count in the Inspector's
-asset details — lists everywhere a texture, material, prefab, or scene is referenced,
-across the on-disk dependency graph *and* the unsaved open scene.
-
-## Play-in-editor
-
-The **Play** controls in the toolbar run your game:
-
-- **Play** starts the game; while running the same button becomes **Stop**, with
- **Restart** and **Pause/Resume** as side buttons.
-- The play-mode dropdown chooses **Play In Viewport** (the game hosts over the viewport)
- or **Play In New Window** (a dedicated **Game** tab), and toggles **Maximize Viewport on
- Play** — which hands the whole workspace to the running game and restores your layout on
- Stop.
-- A running game reads as a soft accent ring around the viewport (amber, with the frame
- dimmed, when paused) — not a badge over the game.
-- Shortcuts: **F5** play, **Esc** stop, **F6** pause/resume, **Shift+F5** restart, and
- **F11** to maximize/restore the viewport at any time.
-
-Because play uses an isolated realm — the same runtime that ships your game — what you
-see in play is what a player gets.
-
-## Autosave & recovery
-
-The editor periodically snapshots your **unsaved** documents — only when there are
-unsaved changes and no Play session is running — so a crash or power loss never costs
-more than the last few moments of work. A snapshot is kept in your project's workspace
-folder and never counts as a real save. The next time you open the project, if a
-snapshot is newer than the file on disk, the editor offers to **restore** it; saving the
-document supersedes its snapshot. This sits alongside the crash minidump and the
-automatic reload if the GPU render process is lost.
-
-## Specialized editors
-
-Double-click an asset in the Content Browser to open its editor in a document tab.
-
-- **Sequencer** — a timeline / curve editor for keyframe animation. See
- [Timeline](/docs/animation/timeline/).
-- **Tilemap painter** — tools for **brush, erase, rectangle, line, bucket, select,
- eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**
- (`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode** (`D`). The
- palette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps can
- be **orthogonal, isometric, staggered, or hexagonal**. See
- [Tilemaps](/docs/world/tilemaps/).
-- **Tileset editor** — author per-tile **collision** (box, circle, polygon, slope
- presets; one-way / sensor / material modifiers) with **direct-manipulation** shape
- editors on a magnified tile: drag a circle's **centre or radius**, **click-add / drag /
- click-delete** a polygon's **vertices**, and pick a **one-way** platform's solid side
- (top / bottom / left / right) — resizing keeps the sensor / material / density modifiers.
- Also **terrain** sets for autotiling (edge/corner peering or multi-color **corner
- Wang**), per-tile **probability** weights and properties, and **animated tiles** — drag
- frame thumbnails to **reorder**, or set the whole loop to **one uniform duration**, with
- a live preview.
-- **State Machine** (`.esfsm`) and **Behavior Tree** (`.esbt`) editors — visual graphs
- for AI. See [Gameplay AI](/docs/gameplay/ai/).
-- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See
- [Materials & Shaders](/docs/graphics/materials/).
-
-The State Machine and Behavior Tree editors share a common node canvas: **middle-drag**
-to pan, **wheel** to zoom toward the cursor, drag an output handle onto another node to
-connect them, click to select a node or edge, **Delete** to remove it, and right-click
-the canvas to add a node at the cursor.
-
-## Project settings
-
-Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are grouped:
-
-- **Editor** — Appearance (**language**, accent color, UI scale), Viewport (grid,
- snapping, gizmos), **Keyboard Shortcuts** (every shortcut below is rebindable
- here), and Console.
-- **Project** (saved into `project.esproject`):
- - **Display** — the project design resolution (seeds new Canvases + drives the device
- preview in any scene), the project-wide **screen orientation** (every export target
- honors it; unset ⇒ derived from the design resolution's aspect), and the **camera fit**
- (how the main camera scales the design resolution without a UI Canvas; `None` = off).
- - **UI** — the project's widget **theme** (dark / light) and per-role **Theme
- Colors** overrides, applied identically in the editor, Play, and every export.
- See [UI widgets — theming](/docs/ui/widgets/#theming).
- - **Physics** — enable, gravity, sixteen collision-layer names and a 16×16 collision
- matrix, plus solver tuning (fixed timestep, sub-steps, contact Hz/damping/push
- speed, sleeping, continuous collision). See [Physics](/docs/gameplay/physics/).
- - **Rendering** — up to thirty-two named sorting layers that populate the inspector's
- layer dropdown, and which of them y-sort. The names are suggestions, not a limit:
- a render `layer` still accepts a number outside them.
- - **Packaging** — per-target metadata: WeChat AppID, Desktop app id / product name.
-
-### Editor language
-
-The editor ships in **English** and **简体中文** and follows your system language on
-first launch. Switch it under **Settings → Appearance → Language** — the change
-applies after a reload (the editor prompts for one). The editor's UI strings run on
-the same [localization engine](/docs/assets/localization/) your game uses at runtime.
-
-## Keyboard shortcuts
-
-`mod` is **⌘** on macOS and **Ctrl** elsewhere. All of these are rebindable under
-Settings → Keyboard Shortcuts.
-
-| Action | Shortcut |
-|---|---|
-| New Scene | `mod + N` |
-| Open Project | `mod + O` |
-| Save Scene | `mod + S` |
-| Save Scene As | `mod + shift + S` |
-| Undo / Redo | `mod + Z` / `mod + shift + Z` |
-| Duplicate | `mod + D` |
-| Copy / Cut / Paste | `mod + C` / `mod + X` / `mod + V` |
-| Delete | `Delete` / `Backspace` |
-| Select All | `mod + A` |
-| Select / Move / Rotate / Scale tool | `Q` / `W` / `E` / `R` |
-| Nudge selection (×10 with Shift) | Arrow keys |
-| Frame Selected | `F` |
-| Play · Stop | `F5` · `Esc` |
-| Pause/Resume · Restart | `F6` · `shift + F5` |
-| Maximize / restore viewport | `F11` |
-| Command Palette | `mod + shift + P` |
-| Content Drawer | `Ctrl + Space` |
-| Project Settings | `mod + ,` |
-
-The **Command Palette** (`mod + shift + P`) fuzzy-searches every runnable command —
-the fastest way to reach any action without hunting through menus.
-
-Beyond the command shortcuts, the editor is keyboard-navigable throughout: menus
-and context menus move with the arrow keys (plus type-ahead, Home/End, and `→` /
-`←` for submenus), the Outliner jumps to entities as you type, the Content
-Browser's folder tree and the tile palette both walk with arrows, and keyboard
-focus is always shown with a visible focus ring.
-
-<Aside type="tip">
- For headless automation and AI agents, the editor also exposes an
- `EditorControlSurface` (load a scene, step the sim, read the scene tree/inspector,
- capture the viewport) over an MCP server — a developer/automation surface driven from
- scripts, separate from the visual editor above.
-</Aside>
+<CardGrid>
+ <LinkCard title="Viewport & editing modes" href="/docs/editor/viewport/" description="Navigation, transform gizmos, align & distribute, and the device preview." />
+ <LinkCard title="Building a scene" href="/docs/editor/scenes/" description="Creating entities, the World Outliner, and the Details inspector." />
+ <LinkCard title="The Content Browser" href="/docs/editor/content-browser/" description="Creating and importing assets, and finding what references them." />
+ <LinkCard title="Play in the editor" href="/docs/editor/play/" description="Running the game in an isolated realm, and autosave recovery." />
+ <LinkCard title="Asset editors" href="/docs/editor/asset-editors/" description="The Sequencer, tilemap painter, tileset editor and node graphs." />
+ <LinkCard title="Project settings" href="/docs/editor/settings/" description="Editor preferences and the settings saved into your project." />
+ <LinkCard title="Keyboard shortcuts" href="/docs/editor/shortcuts/" description="Every default binding, and the Command Palette." />
+</CardGrid>
## See also
diff --git a/docs/astro/src/content/docs/editor/play.mdx b/docs/astro/src/content/docs/editor/play.mdx
new file mode 100644
index 000000000..9a8c2c6ed
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/play.mdx
@@ -0,0 +1,29 @@
+---
+title: Play in the editor
+description: "Running the game inside the editor in an isolated realm, the play-mode options, and autosave & crash recovery."
+---
+The **Play** controls in the toolbar run your game:
+
+- **Play** starts the game; while running the same button becomes **Stop**, with
+ **Restart** and **Pause/Resume** as side buttons.
+- The play-mode dropdown chooses **Play In Viewport** (the game hosts over the viewport)
+ or **Play In New Window** (a dedicated **Game** tab), and toggles **Maximize Viewport on
+ Play** — which hands the whole workspace to the running game and restores your layout on
+ Stop.
+- A running game reads as a soft accent ring around the viewport (amber, with the frame
+ dimmed, when paused) — not a badge over the game.
+- Shortcuts: **F5** play, **Esc** stop, **F6** pause/resume, **Shift+F5** restart, and
+ **F11** to maximize/restore the viewport at any time.
+
+Because play uses an isolated realm — the same runtime that ships your game — what you
+see in play is what a player gets.
+
+## Autosave & recovery
+
+The editor periodically snapshots your **unsaved** documents — only when there are
+unsaved changes and no Play session is running — so a crash or power loss never costs
+more than the last few moments of work. A snapshot is kept in your project's workspace
+folder and never counts as a real save. The next time you open the project, if a
+snapshot is newer than the file on disk, the editor offers to **restore** it; saving the
+document supersedes its snapshot. This sits alongside the crash minidump and the
+automatic reload if the GPU render process is lost.
diff --git a/docs/astro/src/content/docs/editor/scenes.mdx b/docs/astro/src/content/docs/editor/scenes.mdx
new file mode 100644
index 000000000..aea8b65ea
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/scenes.mdx
@@ -0,0 +1,84 @@
+---
+title: Building a scene
+description: "Creating entities, the World Outliner, and the Details inspector — including its purpose-built layout widgets and the asset import settings it edits."
+---
+## Creating entities
+
+There are several ways to add an entity:
+
+- **Entity → Add Entity** (or the toolbar) drops a blank Transform entity.
+- **Create…** 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
+ controls) — **your own project components**, and any **`.esprefab` prefab** in the
+ project. Every create path (this menu, drag-and-drop, and the automation surface) runs
+ the same pipeline, so each spawn is a single undo step.
+- **Right-click in the Outliner** for the same actions in context, plus folders,
+ parenting, and prefab creation.
+- **Drag from the Content Browser** — drop an image to spawn a Sprite, or a `.esprefab`
+ to instantiate it.
+
+## The World Outliner
+
+The Outliner is the scene's hierarchy. You can:
+
+- Reparent by dragging entities onto one another, and organize with **folders**.
+- **Type to jump** — with the tree focused, type the first letters of a name to
+ jump to the matching entity.
+- **Rename** with `F2`, **Duplicate** with Ctrl/⌘ + D, **Delete** with Delete.
+- **Hide/Show** and **Lock/Unlock** entities (independent of whether the component is
+ enabled at runtime). Hiding takes the entity out of the edit viewport — sprites,
+ skeletons, tilemaps, particles, lights and all — without editing the scene the game
+ loads. Locking leaves it visible and selectable but gives it no handles: the
+ viewport won't pick it, and the transform gizmo won't appear for it.
+- **Create Prefab** from a selection, then drop instances back into the scene.
+
+## The Details panel
+
+Details is the inspector for the selection. It lists every component on the entity and
+its fields — driven by the engine's reflection metadata, so ranges, units, enums, and
+tooltips come straight from the component definition. Add components, edit values, and
+they're written back to the scene live. Fields enforce their constraints as you edit: a
+**required** field is flagged when left empty, a numeric field is clamped to its
+declared range on write, and dropping an asset onto a slot is rejected unless its type
+matches.
+
+Each component is a **collapsible section**, and the panel remembers what you fold —
+across reselects *and* editor restarts — so an inspector stays as tidy as you leave it.
+Rarely-touched "chrome" (a widget's `Focusable` and `ThemeStyle` tags) starts folded.
+
+Where a visual control beats a row of raw numbers, Details shows a **purpose-built
+widget** — most of them for UI nodes:
+
+- an **anchor** control for absolutely-positioned `UINode`s: a clickable **3×3 grid** for
+ the nine point anchors (Left / Centre / Right × Top / Middle / Bottom) plus a **Stretch**
+ toggle per axis;
+- a **flex** (auto-layout) widget for `FlexContainer`s: **Direction** (row / column and
+ their reverses), a **3×3 alignment grid** that sets main- and cross-axis alignment in one
+ click, main-axis **Distribute** (Packed / Between / Around / Evenly), and **Wrap** /
+ **Stretch** toggles — with **padding** edited as a four-edge `sides` control;
+- an inline **Controllers** strip that pulls per-node state authoring into the inspector:
+ pick a state page and *gear* a field to bind it, all without leaving the panel (see
+ [UI controllers](/docs/ui/controllers/));
+- for a **material**, a **Shader** picker to swap the bound shader — a built-in template or
+ a project `.esshader` — see
+ [Materials & Shaders](/docs/graphics/materials/#choosing--sharing-shaders-in-the-editor).
+
+![The Details panel showing the anchor grid and layout controls for a UI node](../../../assets/guides/en/inspector-flex.png)
+
+*A UI node's inspector: the **In Layout / Absolute** toggle, the clickable **3×3 anchor grid** (with per-axis Stretch), and `Display: Flex` — visual controls in place of raw numbers.*
+
+Details also serves as the **asset inspector**: select an asset in the Content Browser to
+edit its import settings or, for a material, its parameters.
+
+**Dragging a 9-slice border.** A texture's slice border decides where a `NineSlice` panel
+keeps its corners crisp, and typing four numbers means guessing at them. Select the
+texture and drag the four guides directly on the preview instead — the numeric fields stay
+in sync, so you can nudge one edge exactly after eyeballing the rest.
+
+Import settings describe the **asset**, not the scene that happens to use it, and they now
+reach every place the texture is drawn: the edit viewport, Play (in the viewport and in
+the Game panel), and a packaged build. A frame that slices correctly while you author it
+slices correctly in the shipped game.
+
+![Dragging the 9-slice border guides on a texture in the asset inspector](../../../assets/guides/en/nine-slice-drag.png)
diff --git a/docs/astro/src/content/docs/editor/settings.mdx b/docs/astro/src/content/docs/editor/settings.mdx
new file mode 100644
index 000000000..a13259270
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/settings.mdx
@@ -0,0 +1,31 @@
+---
+title: Project settings
+description: "Editor preferences and the project-wide settings saved into project.esproject — display, UI theme, physics, rendering layers and packaging."
+---
+Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are grouped:
+
+- **Editor** — Appearance (**language**, accent color, UI scale), Viewport (grid,
+ snapping, gizmos), **Keyboard Shortcuts** (every shortcut below is rebindable
+ here), and Console.
+- **Project** (saved into `project.esproject`):
+ - **Display** — the project design resolution (seeds new Canvases + drives the device
+ preview in any scene), the project-wide **screen orientation** (every export target
+ honors it; unset ⇒ derived from the design resolution's aspect), and the **camera fit**
+ (how the main camera scales the design resolution without a UI Canvas; `None` = off).
+ - **UI** — the project's widget **theme** (dark / light) and per-role **Theme
+ Colors** overrides, applied identically in the editor, Play, and every export.
+ See [UI widgets — theming](/docs/ui/widgets/#theming).
+ - **Physics** — enable, gravity, sixteen collision-layer names and a 16×16 collision
+ matrix, plus solver tuning (fixed timestep, sub-steps, contact Hz/damping/push
+ speed, sleeping, continuous collision). See [Physics](/docs/gameplay/physics/).
+ - **Rendering** — up to thirty-two named sorting layers that populate the inspector's
+ layer dropdown, and which of them y-sort. The names are suggestions, not a limit:
+ a render `layer` still accepts a number outside them.
+ - **Packaging** — per-target metadata: WeChat AppID, Desktop app id / product name.
+
+## Editor language
+
+The editor ships in **English** and **简体中文** and follows your system language on
+first launch. Switch it under **Settings → Appearance → Language** — the change
+applies after a reload (the editor prompts for one). The editor's UI strings run on
+the same [localization engine](/docs/assets/localization/) your game uses at runtime.
diff --git a/docs/astro/src/content/docs/editor/shortcuts.mdx b/docs/astro/src/content/docs/editor/shortcuts.mdx
new file mode 100644
index 000000000..d7d42803e
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/shortcuts.mdx
@@ -0,0 +1,46 @@
+---
+title: Keyboard shortcuts
+description: "Every default shortcut, all of them rebindable, plus the Command Palette and the editor keyboard navigation model."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`mod` is **⌘** on macOS and **Ctrl** elsewhere. All of these are rebindable under
+Settings → Keyboard Shortcuts.
+
+| Action | Shortcut |
+|---|---|
+| New Scene | `mod + N` |
+| Open Project | `mod + O` |
+| Save Scene | `mod + S` |
+| Save Scene As | `mod + shift + S` |
+| Undo / Redo | `mod + Z` / `mod + shift + Z` |
+| Duplicate | `mod + D` |
+| Copy / Cut / Paste | `mod + C` / `mod + X` / `mod + V` |
+| Delete | `Delete` / `Backspace` |
+| Select All | `mod + A` |
+| Select / Move / Rotate / Scale tool | `Q` / `W` / `E` / `R` |
+| Nudge selection (×10 with Shift) | Arrow keys |
+| Frame Selected | `F` |
+| Play · Stop | `F5` · `Esc` |
+| Pause/Resume · Restart | `F6` · `shift + F5` |
+| Maximize / restore viewport | `F11` |
+| Command Palette | `mod + shift + P` |
+| Content Drawer | `Ctrl + Space` |
+| Project Settings | `mod + ,` |
+
+The **Command Palette** (`mod + shift + P`) fuzzy-searches every runnable command —
+the fastest way to reach any action without hunting through menus.
+
+Beyond the command shortcuts, the editor is keyboard-navigable throughout: menus
+and context menus move with the arrow keys (plus type-ahead, Home/End, and `→` /
+`←` for submenus), the Outliner jumps to entities as you type, the Content
+Browser's folder tree and the tile palette both walk with arrows, and keyboard
+focus is always shown with a visible focus ring.
+
+<Aside type="tip">
+ For headless automation and AI agents, the editor also exposes an
+ `EditorControlSurface` (load a scene, step the sim, read the scene tree/inspector,
+ capture the viewport) over an MCP server — a developer/automation surface driven from
+ scripts, separate from the visual editor above.
+</Aside>
diff --git a/docs/astro/src/content/docs/editor/viewport.mdx b/docs/astro/src/content/docs/editor/viewport.mdx
new file mode 100644
index 000000000..3c8c3972d
--- /dev/null
+++ b/docs/astro/src/content/docs/editor/viewport.mdx
@@ -0,0 +1,119 @@
+---
+title: Viewport & editing modes
+description: "Navigating the viewport, the transform gizmos, align & distribute, show flags, the Scene / UI / Tilemap modes, and the design-resolution device preview."
+---
+The viewport is where you place and manipulate entities.
+
+**Navigation**
+
+- **Pan** — drag with the middle or right mouse button.
+- **Zoom** — scroll the mouse wheel (zooms toward the cursor).
+- **Frame Selected** — press **F** to center and fit the selection.
+
+**Selecting**
+
+- **Click** an entity to select it; **Shift-click** to toggle it in a multi-selection.
+- Drag on **empty space** to **marquee** box-select everything inside.
+- Press **Esc** to cancel an in-progress drag, then to clear the selection.
+
+**Transforming** — pick a tool from the toolbar (or its shortcut) and drag a gizmo
+handle:
+
+| Tool | Shortcut | Gizmo |
+|---|---|---|
+| Select | `Q` | Pick / marquee only, no transform handles. |
+| Move | `W` | Axis arrows (X / Y) plus a center plane for free move. |
+| Rotate | `E` | A rotation ring. |
+| Scale | `R` | Axis boxes plus a uniform-scale center. |
+
+Dragging a handle transforms the whole selection as one, about a shared pivot, and
+each drag is a single undo step. **Alt-drag** a selection to duplicate it and drag the
+copies. Nudge the selection with the **arrow keys** (one grid step; hold **Shift** for
+×10).
+
+**Align & distribute** — select two or more entities and a strip of alignment buttons
+appears in the viewport overlay: align **left / centre / right** edges and **top / middle /
+bottom** edges. With three or more selected, two **distribute** buttons even out horizontal
+or vertical spacing. Each is a single undo step and works across every entity kind (sprites,
+UI nodes, gizmo-only entities alike).
+
+**Snapping** — toggle snapping from the viewport's Snap dropdown and set the grid step,
+rotation angle, and scale increment.
+
+**Show Flags** — a viewport dropdown toggles the Grid, Gizmos, Physics, and the perf
+overlay, plus World/Local axis orientation and Pivot-vs-Center. Entities that don't
+render — Cameras, `Light2D`, colliders, joints, particle emitters — are drawn as
+gizmos in edit mode (icon, view rect, light reach/cone, collider outline, joint
+anchor links) so you can see and place them; many carry drag handles that write
+their fields directly (light radius, collider size, emitter shape, joint anchors).
+
+## Editing modes
+
+The Activity Bar's top three icons switch the **editing mode** — **Scene**, **UI**, or
+**Tilemap**. The mode also *follows your selection*: pick a `Canvas` or `UINode` and the
+editor suggests **UI** mode, a `TilemapLayer` suggests **Tilemap** — switching that mode's
+tools and viewport aids **without** disturbing your panel layout. To open a mode's
+companion panels (UI Widgets, the Tilemap painter), click its Activity Bar icon or the
+viewport's mode chip; that also **pins** the mode as a sticky lock that ordinary selection
+clicks won't clear — re-click it to go back to following the selection.
+
+**The design frame + device preview.** A scene is authored against a **design resolution** —
+a fixed reference size (e.g. `1920 × 1080` landscape or `750 × 1334` portrait). This is a
+**project-level** value (Project Settings → Display), not a UI-layer one: the viewport's
+**Design** and **Device** controls work in **every** editor mode (Scene / UI / Tilemap), so
+you can preview a gameplay-only scene on a real device **without** a UI Canvas. When the
+scene has a Canvas, UI additionally lays out inside the frame per its scale mode.
+
+- **Design** dropdown (viewport toolbar) — sets the design resolution and reframes to it
+ (undoable). With a Canvas it edits that Canvas; otherwise it edits the project value.
+- **Device** dropdown — picks the **target screen** (iPhone / iPad / 1080p …) in any mode.
+ While editing it draws that screen's aspect as letterbox bars + safe-area insets over
+ your scene; when you press **Play** the running game is letterboxed to the same shape,
+ in the viewport and in the **Game** panel alike. It never changes your design
+ resolution — it changes what you are looking at it *through*.
+- **Orientation** (same dropdown) — swaps the device's width and height. It applies to a
+ **device**, so it is disabled while `Design` is selected: with no screen simulated
+ there is nothing to rotate.
+- **Camera Fit** (Project Settings → Display) — how the **main camera** scales the design
+ resolution, independent of any UI Canvas. `None` (default) keeps the camera's own
+ orthoSize; any other mode letterboxes the game the same way on every device, and the
+ device preview then shows the **real** framing (WYSIWYG for gameplay, not just UI).
+
+**One screen, edit and run.** The `Design` entry is the "no simulation" choice: the game
+fills whatever space the panel has, which is what authoring for desktop wants. Pick any
+real device and both the edit overlay and the running game commit to its shape — so a
+project authored for a phone is never only ever *run* at whatever aspect the dock
+happened to be dragged to.
+
+![A scene running in the viewport, framed to the selected target screen rather than to the panel's own shape](../../../assets/guides/en/game-target-screen.png)
+
+### Project screen presets
+
+The built-in device list is a guess. A team that ships to specific hardware corrects it
+in **Project Settings → Display → Screen presets**: add a row with an id, a name and the
+portrait size, and it joins the dropdown for everyone who opens the project.
+
+- **Id** is what a saved selection resolves through, so keep it stable. Reusing a built-in
+ id (`iphone`, `ipad`, `1080p`, `720p`) **replaces** that built-in rather than sitting
+ beside it — which is how a studio makes "iPhone" mean the exact handset it tests on.
+- **Sizes are stored portrait** (width ≤ height), like the built-ins, so the orientation
+ toggle means the same thing for every screen.
+- **Safe area** (the row's ▸ expander) sets the notch / home-indicator insets in device
+ pixels. Leave them at zero and nothing is written to the project file — the viewport's
+ *Safe area* overlay then has nothing to draw for that screen.
+
+![Project Settings showing a screen preset row with its safe-area insets expanded](../../../assets/guides/en/settings-screen-presets.png)
+
+Presets live in `project.esproject`, so they are shared through version control:
+
+```json title="project.esproject"
+{
+ "screenPresets": [
+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
+ {
+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }
+ }
+ ]
+}
+```
diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdx
index 7ed86cf67..ba8eba895 100644
--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx
@@ -324,7 +324,7 @@ mysterious.
## Project platform profiles
A `.esengine/platforms/<id>.mjs` packaging profile (see
-[Mini-Game Platforms](/guides/minigame-platforms/)) is imported into the editor's
+[Mini-Game Platforms](/docs/publishing/minigame-platforms/)) is imported into the editor's
main process with full system access. It is listed in the Plugins panel and needs
the same approval — until you approve it, its target shows as not ready in the
Package dialog.
@@ -391,7 +391,7 @@ is unavailable. Gate on it the way gameplay code gates on `Ads.available`: a
target without the module should degrade, not crash.
To draw what such a runtime produces, hand its triangles to
-[Mesh2D](/guides/drawing/) — positions, UVs, colors and indices go through the
+[Mesh2D](/docs/graphics/drawing/) — positions, UVs, colors and indices go through the
same path the engine's own Spine integration uses, so it renders on every backend
the engine supports.
diff --git a/docs/astro/src/content/docs/publishing/minigame-platforms.mdx b/docs/astro/src/content/docs/publishing/minigame-platforms.mdx
index 2058b0a63..3773105bc 100644
--- a/docs/astro/src/content/docs/publishing/minigame-platforms.mdx
+++ b/docs/astro/src/content/docs/publishing/minigame-platforms.mdx
@@ -12,7 +12,7 @@ input, key-value storage. Estella implements that model **once** and describes
each vendor as data.
This guide is for bringing up a vendor Estella does not ship. If you are
-shipping to WeChat, you want [WeChat MiniGame](/guides/wechat) instead.
+shipping to WeChat, you want [WeChat MiniGame](/docs/publishing/wechat/) instead.
<Aside type="caution">
**Pre-1.0.** The profile contract is `@beta`: it may gain fields as vendors
diff --git a/docs/astro/src/content/docs/scripting/overview.mdx b/docs/astro/src/content/docs/scripting/overview.mdx
index afab0d825..7aeaf916e 100644
--- a/docs/astro/src/content/docs/scripting/overview.mdx
+++ b/docs/astro/src/content/docs/scripting/overview.mdx
@@ -154,15 +154,15 @@ built-in, and a game does not run in Node…
```
If the import is yours, reach for a web API (`crypto.subtle`, `fetch`,
-`localStorage`) or the engine's own equivalent — [Assets](/guides/assets/) for
-files, [Save & Load](/guides/save/) for player data, both of which work
+`localStorage`) or the engine's own equivalent — [Assets](/docs/assets/overview/) for
+files, [Save & Load](/docs/scripting/save/) for player data, both of which work
everywhere. If a *dependency* is the one reaching, the fix is on the package:
many publish a browser-safe entry point — `protobufjs/minimal` above is exactly
that — and some ship a `browser` field that esbuild picks up on its own.
**And it costs package size.** A dependency is bundled whole, which matters most
where the limit is hardest: WeChat caps a mini-game's main package at 4MB. After
-a build, the [size report](/guides/build-export/#package-size) breaks the package
+a build, the [size report](/docs/publishing/overview/#package-size) breaks the package
down — a library that grew shows up under **Scripts**.
<Aside type="tip">
diff --git a/docs/astro/src/content/docs/ui/overview.mdx b/docs/astro/src/content/docs/ui/overview.mdx
index 9e9ec060c..879797862 100644
--- a/docs/astro/src/content/docs/ui/overview.mdx
+++ b/docs/astro/src/content/docs/ui/overview.mdx
@@ -130,7 +130,7 @@ reaches. Corners keep their exact pixels at any size, so one 100×112 texture se
tooltip and a full-width banner. The border belongs to the **image**, not to the entity
using it, so it is a texture import setting — set it once and every `NineSlice` that
references the texture is sliced the same way. See
-[dragging the border](/docs/editor/overview/#the-content-browser) in the asset inspector.
+[dragging the border](/docs/editor/content-browser/) in the asset inspector.
#### What a mask is for
diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdx
index 4908592b5..28d52e579 100644
--- a/docs/astro/src/content/docs/world/particles.mdx
+++ b/docs/astro/src/content/docs/world/particles.mdx
@@ -358,7 +358,7 @@ the scene; the reference is remapped automatically when the scene loads.
Turn on `trailEnabled` and every particle drags a tapering ribbon along its recent
path — comet sparks, tracer rounds, swirling magic streaks. This is *distinct* from
-the standalone [`TrailRenderer`](/guides/trail/), which trails a single entity; here
+the standalone [`TrailRenderer`](/docs/graphics/sprites/#motion-trails), which trails a single entity; here
each of the (up to thousands of) particles gets its own streak.
```typescript
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.mdx
new file mode 100644
index 000000000..c614adefe
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdx
@@ -0,0 +1,24 @@
+---
+title: 专用编辑器
+description: "双击资产打开的各个文档编辑器:Sequencer、瓦片画笔、图块集编辑器,以及状态机、行为树与材质图。"
+---
+在内容浏览器里双击一个资产,即可在文档标签里打开它的编辑器。
+
+- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/animation/timeline/)。
+- **瓦片地图画笔** — **画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,
+ 外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个
+ **随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是
+ **正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/world/tilemaps/)。
+- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设;单向 / 传感器 / 材质
+ 修饰),并可在放大的瓦片上**直接操纵**编辑形状:拖圆的**圆心或半径**、给多边形**点击加点 /
+ 拖动 / 点击删点**编辑**顶点**、给**单向**平台挑选实心的一侧(上 / 下 / 左 / 右)——调整大小会
+ 保留传感器 / 材质 / 密度等修饰。此外还有 autotile 用的**地形**集(edge/corner 邻接或多色
+ **角 Wang**)、逐瓦片**概率**权重与属性,以及**动画瓦片**——拖动帧缩略图**重排**,或把整段
+ 循环设成**一个统一时长**,带实时预览。
+- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见
+ [游戏 AI](/docs/zh-cn/gameplay/ai/)。
+- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见
+ [材质与着色器](/docs/zh-cn/graphics/materials/)。
+
+状态机和行为树编辑器共享一块公共节点画布:**中键拖动**平移,**滚轮**朝光标缩放,把一个输出手柄
+拖到另一个节点上连线,点击选中节点或边,**Delete** 删除,右键画布在光标处添加节点。
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.mdx
new file mode 100644
index 000000000..3e36c265e
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/content-browser.mdx
@@ -0,0 +1,24 @@
+---
+title: 内容浏览器
+description: "项目的资产浏览器——新建与导入资产、按资产类型的操作,以及查找引用。"
+---
+内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:
+
+- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、**新建脚本…**、新建文件夹。
+- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、
+ **创建材质实例**(从材质)。
+
+**新建脚本…** 是唯一一个不止写一个文件的:没人 import 的模块永远不会被打包,它的组件
+也永远进不了 Add Component,所以对话框还会在项目的脚本入口里加上够到它的那一行——加到
+哪个入口,取决于你建的是组件还是系统。见
+[脚本编写](/docs/zh-cn/scripting/overview/#新建脚本对话框)。
+
+**导入**可从访达/资源管理器把文件拖进来,或用"导入…"。每个资产首次出现时会得到一个 `.meta`
+边车。按资产的上下文动作包括重命名、复制、复制路径、复制引用、**查找引用**、在文件管理器中
+显示、删除。重命名、移动和复制各会弹出一个带**撤销**按钮的 toast——而且重命名或移动资产会
+改写每个已打开文档里对它的引用,所以不会留下悬空引用。**删除**会先列出引用该文件的每个场景、
+预制件和资产(让你清楚会破坏什么),再把文件移进系统回收站——仍可用撤销复原。文件夹树完全
+可用键盘操作——方向键行走与折叠/展开,Enter 进入文件夹。
+
+**查找引用**——右键一个资产,或点击检视器资产详情里的引用计数——会列出一张纹理、材质、
+预制件或场景被引用的所有位置,横跨磁盘上的依赖图**以及**尚未保存的打开场景。
diff --git a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx b/docs/astro/src/content/docs/zh-cn/editor/overview.mdx
index 5f565dc7b..84403ce7c 100644
--- a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/editor/overview.mdx
@@ -3,7 +3,7 @@ title: 编辑器
description: Estella 编辑器导览——可停靠工作区、视口与变换 gizmo、用 Outliner 和 Details 搭场景、内容浏览器、编辑器内运行、各专用资产编辑器,以及项目设置。
---
-import { Aside } from '@astrojs/starlight/components';
+import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';
Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可停靠工作区**。你可视化地搭
场景、在检视器里调组件、绘制瓦片地图、连节点图,并**直接在编辑器里运行游戏**——在一个隔离的
@@ -26,7 +26,7 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
| `.esengine/workspace.json` | 编辑器本地状态(上次打开的场景、面板布局)。被 gitignore。 |
| `assets/scenes/*.esscene` | 你的场景。 |
| `assets/…` | 纹理、材质、瓦片集等资产,每个带一个 `.meta` 边车文件。 |
-| `src/components.ts` | **声明入口**——编辑器会求值这个模块以及它 import 到的一切,以此认识你的组件。组件定义在哪都行,从这里 re-export 出来即可。见[脚本](/zh-cn/docs/scripting/overview/#声明放在哪里)。 |
+| `src/components.ts` | **声明入口**——编辑器会求值这个模块以及它 import 到的一切,以此认识你的组件。组件定义在哪都行,从这里 re-export 出来即可。见[脚本](/docs/zh-cn/scripting/overview/#声明放在哪里)。 |
| `src/main.ts` | **启动入口**——注册系统的地方。跑游戏的是它;编辑器从不求值它。 |
资产按 UUID(`@uuid:…`)可移植地引用,而不是按路径,所以移动或重命名文件不会断掉引用。
@@ -56,292 +56,19 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
停止后回到你原本那个场景,分毫不差。
</Aside>
-## 视口
+## 本章其余部分
-视口是你摆放和操作实体的地方。
+上面的导览讲的是这个工具长什么样。下面几页是你会反复回来查的部分。
-**导航**
-
-- **平移** — 按住鼠标中键或右键拖动。
-- **缩放** — 滚动滚轮(朝光标缩放)。
-- **聚焦选中** — 按 **F** 把选中项居中并适配。
-
-**选择**
-
-- **点击**实体选中;**Shift 点击**在多选里切换它。
-- 在**空白处**拖动,**框选(marquee)**框内所有实体。
-- 按 **Esc** 取消正在进行的拖动,再按清空选择。
-
-**变换** — 从工具栏(或用快捷键)选一个工具,拖动 gizmo 手柄:
-
-| 工具 | 快捷键 | Gizmo |
-|---|---|---|
-| 选择 | `Q` | 只做拾取/框选,无变换手柄。 |
-| 移动 | `W` | 轴向箭头(X / Y)加一个自由移动的中心面。 |
-| 旋转 | `E` | 一个旋转环。 |
-| 缩放 | `R` | 轴向方块加一个等比缩放中心。 |
-
-拖动手柄会把整个选择当作一体、绕共享轴心变换,每次拖动是一步撤销。**Alt 拖动**选择可复制它并
-拖动副本。用**方向键**微移选择(一格;按 **Shift** 为 ×10)。
-
-**对齐与分布**——选中两个或更多实体,视口浮层里会出现一排对齐按钮:对齐**左 / 中 / 右**边和
-**上 / 中 / 下**边。选中三个或更多时,另有两个**分布**按钮可把水平或垂直间距均分。每个都是一步
-撤销,且对每种实体都有效(精灵、UI 节点、纯 gizmo 实体一视同仁)。
-
-**吸附** — 从视口的吸附下拉里开关吸附,并设置网格步长、旋转角度和缩放增量。
-
-**显示标志(Show Flags)** — 视口下拉可开关网格、gizmo、物理和性能浮层,以及世界/本地轴朝向
-和轴心/中心。不渲染的实体——相机、`Light2D`、碰撞体、关节、粒子发射器——在编辑模式下画成
-gizmo(图标、视野矩形、光照范围/锥、碰撞体轮廓、关节锚点连线),让你能看见并摆放它们;
-多数还带可拖拽的 handle,直接写回字段(灯光半径、碰撞体尺寸、发射器形状、关节锚点)。
-
-## 编辑模式
-
-活动栏顶部三个图标切换**编辑模式**——**场景(Scene)**、**UI**、**瓦片地图(Tilemap)**。模式也会
-*跟随你的选择*:选中 `Canvas` 或 `UINode`,编辑器建议 **UI** 模式,选中 `TilemapLayer` 建议**瓦片
-地图**模式——只切换该模式的工具和视口辅助,**不会**打乱你的面板布局。要打开某个模式的配套面板
-(UI 控件面板、瓦片地图绘制器),点它的活动栏图标或视口里的模式芯片;这也会把该模式**固定**成一个
-粘性锁,普通的选中点击不再清掉它——再点一次即可回到跟随选择。
-
-**设计框与设备预览。** 场景是对着**设计分辨率**创作的——一个固定的参考尺寸(比如横屏
-`1920 × 1080` 或竖屏 `750 × 1334`)。它是**项目级**的值(项目设置 → 显示),不属于 UI 层:视口的
-**Design** 和 **Device** 控件在**每种**编辑模式(场景 / UI / 瓦片地图)都可用,所以纯玩法场景**无需**
-UI Canvas 也能在真机上预览。场景里有 Canvas 时,UI 会额外按其缩放模式在框内布局。
-
-- **Design** 下拉(视口工具栏)——设置设计分辨率并成帧到它(可撤销)。有 Canvas 时改的是该 Canvas,
- 否则改的是项目值。
-- **Device** 下拉——在任意模式选择**目标屏幕**(iPhone / iPad / 1080p …)。编辑时它在场景上画出该
- 屏幕宽高比的 letterbox 黑边和安全区;按下**运行**后,运行中的游戏也会被 letterbox 成同一形状——
- 视口内运行和 **游戏** 面板都是如此。它不会改动你的设计分辨率,改的是你**透过什么**去看它。
-- **方向**(同一下拉)——交换设备的宽和高。它作用于**设备**,所以选中 `设计` 时是禁用的:没有模拟
- 任何屏幕,也就没有东西可转。
-- **相机适配**(项目设置 → 显示)——**主相机**如何按设计分辨率缩放,独立于任何 UI Canvas。`无`(默认)
- 保持相机自身的 orthoSize;其他模式让游戏在每台设备上一致 letterbox,设备预览也随之显示**真实**取景
- (玩法也所见即所得,不止 UI)。
-
-**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向
-桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机
-创作的项目,不会只能在"面板恰好被拖成的比例"下运行。
-
-![在视口内运行的场景,按选定的目标屏幕取景,而不是按面板自身的形状](../../../../assets/guides/zh/game-target-screen.png)
-
-### 项目屏幕预设
-
-内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:
-添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。
-
-- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、
- `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。
-- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。
-- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——
- 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。
-
-![项目设置中展开了安全区域的屏幕预设行](../../../../assets/guides/zh/settings-screen-presets.png)
-
-预设保存在 `project.esproject` 中,因此可以随版本控制共享:
-
-```json title="project.esproject"
-{
- "screenPresets": [
- { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
- {
- "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
- "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }
- }
- ]
-}
-```
-
-## 搭建场景
-
-### 创建实体
-
-有好几种加实体的方式:
-
-- **实体 → 添加实体**(或工具栏)放下一个空白 Transform 实体。
-- **创建…** 打开一个生成实体的命令面板:内置类型——**空**、**精灵**、**相机**、**粒子**、
- **光**、**瓦片地图**、**Spine**、**音频**、**文本**、**形状**、**网格**、**拖尾**,以及
- **UI** 控件(画布加控件)——**你自己项目里定义的组件**,还有项目中任意 **`.esprefab` 预制体**。
- 所有创建入口(此菜单、拖拽、自动化接口)都走同一条管线,因此每次生成都是一步撤销。
-- **在 Outliner 里右键**在上下文里做同样的事,外加文件夹、父子关系和预制体创建。
-- **从内容浏览器拖拽** — 拖一张图生成精灵,或拖一个 `.esprefab` 实例化它。
-
-### World Outliner
-
-Outliner 是场景的层级。你可以:
-
-- 把实体拖到彼此上重设父子,并用**文件夹**归类。
-- **按名跳转** — 树聚焦时,输入名字的前几个字母即可跳到匹配的实体。
-- 用 `F2` **重命名**、`mod + D` **复制**、`Delete` **删除**。
-- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。隐藏是把实体从编辑视口里
- 拿掉——精灵、骨架、瓦片图、粒子、灯光一概如此——而不改动游戏真正加载的场景。锁定则仍然可见、可选中,
- 只是不再有把手:视口不会拾取它,变换 Gizmo 也不会为它出现。
-- 从选择**创建预制体**,再把实例拖回场景。
-
-### Details 面板
-
-Details 是选中项的检视器。它列出实体上的每个组件及其字段——由引擎的反射元数据驱动,所以范围、
-单位、枚举和 tooltip 都直接来自组件定义。加组件、改值,都会实时写回场景。编辑时字段会强制其
-约束:**必填**字段为空时会被标红,数值字段写入时按声明范围 clamp,拖资产到槽位时类型不匹配会被
-拒绝。
-
-每个组件都是一个**可折叠区**,而且面板会记住你折了哪些——跨重新选择*以及*编辑器重启——所以检视器
-会保持你离开时的整洁。很少动的"周边"(某个控件的 `Focusable` 与 `ThemeStyle` 标签)默认折叠。
-
-当可视化控件比一排裸数字更清楚时,Details 会显示一个**专用控件**——大多用于 UI 节点:
-
-- 用于绝对定位 `UINode` 的**锚点**控件:一个可点击的 **3×3 网格**,对应九个点锚
- (左 / 中 / 右 × 上 / 中 / 下),每个轴另带一个 **Stretch(拉伸)**开关;
-- 用于 `FlexContainer` 的 **flex**(自动布局)控件:**方向**(横向 / 纵向及其反转)、一个
- 一点即设主轴与交叉轴对齐的 **3×3 对齐网格**、主轴**分布**(紧凑 / 两端 / 环绕 / 均匀),以及
- **换行 / 填满**开关——**内边距**用一个四边 `sides` 控件编辑;
-- 一个内联 **Controllers(控制器)条**,把逐节点的状态创作拉进检视器:选一个状态页、给字段
- *挂齿轮*绑定,全程不用离开面板(见 [UI 控制器](/docs/zh-cn/ui/controllers/));
-- 对**材质**,一个 **Shader** 选择器,用于切换绑定的着色器——内置模板或项目里的 `.esshader`——见
- [材质与着色器](/docs/zh-cn/graphics/materials/#在编辑器里选取与共享着色器)。
-
-![细节面板显示某个 UI 节点的锚点网格与布局控件](../../../../assets/guides/zh/inspector-flex.png)
-
-*一个 UI 节点的检视器:**布局内 / 绝对**切换、可点击的 **3×3 锚点网格**(每轴带 Stretch),以及 `Display: Flex`——用可视化控件取代裸数字。*
-
-Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)
-编辑其参数。
-
-**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字
-等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好
-其余边,再精确微调某一条。
-
-导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:
-编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的
-游戏里同样正确。
-
-![在资产检视器中拖动纹理的九宫格参考线](../../../../assets/guides/zh/nine-slice-drag.png)
-
-## 内容浏览器
-
-内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:
-
-- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、**新建脚本…**、新建文件夹。
-- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、
- **创建材质实例**(从材质)。
-
-**新建脚本…** 是唯一一个不止写一个文件的:没人 import 的模块永远不会被打包,它的组件
-也永远进不了 Add Component,所以对话框还会在项目的脚本入口里加上够到它的那一行——加到
-哪个入口,取决于你建的是组件还是系统。见
-[脚本编写](/docs/zh-cn/scripting/overview/#新建脚本对话框)。
-
-**导入**可从访达/资源管理器把文件拖进来,或用"导入…"。每个资产首次出现时会得到一个 `.meta`
-边车。按资产的上下文动作包括重命名、复制、复制路径、复制引用、**查找引用**、在文件管理器中
-显示、删除。重命名、移动和复制各会弹出一个带**撤销**按钮的 toast——而且重命名或移动资产会
-改写每个已打开文档里对它的引用,所以不会留下悬空引用。**删除**会先列出引用该文件的每个场景、
-预制件和资产(让你清楚会破坏什么),再把文件移进系统回收站——仍可用撤销复原。文件夹树完全
-可用键盘操作——方向键行走与折叠/展开,Enter 进入文件夹。
-
-**查找引用**——右键一个资产,或点击检视器资产详情里的引用计数——会列出一张纹理、材质、
-预制件或场景被引用的所有位置,横跨磁盘上的依赖图**以及**尚未保存的打开场景。
-
-## 编辑器内运行
-
-工具栏里的**运行**控制驱动你的游戏:
-
-- **运行**启动游戏;运行时同一个按钮变成**停止**,旁边是**重启**和**暂停/继续**侧键。
-- 运行模式下拉选择**在视口中运行**(游戏托管在视口上)或**在新窗口运行**(专门的 **Game** 标签),
- 并可切换**运行时最大化视口**——把整个工作区让给运行中的游戏,停止时还原你的布局。
-- 运行中的游戏在视口四周显示一圈柔和的强调色边框(暂停时转琥珀色并压暗画面),而不是盖在游戏上的角标。
-- 快捷键:**F5** 运行,**Esc** 停止,**F6** 暂停/继续,**Shift+F5** 重启,**F11** 随时最大化/还原视口。
-
-因为运行用的是隔离 realm——正是发布你游戏的那套运行时——你在运行里看到的,就是玩家会得到的。
-
-## 自动保存与恢复
-
-编辑器会定期快照你**未保存**的文档——仅在存在未保存改动且没有 Play 会话运行时——所以崩溃或
-断电最多只损失最近片刻的工作。快照保存在项目的工作区文件夹里,永远不算作真正的保存。下次
-打开项目时,如果某个快照比磁盘上的文件更新,编辑器会提议**恢复**它;保存文档就会让它的快照
-失效。这与崩溃 minidump、以及 GPU 渲染进程丢失时的自动重载并存。
-
-## 专用编辑器
-
-在内容浏览器里双击一个资产,即可在文档标签里打开它的编辑器。
-
-- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/animation/timeline/)。
-- **瓦片地图画笔** — **画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,
- 外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个
- **随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是
- **正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/world/tilemaps/)。
-- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设;单向 / 传感器 / 材质
- 修饰),并可在放大的瓦片上**直接操纵**编辑形状:拖圆的**圆心或半径**、给多边形**点击加点 /
- 拖动 / 点击删点**编辑**顶点**、给**单向**平台挑选实心的一侧(上 / 下 / 左 / 右)——调整大小会
- 保留传感器 / 材质 / 密度等修饰。此外还有 autotile 用的**地形**集(edge/corner 邻接或多色
- **角 Wang**)、逐瓦片**概率**权重与属性,以及**动画瓦片**——拖动帧缩略图**重排**,或把整段
- 循环设成**一个统一时长**,带实时预览。
-- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见
- [游戏 AI](/docs/zh-cn/gameplay/ai/)。
-- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见
- [材质与着色器](/docs/zh-cn/graphics/materials/)。
-
-状态机和行为树编辑器共享一块公共节点画布:**中键拖动**平移,**滚轮**朝光标缩放,把一个输出手柄
-拖到另一个节点上连线,点击选中节点或边,**Delete** 删除,右键画布在光标处添加节点。
-
-## 项目设置
-
-用 **Ctrl / ⌘ + ,** 或活动栏的齿轮打开设置。设置分组:
-
-- **编辑器** — 外观(**语言**、强调色、UI 缩放)、视口(网格、吸附、gizmo)、**键盘快捷键**(下面每个快捷键
- 都能在这里重绑)、控制台。
-- **项目**(存进 `project.esproject`):
- - **显示** — 项目设计分辨率(播种新 Canvas + 驱动任意场景的设备预览)、项目级的**屏幕方向**
- (所有导出目标都遵循它;留空则从设计分辨率的宽高比推导),以及**相机适配**(主相机如何在无 UI
- Canvas 的情况下按设计分辨率缩放;`无`=关闭)。
- - **UI** — 项目的控件**主题**(深色 / 浅色)与逐角色的**主题颜色**覆盖,在编辑器、Play
- 和所有导出里一致生效。见 [UI 控件——主题](/docs/zh-cn/ui/widgets/#主题)。
- - **物理** — 启用、重力、十六个碰撞层名字和一个 16×16 碰撞矩阵,以及解算器调参(固定时间步、
- 子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/gameplay/physics/)。
- - **渲染** — 最多三十二个命名排序层,填充检视器里的层下拉,以及其中哪些参与 Y 轴排序。
- 名字只是建议,不是上限:渲染组件的 `layer` 照样接受名单以外的数字。
- - **打包** — 每目标元数据:微信 AppID、桌面应用 id / 产品名。
-
-### 编辑器语言
-
-编辑器内置 **English** 和 **简体中文**,首次启动跟随系统语言。在 **设置 → 外观 → 语言** 切换——
-更改在重新加载后生效(编辑器会弹出提示)。编辑器界面文案跑在与游戏运行时相同的
-[本地化引擎](/docs/zh-cn/assets/localization/)上。
-
-## 键盘快捷键
-
-`mod` 在 macOS 上是 **⌘**,其他平台是 **Ctrl**。以下全部可在设置 → 键盘快捷键里重绑。
-
-| 动作 | 快捷键 |
-|---|---|
-| 新建场景 | `mod + N` |
-| 打开项目 | `mod + O` |
-| 保存场景 | `mod + S` |
-| 场景另存为 | `mod + shift + S` |
-| 撤销 / 重做 | `mod + Z` / `mod + shift + Z` |
-| 复制(duplicate) | `mod + D` |
-| 拷贝 / 剪切 / 粘贴 | `mod + C` / `mod + X` / `mod + V` |
-| 删除 | `Delete` / `Backspace` |
-| 全选 | `mod + A` |
-| 选择 / 移动 / 旋转 / 缩放 工具 | `Q` / `W` / `E` / `R` |
-| 微移选择(按 Shift ×10) | 方向键 |
-| 聚焦选中 | `F` |
-| 运行 · 停止 | `F5` · `Esc` |
-| 暂停/继续 · 重启 | `F6` · `shift + F5` |
-| 最大化 / 还原视口 | `F11` |
-| 命令面板 | `mod + shift + P` |
-| 内容抽屉 | `Ctrl + Space` |
-| 项目设置 | `mod + ,` |
-
-**命令面板**(`mod + shift + P`)对每一条可运行命令做模糊搜索——不用翻菜单,直达任何操作的最快方式。
-
-在命令快捷键之外,编辑器整体都可用键盘导航:菜单与右键菜单用方向键移动(还有输入即跳、
-Home/End、`→` / `←` 进出子菜单),Outliner 输入名字即跳转,内容浏览器的文件夹树和瓦片
-调色板都用方向键行走,键盘焦点始终有可见的焦点环。
-
-<Aside type="tip">
- 用于无头自动化和 AI 代理,编辑器还暴露了一个 `EditorControlSurface`(加载场景、步进模拟、读取
- 场景树/检视器、抓取视口),通过一个 MCP server 提供——这是一个由脚本驱动的开发/自动化面,与上面
- 的可视化编辑器分开。
-</Aside>
+<CardGrid>
+ <LinkCard title="视口与编辑模式" href="/docs/zh-cn/editor/viewport/" description="导航、变换 gizmo、对齐与分布,以及设备预览。" />
+ <LinkCard title="搭建场景" href="/docs/zh-cn/editor/scenes/" description="创建实体、World Outliner,以及 Details 检视器。" />
+ <LinkCard title="内容浏览器" href="/docs/zh-cn/editor/content-browser/" description="新建与导入资产,以及查找谁引用了它们。" />
+ <LinkCard title="编辑器内运行" href="/docs/zh-cn/editor/play/" description="在隔离 realm 里运行游戏,以及自动保存恢复。" />
+ <LinkCard title="专用编辑器" href="/docs/zh-cn/editor/asset-editors/" description="Sequencer、瓦片画笔、图块集编辑器与节点图。" />
+ <LinkCard title="项目设置" href="/docs/zh-cn/editor/settings/" description="编辑器偏好,以及写进项目文件的设置。" />
+ <LinkCard title="键盘快捷键" href="/docs/zh-cn/editor/shortcuts/" description="全部默认绑定,以及命令面板。" />
+</CardGrid>
## 参见
diff --git a/docs/astro/src/content/docs/zh-cn/editor/play.mdx b/docs/astro/src/content/docs/zh-cn/editor/play.mdx
new file mode 100644
index 000000000..1a4ee69bd
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/play.mdx
@@ -0,0 +1,20 @@
+---
+title: 编辑器内运行
+description: "在隔离 realm 里于编辑器内运行游戏、运行模式选项,以及自动保存与崩溃恢复。"
+---
+工具栏里的**运行**控制驱动你的游戏:
+
+- **运行**启动游戏;运行时同一个按钮变成**停止**,旁边是**重启**和**暂停/继续**侧键。
+- 运行模式下拉选择**在视口中运行**(游戏托管在视口上)或**在新窗口运行**(专门的 **Game** 标签),
+ 并可切换**运行时最大化视口**——把整个工作区让给运行中的游戏,停止时还原你的布局。
+- 运行中的游戏在视口四周显示一圈柔和的强调色边框(暂停时转琥珀色并压暗画面),而不是盖在游戏上的角标。
+- 快捷键:**F5** 运行,**Esc** 停止,**F6** 暂停/继续,**Shift+F5** 重启,**F11** 随时最大化/还原视口。
+
+因为运行用的是隔离 realm——正是发布你游戏的那套运行时——你在运行里看到的,就是玩家会得到的。
+
+## 自动保存与恢复
+
+编辑器会定期快照你**未保存**的文档——仅在存在未保存改动且没有 Play 会话运行时——所以崩溃或
+断电最多只损失最近片刻的工作。快照保存在项目的工作区文件夹里,永远不算作真正的保存。下次
+打开项目时,如果某个快照比磁盘上的文件更新,编辑器会提议**恢复**它;保存文档就会让它的快照
+失效。这与崩溃 minidump、以及 GPU 渲染进程丢失时的自动重载并存。
diff --git a/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx
new file mode 100644
index 000000000..36a13624e
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx
@@ -0,0 +1,66 @@
+---
+title: 搭建场景
+description: "创建实体、World Outliner,以及 Details 检视器——含它的专用布局控件与它编辑的资产导入设置。"
+---
+## 创建实体
+
+有好几种加实体的方式:
+
+- **实体 → 添加实体**(或工具栏)放下一个空白 Transform 实体。
+- **创建…** 打开一个生成实体的命令面板:内置类型——**空**、**精灵**、**相机**、**粒子**、
+ **光**、**瓦片地图**、**Spine**、**音频**、**文本**、**形状**、**网格**、**拖尾**,以及
+ **UI** 控件(画布加控件)——**你自己项目里定义的组件**,还有项目中任意 **`.esprefab` 预制体**。
+ 所有创建入口(此菜单、拖拽、自动化接口)都走同一条管线,因此每次生成都是一步撤销。
+- **在 Outliner 里右键**在上下文里做同样的事,外加文件夹、父子关系和预制体创建。
+- **从内容浏览器拖拽** — 拖一张图生成精灵,或拖一个 `.esprefab` 实例化它。
+
+## World Outliner
+
+Outliner 是场景的层级。你可以:
+
+- 把实体拖到彼此上重设父子,并用**文件夹**归类。
+- **按名跳转** — 树聚焦时,输入名字的前几个字母即可跳到匹配的实体。
+- 用 `F2` **重命名**、`mod + D` **复制**、`Delete` **删除**。
+- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。隐藏是把实体从编辑视口里
+ 拿掉——精灵、骨架、瓦片图、粒子、灯光一概如此——而不改动游戏真正加载的场景。锁定则仍然可见、可选中,
+ 只是不再有把手:视口不会拾取它,变换 Gizmo 也不会为它出现。
+- 从选择**创建预制体**,再把实例拖回场景。
+
+## Details 面板
+
+Details 是选中项的检视器。它列出实体上的每个组件及其字段——由引擎的反射元数据驱动,所以范围、
+单位、枚举和 tooltip 都直接来自组件定义。加组件、改值,都会实时写回场景。编辑时字段会强制其
+约束:**必填**字段为空时会被标红,数值字段写入时按声明范围 clamp,拖资产到槽位时类型不匹配会被
+拒绝。
+
+每个组件都是一个**可折叠区**,而且面板会记住你折了哪些——跨重新选择*以及*编辑器重启——所以检视器
+会保持你离开时的整洁。很少动的"周边"(某个控件的 `Focusable` 与 `ThemeStyle` 标签)默认折叠。
+
+当可视化控件比一排裸数字更清楚时,Details 会显示一个**专用控件**——大多用于 UI 节点:
+
+- 用于绝对定位 `UINode` 的**锚点**控件:一个可点击的 **3×3 网格**,对应九个点锚
+ (左 / 中 / 右 × 上 / 中 / 下),每个轴另带一个 **Stretch(拉伸)**开关;
+- 用于 `FlexContainer` 的 **flex**(自动布局)控件:**方向**(横向 / 纵向及其反转)、一个
+ 一点即设主轴与交叉轴对齐的 **3×3 对齐网格**、主轴**分布**(紧凑 / 两端 / 环绕 / 均匀),以及
+ **换行 / 填满**开关——**内边距**用一个四边 `sides` 控件编辑;
+- 一个内联 **Controllers(控制器)条**,把逐节点的状态创作拉进检视器:选一个状态页、给字段
+ *挂齿轮*绑定,全程不用离开面板(见 [UI 控制器](/docs/zh-cn/ui/controllers/));
+- 对**材质**,一个 **Shader** 选择器,用于切换绑定的着色器——内置模板或项目里的 `.esshader`——见
+ [材质与着色器](/docs/zh-cn/graphics/materials/#在编辑器里选取与共享着色器)。
+
+![细节面板显示某个 UI 节点的锚点网格与布局控件](../../../../assets/guides/zh/inspector-flex.png)
+
+*一个 UI 节点的检视器:**布局内 / 绝对**切换、可点击的 **3×3 锚点网格**(每轴带 Stretch),以及 `Display: Flex`——用可视化控件取代裸数字。*
+
+Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)
+编辑其参数。
+
+**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字
+等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好
+其余边,再精确微调某一条。
+
+导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:
+编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的
+游戏里同样正确。
+
+![在资产检视器中拖动纹理的九宫格参考线](../../../../assets/guides/zh/nine-slice-drag.png)
diff --git a/docs/astro/src/content/docs/zh-cn/editor/settings.mdx b/docs/astro/src/content/docs/zh-cn/editor/settings.mdx
new file mode 100644
index 000000000..1d5dad1bf
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/settings.mdx
@@ -0,0 +1,25 @@
+---
+title: 项目设置
+description: "编辑器偏好,以及写入 project.esproject 的项目级设置——显示、UI 主题、物理、渲染层与打包。"
+---
+用 **Ctrl / ⌘ + ,** 或活动栏的齿轮打开设置。设置分组:
+
+- **编辑器** — 外观(**语言**、强调色、UI 缩放)、视口(网格、吸附、gizmo)、**键盘快捷键**(下面每个快捷键
+ 都能在这里重绑)、控制台。
+- **项目**(存进 `project.esproject`):
+ - **显示** — 项目设计分辨率(播种新 Canvas + 驱动任意场景的设备预览)、项目级的**屏幕方向**
+ (所有导出目标都遵循它;留空则从设计分辨率的宽高比推导),以及**相机适配**(主相机如何在无 UI
+ Canvas 的情况下按设计分辨率缩放;`无`=关闭)。
+ - **UI** — 项目的控件**主题**(深色 / 浅色)与逐角色的**主题颜色**覆盖,在编辑器、Play
+ 和所有导出里一致生效。见 [UI 控件——主题](/docs/zh-cn/ui/widgets/#主题)。
+ - **物理** — 启用、重力、十六个碰撞层名字和一个 16×16 碰撞矩阵,以及解算器调参(固定时间步、
+ 子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/gameplay/physics/)。
+ - **渲染** — 最多三十二个命名排序层,填充检视器里的层下拉,以及其中哪些参与 Y 轴排序。
+ 名字只是建议,不是上限:渲染组件的 `layer` 照样接受名单以外的数字。
+ - **打包** — 每目标元数据:微信 AppID、桌面应用 id / 产品名。
+
+## 编辑器语言
+
+编辑器内置 **English** 和 **简体中文**,首次启动跟随系统语言。在 **设置 → 外观 → 语言** 切换——
+更改在重新加载后生效(编辑器会弹出提示)。编辑器界面文案跑在与游戏运行时相同的
+[本地化引擎](/docs/zh-cn/assets/localization/)上。
diff --git a/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx
new file mode 100644
index 000000000..f59f35bfd
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx
@@ -0,0 +1,41 @@
+---
+title: 键盘快捷键
+description: "全部默认快捷键(均可重绑),以及命令面板与编辑器的键盘导航模型。"
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`mod` 在 macOS 上是 **⌘**,其他平台是 **Ctrl**。以下全部可在设置 → 键盘快捷键里重绑。
+
+| 动作 | 快捷键 |
+|---|---|
+| 新建场景 | `mod + N` |
+| 打开项目 | `mod + O` |
+| 保存场景 | `mod + S` |
+| 场景另存为 | `mod + shift + S` |
+| 撤销 / 重做 | `mod + Z` / `mod + shift + Z` |
+| 复制(duplicate) | `mod + D` |
+| 拷贝 / 剪切 / 粘贴 | `mod + C` / `mod + X` / `mod + V` |
+| 删除 | `Delete` / `Backspace` |
+| 全选 | `mod + A` |
+| 选择 / 移动 / 旋转 / 缩放 工具 | `Q` / `W` / `E` / `R` |
+| 微移选择(按 Shift ×10) | 方向键 |
+| 聚焦选中 | `F` |
+| 运行 · 停止 | `F5` · `Esc` |
+| 暂停/继续 · 重启 | `F6` · `shift + F5` |
+| 最大化 / 还原视口 | `F11` |
+| 命令面板 | `mod + shift + P` |
+| 内容抽屉 | `Ctrl + Space` |
+| 项目设置 | `mod + ,` |
+
+**命令面板**(`mod + shift + P`)对每一条可运行命令做模糊搜索——不用翻菜单,直达任何操作的最快方式。
+
+在命令快捷键之外,编辑器整体都可用键盘导航:菜单与右键菜单用方向键移动(还有输入即跳、
+Home/End、`→` / `←` 进出子菜单),Outliner 输入名字即跳转,内容浏览器的文件夹树和瓦片
+调色板都用方向键行走,键盘焦点始终有可见的焦点环。
+
+<Aside type="tip">
+ 用于无头自动化和 AI 代理,编辑器还暴露了一个 `EditorControlSurface`(加载场景、步进模拟、读取
+ 场景树/检视器、抓取视口),通过一个 MCP server 提供——这是一个由脚本驱动的开发/自动化面,与上面
+ 的可视化编辑器分开。
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx
new file mode 100644
index 000000000..e195224fd
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx
@@ -0,0 +1,97 @@
+---
+title: 视口与编辑模式
+description: "视口导航、变换 gizmo、对齐与分布、显示开关、Scene / UI / Tilemap 模式,以及基于设计分辨率的设备预览。"
+---
+视口是你摆放和操作实体的地方。
+
+**导航**
+
+- **平移** — 按住鼠标中键或右键拖动。
+- **缩放** — 滚动滚轮(朝光标缩放)。
+- **聚焦选中** — 按 **F** 把选中项居中并适配。
+
+**选择**
+
+- **点击**实体选中;**Shift 点击**在多选里切换它。
+- 在**空白处**拖动,**框选(marquee)**框内所有实体。
+- 按 **Esc** 取消正在进行的拖动,再按清空选择。
+
+**变换** — 从工具栏(或用快捷键)选一个工具,拖动 gizmo 手柄:
+
+| 工具 | 快捷键 | Gizmo |
+|---|---|---|
+| 选择 | `Q` | 只做拾取/框选,无变换手柄。 |
+| 移动 | `W` | 轴向箭头(X / Y)加一个自由移动的中心面。 |
+| 旋转 | `E` | 一个旋转环。 |
+| 缩放 | `R` | 轴向方块加一个等比缩放中心。 |
+
+拖动手柄会把整个选择当作一体、绕共享轴心变换,每次拖动是一步撤销。**Alt 拖动**选择可复制它并
+拖动副本。用**方向键**微移选择(一格;按 **Shift** 为 ×10)。
+
+**对齐与分布**——选中两个或更多实体,视口浮层里会出现一排对齐按钮:对齐**左 / 中 / 右**边和
+**上 / 中 / 下**边。选中三个或更多时,另有两个**分布**按钮可把水平或垂直间距均分。每个都是一步
+撤销,且对每种实体都有效(精灵、UI 节点、纯 gizmo 实体一视同仁)。
+
+**吸附** — 从视口的吸附下拉里开关吸附,并设置网格步长、旋转角度和缩放增量。
+
+**显示标志(Show Flags)** — 视口下拉可开关网格、gizmo、物理和性能浮层,以及世界/本地轴朝向
+和轴心/中心。不渲染的实体——相机、`Light2D`、碰撞体、关节、粒子发射器——在编辑模式下画成
+gizmo(图标、视野矩形、光照范围/锥、碰撞体轮廓、关节锚点连线),让你能看见并摆放它们;
+多数还带可拖拽的 handle,直接写回字段(灯光半径、碰撞体尺寸、发射器形状、关节锚点)。
+
+## 编辑模式
+
+活动栏顶部三个图标切换**编辑模式**——**场景(Scene)**、**UI**、**瓦片地图(Tilemap)**。模式也会
+*跟随你的选择*:选中 `Canvas` 或 `UINode`,编辑器建议 **UI** 模式,选中 `TilemapLayer` 建议**瓦片
+地图**模式——只切换该模式的工具和视口辅助,**不会**打乱你的面板布局。要打开某个模式的配套面板
+(UI 控件面板、瓦片地图绘制器),点它的活动栏图标或视口里的模式芯片;这也会把该模式**固定**成一个
+粘性锁,普通的选中点击不再清掉它——再点一次即可回到跟随选择。
+
+**设计框与设备预览。** 场景是对着**设计分辨率**创作的——一个固定的参考尺寸(比如横屏
+`1920 × 1080` 或竖屏 `750 × 1334`)。它是**项目级**的值(项目设置 → 显示),不属于 UI 层:视口的
+**Design** 和 **Device** 控件在**每种**编辑模式(场景 / UI / 瓦片地图)都可用,所以纯玩法场景**无需**
+UI Canvas 也能在真机上预览。场景里有 Canvas 时,UI 会额外按其缩放模式在框内布局。
+
+- **Design** 下拉(视口工具栏)——设置设计分辨率并成帧到它(可撤销)。有 Canvas 时改的是该 Canvas,
+ 否则改的是项目值。
+- **Device** 下拉——在任意模式选择**目标屏幕**(iPhone / iPad / 1080p …)。编辑时它在场景上画出该
+ 屏幕宽高比的 letterbox 黑边和安全区;按下**运行**后,运行中的游戏也会被 letterbox 成同一形状——
+ 视口内运行和 **游戏** 面板都是如此。它不会改动你的设计分辨率,改的是你**透过什么**去看它。
+- **方向**(同一下拉)——交换设备的宽和高。它作用于**设备**,所以选中 `设计` 时是禁用的:没有模拟
+ 任何屏幕,也就没有东西可转。
+- **相机适配**(项目设置 → 显示)——**主相机**如何按设计分辨率缩放,独立于任何 UI Canvas。`无`(默认)
+ 保持相机自身的 orthoSize;其他模式让游戏在每台设备上一致 letterbox,设备预览也随之显示**真实**取景
+ (玩法也所见即所得,不止 UI)。
+
+**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向
+桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机
+创作的项目,不会只能在"面板恰好被拖成的比例"下运行。
+
+![在视口内运行的场景,按选定的目标屏幕取景,而不是按面板自身的形状](../../../../assets/guides/zh/game-target-screen.png)
+
+### 项目屏幕预设
+
+内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:
+添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。
+
+- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、
+ `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。
+- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。
+- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——
+ 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。
+
+![项目设置中展开了安全区域的屏幕预设行](../../../../assets/guides/zh/settings-screen-presets.png)
+
+预设保存在 `project.esproject` 中,因此可以随版本控制共享:
+
+```json title="project.esproject"
+{
+ "screenPresets": [
+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
+ {
+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 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.mdx
index e8ea0ff7f..21ec35957 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
@@ -286,7 +286,7 @@ ctx.scene.transact('Rename Markers', () => {
## 项目平台配置
`.esengine/platforms/<id>.mjs` 打包配置(见
-[小游戏平台](/zh-cn/guides/minigame-platforms/))会以完整系统权限被导入编辑器主
+[小游戏平台](/docs/zh-cn/publishing/minigame-platforms/))会以完整系统权限被导入编辑器主
进程。它同样列在插件面板里、同样需要批准——在你批准之前,它对应的目标在打包对话框
里显示为未就绪。
@@ -345,7 +345,7 @@ const version = rive.cwrap('rive_version', 'string', [])() as string;
的目标应当降级,而不是崩溃。
要把这类运行时产出的东西画出来,把它的三角形交给
-[Mesh2D](/zh-cn/guides/drawing/)——顶点位置、UV、颜色和索引走的正是引擎内置 Spine 集成
+[Mesh2D](/docs/zh-cn/graphics/drawing/)——顶点位置、UV、颜色和索引走的正是引擎内置 Spine 集成
所用的同一条路,因此引擎支持的每个后端上它都能渲染。
<Aside type="note">
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx b/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx
index fcd5e29da..4d24785a9 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx
@@ -10,7 +10,7 @@ import { Steps, Aside } from '@astrojs/starlight/components';
触摸输入、键值存储。Estella 把这套模型**只实现一次**,每个平台厂商用数据来描述。
本指南面向「接入 Estella 未内置的平台」。如果你的目标是微信,请看
-[微信小游戏](/zh-cn/guides/wechat)。
+[微信小游戏](/docs/zh-cn/publishing/wechat/)。
<Aside type="caution">
**1.0 之前。** profile 契约标记为 `@beta`:随着微信之外的平台在真机上跑通,它可能
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
index b2bba4047..f168dadc1 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
@@ -134,13 +134,13 @@ built-in, and a game does not run in Node…
```
如果这个 import 是你自己写的,改用 Web API(`crypto.subtle`、`fetch`、`localStorage`)
-或引擎自己的等价物——文件用 [资产](/zh-cn/guides/assets/)、玩家数据用
-[存档](/zh-cn/guides/save/),它们在所有平台都能用。如果伸手的是**某个依赖**,那修法在
+或引擎自己的等价物——文件用 [资产](/docs/zh-cn/assets/overview/)、玩家数据用
+[存档](/docs/zh-cn/scripting/save/),它们在所有平台都能用。如果伸手的是**某个依赖**,那修法在
包那一侧:很多包都发布了浏览器安全的入口——上面的 `protobufjs/minimal` 正是——还有些带
`browser` 字段,esbuild 会自动选用。
**而且它要占包体。** 依赖是被整个打进去的,而这在上限最紧的地方最要命:微信把小游戏主包
-限制在 4MB。构建完成后,[体积报告](/zh-cn/guides/build-export/#包体体积)会把包体拆开给你
+限制在 4MB。构建完成后,[体积报告](/docs/zh-cn/publishing/overview/#包体体积)会把包体拆开给你
看——涨上去的库会出现在**脚本**那一类里。
<Aside type="tip">
diff --git a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
index 470021dcd..953529111 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
@@ -121,7 +121,7 @@ addStartupSystem(buildPauseMenu);
`sliceBorder` 就是那四个数字:从每条边往内多远是"不该拉伸"的区带。四角在任何尺寸下都保留自己
的精确像素,于是同一张 100×112 的纹理既能做小提示框,也能做通栏横幅。这个边框属于**图像**本身,
而不属于用到它的实体,所以它是纹理的导入设置——设一次,引用该纹理的每个 `NineSlice` 都按同样
-方式切片。参见资产检视器中的[拖拽边框](/zh-cn/docs/editor/overview/#内容浏览器)。
+方式切片。参见资产检视器中的[拖拽边框](/docs/zh-cn/editor/content-browser/)。
#### 遮罩是用来做什么的
diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
index 97b99d7d5..03f1c3647 100644
--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
@@ -334,7 +334,7 @@ cmds.spawn()
## 逐粒子拖尾
打开 `trailEnabled`,每个粒子都会沿最近的运动轨迹拖出一条渐细的 ribbon —— 彗星火花、
-曳光弹、旋绕的魔法尾迹。这和独立的 [`TrailRenderer`](/zh-cn/guides/trail/) *不同*:后者
+曳光弹、旋绕的魔法尾迹。这和独立的 [`TrailRenderer`](/docs/zh-cn/graphics/sprites/#拖尾) *不同*:后者
给单个实体拖尾,而这里(可达数千个)每个粒子都有自己的尾迹。
```typescript