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(editor): a manual chapter was hiding behind one sidebar link
yhhd35589aa8923
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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 Editordescription: 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.----### 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.----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).----*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.----## 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 alsodiff --git a/docs/astro/src/content/docs/editor/play.mdx b/docs/astro/src/content/docs/editor/play.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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).++++*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.++diff --git a/docs/astro/src/content/docs/editor/settings.mdx b/docs/astro/src/content/docs/editor/settings.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.++++### 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.++++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.mdxindex 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 profilesA `.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'smain process with full system access. It is listed in the Plugins panel and needsthe same approval — until you approve it, its target shows as not ready in thePackage dialog.@@ -391,7 +391,7 @@ is unavailable. Gate on it the way gameplay code gates on `Ads.available`: atarget 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 thesame path the engine's own Spine integration uses, so it renders on every backendthe engine supports.diff --git a/docs/astro/src/content/docs/publishing/minigame-platforms.mdx b/docs/astro/src/content/docs/publishing/minigame-platforms.mdxindex 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 describeseach 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 vendorsdiff --git a/docs/astro/src/content/docs/scripting/overview.mdx b/docs/astro/src/content/docs/scripting/overview.mdxindex 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 workeverywhere. If a *dependency* is the one reaching, the fix is on the package:many publish a browser-safe entry point — `protobufjs/minimal` above is exactlythat — 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 mostwhere 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 packagedown — 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.mdxindex 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 setooltip and a full-width banner. The border belongs to the **image**, not to the entityusing it, so it is a texture import setting — set it once and every `NineSlice` thatreferences 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 fordiff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex 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 recentpath — 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; hereeach of the (up to thousands of) particles gets its own streak.```typescriptdiff --git a/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdx b/docs/astro/src/content/docs/zh-cn/editor/asset-editors.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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)。--**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向-桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机-创作的项目,不会只能在"面板恰好被拖成的比例"下运行。----### 项目屏幕预设--内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:-添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。--- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、- `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。-- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。-- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——- 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。----预设保存在 `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 节点的检视器:**布局内 / 绝对**切换、可点击的 **3×3 锚点网格**(每轴带 Stretch),以及 `Display: Flex`——用可视化控件取代裸数字。*--Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)-编辑其参数。--**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字-等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好-其余边,再精确微调某一条。--导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:-编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的-游戏里同样正确。----## 内容浏览器--内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:--- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、**新建脚本…**、新建文件夹。-- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、- **创建材质实例**(从材质)。--**新建脚本…** 是唯一一个不止写一个文件的:没人 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 节点的检视器:**布局内 / 绝对**切换、可点击的 **3×3 锚点网格**(每轴带 Stretch),以及 `Display: Flex`——用可视化控件取代裸数字。*++Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)+编辑其参数。++**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字+等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好+其余边,再精确微调某一条。++导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:+编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的+游戏里同样正确。++diff --git a/docs/astro/src/content/docs/zh-cn/editor/settings.mdx b/docs/astro/src/content/docs/zh-cn/editor/settings.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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)。++**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向+桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机+创作的项目,不会只能在"面板恰好被拖成的比例"下运行。++++### 项目屏幕预设++内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:+添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。++- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、+ `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。+- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。+- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——+ 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。++++预设保存在 `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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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