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: cover editor-workflow features and add editor screenshots (en + zh)

yhh630b2b57d2da
diff --git a/docs/astro/src/assets/guides/en/controllers-strip.png b/docs/astro/src/assets/guides/en/controllers-strip.png
new file mode 100644
index 000000000..24474d4dc
Binary files /dev/null and b/docs/astro/src/assets/guides/en/controllers-strip.png differ
diff --git a/docs/astro/src/assets/guides/en/editor-overview.png b/docs/astro/src/assets/guides/en/editor-overview.png
new file mode 100644
index 000000000..a3bf40ca6
Binary files /dev/null and b/docs/astro/src/assets/guides/en/editor-overview.png differ
diff --git a/docs/astro/src/assets/guides/en/inspector-flex.png b/docs/astro/src/assets/guides/en/inspector-flex.png
new file mode 100644
index 000000000..24c2bcec5
Binary files /dev/null and b/docs/astro/src/assets/guides/en/inspector-flex.png differ
diff --git a/docs/astro/src/assets/guides/en/material-shader.png b/docs/astro/src/assets/guides/en/material-shader.png
new file mode 100644
index 000000000..a635c3531
Binary files /dev/null and b/docs/astro/src/assets/guides/en/material-shader.png differ
diff --git a/docs/astro/src/assets/guides/en/prefab-mode.png b/docs/astro/src/assets/guides/en/prefab-mode.png
new file mode 100644
index 000000000..5e6f21d42
Binary files /dev/null and b/docs/astro/src/assets/guides/en/prefab-mode.png differ
diff --git a/docs/astro/src/assets/guides/en/tilemap-overview.png b/docs/astro/src/assets/guides/en/tilemap-overview.png
new file mode 100644
index 000000000..513d12996
Binary files /dev/null and b/docs/astro/src/assets/guides/en/tilemap-overview.png differ
diff --git a/docs/astro/src/assets/guides/en/tilemap-tools.png b/docs/astro/src/assets/guides/en/tilemap-tools.png
new file mode 100644
index 000000000..c8fc004b0
Binary files /dev/null and b/docs/astro/src/assets/guides/en/tilemap-tools.png differ
diff --git a/docs/astro/src/assets/guides/zh/controllers-strip.png b/docs/astro/src/assets/guides/zh/controllers-strip.png
new file mode 100644
index 000000000..da2c927d1
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/controllers-strip.png differ
diff --git a/docs/astro/src/assets/guides/zh/editor-overview.png b/docs/astro/src/assets/guides/zh/editor-overview.png
new file mode 100644
index 000000000..ece071e2f
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/editor-overview.png differ
diff --git a/docs/astro/src/assets/guides/zh/inspector-flex.png b/docs/astro/src/assets/guides/zh/inspector-flex.png
new file mode 100644
index 000000000..412bbaef2
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/inspector-flex.png differ
diff --git a/docs/astro/src/assets/guides/zh/material-shader.png b/docs/astro/src/assets/guides/zh/material-shader.png
new file mode 100644
index 000000000..04b399f9e
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/material-shader.png differ
diff --git a/docs/astro/src/assets/guides/zh/prefab-mode.png b/docs/astro/src/assets/guides/zh/prefab-mode.png
new file mode 100644
index 000000000..9f635a5f3
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/prefab-mode.png differ
diff --git a/docs/astro/src/assets/guides/zh/tilemap-overview.png b/docs/astro/src/assets/guides/zh/tilemap-overview.png
new file mode 100644
index 000000000..cab72b5bd
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/tilemap-overview.png differ
diff --git a/docs/astro/src/assets/guides/zh/tilemap-tools.png b/docs/astro/src/assets/guides/zh/tilemap-tools.png
new file mode 100644
index 000000000..a449f1554
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/tilemap-tools.png differ
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index d42e5116a..ba999051b 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -36,6 +36,10 @@ renaming a file doesn't break references.
## The workspace
+![The Estella editor with a platformer scene — viewport, World Outliner, Details, and Content Browser](../../../assets/guides/en/editor-overview.png)
+
+*The default workspace: the viewport in the centre, the World Outliner and Details on the right, the Content Browser along the bottom, and the Play controls up top.*
+
The default layout, from the outside in:
- **Activity Bar** — the far-left icon rail: the **editing mode** (Scene / UI / Tilemap), side panels, and project settings.
@@ -88,6 +92,12 @@ each drag is a single undo step. **Alt-drag** a selection to duplicate it and dr
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.
@@ -163,9 +173,35 @@ tooltips come straight from the component definition. Add components, edit value
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. 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.
+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/guides/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/guides/material/#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.
## The Content Browser
@@ -173,7 +209,7 @@ The Content Browser is your project's asset explorer. Its **create** menu makes
assets in place:
- New Scene, New Animation, New Input Map, New Material, New Material Graph,
- New State Machine, New Behavior Tree, New Folder.
+ **New Shader**, New State Machine, New Behavior Tree, New Folder.
- Context actions per asset type: **Create Tileset** (from a texture), **Create
Tilemap** (from a tileset), **Create Material Instance** (from a material).
@@ -231,11 +267,15 @@ Double-click an asset in the Content Browser to open its editor in a document ta
palette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps can
be **orthogonal, isometric, staggered, or hexagonal**. See
[Tilemaps](/docs/guides/tilemap/).
-- **Tileset editor** — author per-tile **collision** (box / circle / polygon, slope
- presets, one-way / sensor / material modifiers), **terrain** sets for autotiling
- (edge/corner peering or multi-color **corner Wang**), per-tile **probability**
- weights and properties, and **animated tiles** (frame sequences with per-frame
- durations and a live preview).
+- **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/guides/ai/).
- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See
diff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/guides/material.mdx
index 385c465e7..22b09a020 100644
--- a/docs/astro/src/content/docs/guides/material.mdx
+++ b/docs/astro/src/content/docs/guides/material.mdx
@@ -23,18 +23,57 @@ You rarely start from a blank file. The Content Browser's **New Material** subme
creates a material from a built-in template — the same list ships in code as
`BUILTIN_SHADER_TEMPLATES`:
-| Template | What it does |
-|---|---|
-| **Unlit** | Texture × vertex color × `u_tint`. The plain default. |
-| **Lit** | Lit by the scene's 2D lights; `u_tint` + optional `u_normalMap`. |
-| **Hit Flash** | Blends toward `u_flashColor` by `u_flash` — drive it from code for damage blinks. |
-| **Outline** | Colored silhouette outline (`u_outlineColor`, `u_outlineWidth` in texels). |
-| **Dissolve** | Noise burn-away with a glowing edge (`u_progress` 0→1). |
-| **Pixelate** | Quantizes UVs to a `u_pixels` grid. |
-| **UV Scroll** | Scrolls the texture by `u_scrollSpeed` × time. |
-
-Each template is an ordinary `.esshader` created next to the material — open it and
-edit; nothing about it is special.
+| Template | `builtin:` id | What it does |
+|---|---|---|
+| **Unlit** | `sprite-unlit` | Texture × vertex color × `u_tint`. The plain default. |
+| **Lit** | `sprite-lit` | Lit by the scene's 2D lights; `u_tint` + optional `u_normalMap`. |
+| **Hit Flash** | `sprite-hit-flash` | Blends toward `u_flashColor` by `u_flash` — drive it from code for damage blinks. |
+| **Outline** | `sprite-outline` | Colored silhouette outline (`u_outlineColor`, `u_outlineWidth` in texels). |
+| **Dissolve** | `sprite-dissolve` | Noise burn-away with a glowing edge (`u_progress` 0→1). |
+| **Pixelate** | `sprite-pixelate` | Quantizes UVs to a `u_pixels` grid. |
+| **UV Scroll** | `sprite-uv-scroll` | Scrolls the texture by `u_scrollSpeed` × time. |
+
+A new material **references** its template by id — it stores `shader: "builtin:sprite-unlit"`
+and writes **no shader file** to disk. The engine compiles the built-in from in-code source
+(the runtime loader, the cook step, and the editor all resolve `builtin:<id>` the same way),
+so a fresh material draws immediately with nothing extra to manage. A real `.esshader` only
+lands on disk when you **convert** the material to a unique shader (below) or **create a
+shader** yourself.
+
+## Choosing & sharing shaders in the editor
+
+Select a material in the Content Browser and the Details panel opens its inspector with a
+**Shader** section at the top, above the parameters. The **Shader** dropdown lists every
+built-in template (as *Built-in · Unlit*, *Built-in · Lit*, …) alongside every `.esshader`
+in your project — pick one to rebind the material.
+
+![The material inspector's Shader section and parameter list](../../../assets/guides/en/material-shader.png)
+
+*The material inspector: the **Shader** section with its picker (here `dissolve.esshader`), above the **Parameters** reflected from that shader's `#pragma param`s.*
+
+Switching re-runs shader reflection: the parameter list below rebuilds from the new shader's
+`#pragma param`s, so the inspector always matches the bound shader. Because the old shader's
+parameters no longer apply, **switching clears the material's parameter values** — re-tune
+them for the new effect.
+
+- **Share one shader across materials.** An `.esshader` is a first-class asset (badge
+ **SHD**). Point several materials at the *same* `.esshader` file and they share one
+ compiled shader — edit the source once and every material that references it updates. That
+ is why the picker lists your project shaders next to the built-ins.
+- **Convert to Unique Shader.** While a material still references a `builtin:` template, the
+ section shows a **Convert to Unique Shader** button. It copies the built-in's source into
+ an editable `<material>.esshader` beside the material and re-points the material at it —
+ your parameter values carry over. Reach for it the moment you want to hand-edit a built-in
+ effect.
+- **New Shader.** To author a shader from scratch, use the Content Browser's **New Shader**
+ entry (a submenu — pick a built-in template to start from). It writes a standalone
+ `.esshader` you can then select from any material's Shader dropdown.
+
+<Aside type="note">
+ A material stores its shader as a path **relative to the material** (or a `builtin:` id),
+ not a `@uuid`. If a referenced `.esshader` is renamed or moved out from under it, the
+ Shader section flags the ref as missing and you re-pick it there.
+</Aside>
## The `.esshader` format
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdx
index 3aa122f0e..1fa51e710 100644
--- a/docs/astro/src/content/docs/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/guides/prefab.mdx
@@ -10,6 +10,84 @@ many times (enemies, pickups, bullets). Instantiate one at runtime through the
`Prefabs` resource. The prefab asset stays the single source of truth; instances can
layer their own values on top.
+## Authoring in the editor
+
+You build a prefab visually, then spawn it from code. Everything in this section happens
+in the editor; the runtime API follows below.
+
+### Create a prefab
+
+Right-click an entity in the **World Outliner → Create Prefab**. The editor extracts that
+entity and its whole subtree into `assets/prefabs/<Name>.esprefab` (named after the entity)
+and leaves your scene untouched — the originals stay put; they aren't swapped for an
+instance. To place instances, drag the `.esprefab` from the Content Browser into the scene,
+or spawn it from the **Create → Prefabs** category.
+
+<Aside type="note">
+ If the subtree references entities *outside* the selection, the editor asks first
+ (*"Expose external references?"*). Those refs are left **unbound** in the prefab, and each
+ instance can bind them to a scene entity in the Inspector.
+</Aside>
+
+### Edit a prefab — Prefab Mode
+
+Double-click a `.esprefab` (or, from an instance, **Edit Prefab**) to enter **Prefab Mode**:
+the prefab opens as its own editable entity tree in the same viewport / Outliner / Details,
+framed in a warm accent under an **Editing Prefab** banner. Add, remove, rename, reparent,
+and tune components exactly as in a scene, then **Save Prefab** — every instance in every
+scene picks up the change. **Back to Scene** returns you where you were.
+
+Not yet supported in Prefab Mode: editing a **nested** prefab in place, or a variant whose
+base isn't flat. Play and *Save As* are disabled while you're editing a prefab.
+
+![The editor in Prefab Mode, editing a Coin prefab in isolation](../../../assets/guides/en/prefab-mode.png)
+
+*Prefab Mode: the **Editing Prefab** banner with **Save Prefab** / **Back to scene**, the prefab opened as its own entity tree — every instance updates when you save.*
+
+### Instances & overrides
+
+Drop an instance into a scene and it stays linked to its source. Change a field on the
+instance and it becomes an **override** — a per-instance value layered on top of the prefab.
+The editor marks overrides so you always know what's local:
+
+- the instance's **root name is tinted warm** in the Outliner;
+- an overridden field shows a **reset arrow** (↺ *Reset to default*) and its component gets
+ an **amber dot**;
+- an Inspector filter narrows the Details panel to **only overridden fields**.
+
+Reset a single field with its ↺ button and the value falls back to the prefab's.
+
+### Apply · Revert · Unpack · Variant
+
+Right-click an instance in the Outliner (or use the Inspector's prefab bar) for the identity
+actions:
+
+| Action | What it does |
+|---|---|
+| **Edit Prefab** | Open the source in Prefab Mode. |
+| **Select Prefab Source** | Reveal the `.esprefab` in the Content Browser. |
+| **Apply to Prefab** | Push this instance's overrides **back to the source** — updating the base for *every* instance. |
+| **Revert to Prefab** | Discard this instance's overrides and re-sync it to the source. |
+| **Create Variant** | Save a new `.esprefab` that inherits the base and bakes in this instance's overrides (a prefab of a prefab). |
+| **Unpack Prefab** | Detach the subtree — its entities become ordinary scene entities and lose every prefab link. Undoable. |
+
+**Apply** is the one action that rewrites the shared asset, so it always previews an
+**itemized diff** first (*"Apply changes to prefab?"*) — edits in amber, additions in green,
+removals in red, with structural changes flagged as destructive.
+
+<Aside type="caution">
+ Deleting a `.esprefab` does **not** delete its instances. The editor warns which documents
+ reference it and moves the file to the trash (recoverable with Undo), but any surviving
+ instances become unresolvable and are dropped the next time their scene loads. Reach for
+ **Unpack** first if you want to keep the entities.
+</Aside>
+
+<Aside type="tip">
+ If you rename or remove components that some instance overrode, those overrides no longer
+ match the prefab and are dropped on scene load (with a toast). The Inspector flags the
+ affected instance and offers a **Repair** — saving the scene persists the cleaned-up state.
+</Aside>
+
## Spawn a prefab
`instantiate` loads the prefab and spawns it. It's async and returns the spawned
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index f52f2175b..fa8fc5b17 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -24,6 +24,10 @@ natively in the editor, or import it from a Tiled file with no extra setup.
## Paint in the editor
+![The Tilemap painter open beside an isometric map in the Estella editor](../../../assets/guides/en/tilemap-overview.png)
+
+*Select a `TilemapLayer` and the **Tilemap painter** opens on the left — tools on top, the tileset palette below. Paint straight into the viewport.*
+
Select an entity with a `TilemapLayer` component and the **Tilemap painter**
panel opens with the tileset palette. Pick a tool and paint directly in the
viewport — a stamp ghost previews every stroke:
@@ -43,6 +47,10 @@ viewport — a stamp ghost previews every stroke:
While a paint tool is active, `H` / `V` flip the stamp and `R` rotates it 90°.
`Q`, `W`, or `Esc` leave paint mode and hand the keys back to the transform tools.
+![Close-up of the Tilemap painter panel — tool row and tile palette](../../../assets/guides/en/tilemap-tools.png)
+
+*The painter panel up close: the tool row (brush, erase, rectangle, ellipse, line, bucket, select, eyedropper, terrain), the active tileset tab, and the tile palette you stamp from.*
+
- **Multi-tile stamps** — drag across the palette to grab a block of tiles as one
stamp. The palette is keyboard-friendly too: **arrow keys** move the selection,
**Shift + arrows** grow it into a stamp.
diff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/guides/ui-controllers.mdx
index eaf13f9bc..f5d7a9da7 100644
--- a/docs/astro/src/content/docs/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/guides/ui-controllers.mdx
@@ -120,6 +120,10 @@ label — all four states, one mechanism.
## Authoring in the editor
+![The inline Controllers strip in the inspector](../../../assets/guides/en/controllers-strip.png)
+
+*The Controllers strip: the active controller (here `theme`, inherited from the Canvas), its **pages** as chips (`sky` / `rose`), and **Gears on this entity** — every field bound to a controller.*
+
Everything above can be authored visually — no code. Select any UI entity and the
**Controllers** panel (revealed in UI mode) lists every controller it can see —
its own plus each ancestor's (inherited rows carry the owner's name), so the
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
index 0e16f733d..cf8a342f6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -33,6 +33,10 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
## 工作区
+![Estella 编辑器与一个平台跳跃场景——视口、世界大纲、细节、内容浏览器](../../../../assets/guides/zh/editor-overview.png)
+
+*默认工作区:视口居中,世界大纲与细节在右侧,内容浏览器在底部,运行控制在顶部。*
+
从外到内的默认布局:
- **活动栏(Activity Bar)** — 最左侧的图标竖条:**编辑模式**(场景 / UI / 瓦片地图)、侧面板、项目设置。
@@ -80,6 +84,10 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
拖动手柄会把整个选择当作一体、绕共享轴心变换,每次拖动是一步撤销。**Alt 拖动**选择可复制它并
拖动副本。用**方向键**微移选择(一格;按 **Shift** 为 ×10)。
+**对齐与分布**——选中两个或更多实体,视口浮层里会出现一排对齐按钮:对齐**左 / 中 / 右**边和
+**上 / 中 / 下**边。选中三个或更多时,另有两个**分布**按钮可把水平或垂直间距均分。每个都是一步
+撤销,且对每种实体都有效(精灵、UI 节点、纯 gizmo 实体一视同仁)。
+
**吸附** — 从视口的吸附下拉里开关吸附,并设置网格步长、旋转角度和缩放增量。
**显示标志(Show Flags)** — 视口下拉可开关网格、gizmo、物理和性能浮层,以及世界/本地轴朝向
@@ -137,14 +145,35 @@ Outliner 是场景的层级。你可以:
Details 是选中项的检视器。它列出实体上的每个组件及其字段——由引擎的反射元数据驱动,所以范围、
单位、枚举和 tooltip 都直接来自组件定义。加组件、改值,都会实时写回场景。编辑时字段会强制其
约束:**必填**字段为空时会被标红,数值字段写入时按声明范围 clamp,拖资产到槽位时类型不匹配会被
-拒绝。Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)
+拒绝。
+
+每个组件都是一个**可折叠区**,而且面板会记住你折了哪些——跨重新选择*以及*编辑器重启——所以检视器
+会保持你离开时的整洁。很少动的"周边"(某个控件的 `Focusable` 与 `ThemeStyle` 标签)默认折叠。
+
+当可视化控件比一排裸数字更清楚时,Details 会显示一个**专用控件**——大多用于 UI 节点:
+
+- 用于绝对定位 `UINode` 的**锚点**控件:一个可点击的 **3×3 网格**,对应九个点锚
+ (左 / 中 / 右 × 上 / 中 / 下),每个轴另带一个 **Stretch(拉伸)**开关;
+- 用于 `FlexContainer` 的 **flex**(自动布局)控件:**方向**(横向 / 纵向及其反转)、一个
+ 一点即设主轴与交叉轴对齐的 **3×3 对齐网格**、主轴**分布**(紧凑 / 两端 / 环绕 / 均匀),以及
+ **换行 / 填满**开关——**内边距**用一个四边 `sides` 控件编辑;
+- 一个内联 **Controllers(控制器)条**,把逐节点的状态创作拉进检视器:选一个状态页、给字段
+ *挂齿轮*绑定,全程不用离开面板(见 [UI 控制器](/docs/zh-cn/guides/ui-controllers/));
+- 对**材质**,一个 **Shader** 选择器,用于切换绑定的着色器——内置模板或项目里的 `.esshader`——见
+ [材质与着色器](/docs/zh-cn/guides/material/#在编辑器里选取与共享着色器)。
+
+![细节面板显示某个 UI 节点的锚点网格与布局控件](../../../../assets/guides/zh/inspector-flex.png)
+
+*一个 UI 节点的检视器:**布局内 / 绝对**切换、可点击的 **3×3 锚点网格**(每轴带 Stretch),以及 `Display: Flex`——用可视化控件取代裸数字。*
+
+Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)
编辑其参数。
## 内容浏览器
内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:
-- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、新建状态机、新建行为树、新建文件夹。
+- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、新建文件夹。
- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、
**创建材质实例**(从材质)。
@@ -186,9 +215,12 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个
**随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是
**正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/guides/tilemap/)。
-- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设、单向 / 传感器 / 材质
- 修饰)、autotile 用的**地形**集(edge/corner 邻接或多色**角 Wang**)、逐瓦片**概率**权重
- 与属性,以及**动画瓦片**(帧序列 + 逐帧时长,带实时预览)。
+- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设;单向 / 传感器 / 材质
+ 修饰),并可在放大的瓦片上**直接操纵**编辑形状:拖圆的**圆心或半径**、给多边形**点击加点 /
+ 拖动 / 点击删点**编辑**顶点**、给**单向**平台挑选实心的一侧(上 / 下 / 左 / 右)——调整大小会
+ 保留传感器 / 材质 / 密度等修饰。此外还有 autotile 用的**地形**集(edge/corner 邻接或多色
+ **角 Wang**)、逐瓦片**概率**权重与属性,以及**动画瓦片**——拖动帧缩略图**重排**,或把整段
+ 循环设成**一个统一时长**,带实时预览。
- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见
[游戏 AI](/docs/zh-cn/guides/ai/)。
- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见
diff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
index 0bca1b73b..ac6189596 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/material.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
@@ -19,17 +19,47 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一
你很少需要从空白文件开始。内容浏览器的 **New Material** 子菜单从内置模板创建材质——
同一份清单在代码里是 `BUILTIN_SHADER_TEMPLATES`:
-| 模板 | 作用 |
-|---|---|
-| **Unlit** | 纹理 × 顶点色 × `u_tint`,普通默认。 |
-| **Lit** | 被场景 2D 灯光照亮;`u_tint` + 可选 `u_normalMap`。 |
-| **Hit Flash** | 按 `u_flash` 混向 `u_flashColor`——代码里驱动它做受击闪白。 |
-| **Outline** | 彩色剪影描边(`u_outlineColor`、`u_outlineWidth`,单位纹素)。 |
-| **Dissolve** | 噪声烧蚀 + 发光边缘(`u_progress` 0→1)。 |
-| **Pixelate** | UV 量化到 `u_pixels` 网格。 |
-| **UV Scroll** | 按 `u_scrollSpeed` × 时间滚动纹理。 |
-
-每个模板就是生成在材质旁边的普通 `.esshader`——直接打开改,没有任何特殊之处。
+| 模板 | `builtin:` id | 作用 |
+|---|---|---|
+| **Unlit** | `sprite-unlit` | 纹理 × 顶点色 × `u_tint`,普通默认。 |
+| **Lit** | `sprite-lit` | 被场景 2D 灯光照亮;`u_tint` + 可选 `u_normalMap`。 |
+| **Hit Flash** | `sprite-hit-flash` | 按 `u_flash` 混向 `u_flashColor`——代码里驱动它做受击闪白。 |
+| **Outline** | `sprite-outline` | 彩色剪影描边(`u_outlineColor`、`u_outlineWidth`,单位纹素)。 |
+| **Dissolve** | `sprite-dissolve` | 噪声烧蚀 + 发光边缘(`u_progress` 0→1)。 |
+| **Pixelate** | `sprite-pixelate` | UV 量化到 `u_pixels` 网格。 |
+| **UV Scroll** | `sprite-uv-scroll` | 按 `u_scrollSpeed` × 时间滚动纹理。 |
+
+新建材质是**按 id 引用**其模板的——它存的是 `shader: "builtin:sprite-unlit"`,并**不会**在磁盘上
+写出 shader 文件。引擎从内置源码编译该模板(运行时加载器、cook 步骤、编辑器三处以同样方式解析
+`builtin:<id>`),所以新材质立即就能绘制,无需额外管理。只有当你把材质**转为独立着色器**(见下文)
+或自己**新建着色器**时,才会有真正的 `.esshader` 落到磁盘上。
+
+## 在编辑器里选取与共享着色器
+
+在内容浏览器里选中一个材质,Details 面板会打开它的检视器,顶部(参数上方)是一个 **Shader** 区。
+**Shader** 下拉框列出每个内置模板(显示为 *Built-in · Unlit*、*Built-in · Lit* ……)以及项目里
+每个 `.esshader`——选一个即可给材质重新绑定着色器。
+
+![材质检视器的 Shader 区与参数列表](../../../../assets/guides/zh/material-shader.png)
+
+*材质检视器:**Shader** 区及其选择器(这里是 `dissolve.esshader`),下方是从该着色器 `#pragma param` 反射出的**参数**。*
+
+切换会重跑着色器反射:下方的参数列表按新着色器的 `#pragma param` 重建,所以检视器始终与当前绑定的
+着色器一致。由于旧着色器的参数不再适用,**切换会清空材质的参数值**——请为新效果重新调参。
+
+- **在多个材质间共享一个着色器。** `.esshader` 是一等资源(徽标 **SHD**)。让多个材质指向*同一个*
+ `.esshader` 文件,它们就共享同一份编译后的着色器——改一次源码,所有引用它的材质一起更新。这正是
+ 选择器把项目着色器和内置模板并列的意义。
+- **Convert to Unique Shader(转为独立着色器)。** 当材质还引用着 `builtin:` 模板时,该区会显示一个
+ **Convert to Unique Shader** 按钮。它把内置源码复制成材质旁边一个可编辑的 `<material>.esshader`,
+ 并把材质重新指向它——参数值会保留。想手改内置效果时就用它。
+- **New Shader(新建着色器)。** 想从零写着色器,用内容浏览器的 **New Shader** 入口(一个子菜单——
+ 选一个内置模板作为起点)。它会写出一个独立的 `.esshader`,之后可在任意材质的 Shader 下拉框里选中。
+
+<Aside type="note">
+ 材质把着色器存为**相对于材质自身**的路径(或一个 `builtin:` id),而不是 `@uuid`。若被引用的
+ `.esshader` 被改名或移走,Shader 区会把该引用标记为缺失,你在那里重新选一次即可。
+</Aside>
## `.esshader` 格式
diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
index 61daa96da..8717e1bd1 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
@@ -9,6 +9,71 @@ import { Aside } from '@astrojs/starlight/components';
在运行时通过 `Prefabs` 资源实例化。预制体资源始终是单一权威来源;实例可以在其之上叠加
自己的值。
+## 在编辑器里创作
+
+你先在编辑器里可视化地搭出预制体,再从代码生成它。本节都发生在编辑器中;运行时 API 在下文。
+
+### 创建预制体
+
+在 **World Outliner** 里右键一个实体 → **Create Prefab**。编辑器会把该实体及其整棵子树抽取成
+`assets/prefabs/<Name>.esprefab`(以实体名命名),并且**不改动**你的场景——原实体原样留在场景里,
+不会被替换成实例。要放置实例,把 `.esprefab` 从内容浏览器拖进场景,或从 **Create → Prefabs** 分类生成。
+
+<Aside type="note">
+ 如果子树引用了选区**之外**的实体,编辑器会先询问(*"Expose external references?"*)。这些引用会在
+ 预制体里保持**未绑定**,每个实例可在检视器里把它们绑到某个场景实体。
+</Aside>
+
+### 编辑预制体——Prefab Mode
+
+双击一个 `.esprefab`(或从实例上点 **Edit Prefab**)进入 **Prefab Mode**:预制体会作为它自己的可编辑
+实体树,在同一个视口 / Outliner / Details 里打开,外框带暖色高亮,顶部是 **Editing Prefab** 横幅。
+像编辑场景一样增删、改名、重设父级、调组件,然后 **Save Prefab**——每个场景里的每个实例都会拿到这次
+改动。**Back to Scene** 把你带回原处。
+
+Prefab Mode 暂不支持:就地编辑**嵌套**预制体,或基不是扁平的变体。编辑预制体时 Play 与 *Save As* 被禁用。
+
+![编辑器处于 Prefab Mode,单独编辑一个 Coin 预制体](../../../../assets/guides/zh/prefab-mode.png)
+
+*Prefab Mode:**Editing Prefab** 横幅带 **Save Prefab** / **Back to scene**,预制体作为它自己的实体树打开——保存后每个实例都会更新。*
+
+### 实例与覆盖
+
+把实例放进场景,它会与源保持联动。改动实例上的某个字段,它就成为一条**覆盖(override)**——叠在预制体
+之上的逐实例值。编辑器会标出覆盖,让你随时知道哪些是本地的:
+
+- 实例的**根名字**在 Outliner 里被染成暖色;
+- 被覆盖的字段会显示一个**重置箭头**(↺ *Reset to default*),其组件带一个**琥珀色圆点**;
+- 检视器有一个筛选,可把 Details 面板收窄到**只看被覆盖的字段**。
+
+用字段的 ↺ 按钮重置单个字段,值会回落到预制体的值。
+
+### Apply · Revert · Unpack · Variant
+
+在 Outliner 里右键一个实例(或用检视器的 prefab 条)可执行这些身份操作:
+
+| 操作 | 作用 |
+|---|---|
+| **Edit Prefab** | 在 Prefab Mode 里打开源。 |
+| **Select Prefab Source** | 在内容浏览器里定位到该 `.esprefab`。 |
+| **Apply to Prefab** | 把这个实例的覆盖**推回源**——更新*每个*实例的基。 |
+| **Revert to Prefab** | 丢弃这个实例的覆盖,并重新同步到源。 |
+| **Create Variant** | 存出一个新的 `.esprefab`,继承基并把这个实例的覆盖烘进去(预制体的预制体)。 |
+| **Unpack Prefab** | 拆开子树——其实体变成普通场景实体,失去一切预制体关联。可撤销。 |
+
+**Apply** 是唯一会改写共享资源的操作,所以它总会先预览一份**逐条 diff**(*"Apply changes to prefab?"*)——
+改动为琥珀、新增为绿、删除为红,结构性改动会被标为破坏性。
+
+<Aside type="caution">
+ 删除一个 `.esprefab` **不会**删除它的实例。编辑器会警告哪些文档引用了它,并把文件移入回收站(可用 Undo
+ 恢复),但任何残留的实例会变得无法解析,并在其场景下次加载时被丢弃。若想保留这些实体,先用 **Unpack**。
+</Aside>
+
+<Aside type="tip">
+ 如果你改名或删除了某些实例覆盖过的组件,这些覆盖就不再与预制体匹配,会在场景加载时被丢弃(伴随一条
+ toast)。检视器会标出受影响的实例并提供 **Repair**——保存场景即把清理后的状态写入文件。
+</Aside>
+
## 生成一个预制体
`instantiate` 加载预制体并生成它。它是异步的,并返回生成的树——`root` 是新的根实体:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
index fd5fbdd75..846f59e59 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -21,6 +21,10 @@ Tiled 文件导入,无需额外设置。
## 在编辑器里绘制
+![Estella 编辑器里,瓦片画笔面板与一张等距地图并排](../../../../assets/guides/zh/tilemap-overview.png)
+
+*选中一个 `TilemapLayer`,**瓦片画笔**就在左侧打开——上面是工具,下面是图集调色板。直接在视口里作画。*
+
选中带 `TilemapLayer` 组件的实体,**瓦片画笔**面板会带着图集调色板打开。选一个工具,
直接在视口里绘制——每一笔都有印章虚影(stamp ghost)预览:
@@ -39,6 +43,10 @@ Tiled 文件导入,无需额外设置。
绘制工具激活期间,`H` / `V` 翻转印章,`R` 旋转 90°。按 `Q`、`W` 或 `Esc` 离开绘制模式,
键位交还给变换工具。
+![瓦片画笔面板特写——工具行与瓦片调色板](../../../../assets/guides/zh/tilemap-tools.png)
+
+*画笔面板特写:工具行(画笔、橡皮、矩形、椭圆、直线、油漆桶、框选、吸管、地形)、当前图集标签,以及你用来盖章的瓦片调色板。*
+
- **多瓦片印章** —— 在调色板上拖动,把一整块瓦片抓成一个印章。调色板也支持键盘:
**方向键**移动选择,**Shift + 方向键**扩成印章。
- **图章库** —— 工具行下方的书签按钮把当前画笔存进按项目持久化的图章库;点击章片
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
index 49a2c2177..e3e5317fa 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
@@ -114,6 +114,10 @@ world.insert(btn, UIGear, {
## 在编辑器里授权
+![检视器里的内联控制器条](../../../../assets/guides/zh/controllers-strip.png)
+
+*控制器条:当前激活的控制器(这里是从 Canvas 继承来的 `theme`)、以芯片形式排列的**翻页**(`sky` / `rose`),以及**此实体的绑定**——每个绑定到控制器的字段。*
+
上面的一切都能可视化授权,无需写码。选中任意 UI 实体,**控制器** 面板(在 UI 模式下弹出)
列出它能看到的所有控制器——自己的加上每个祖先的(继承行标注所有者名字),所以在被绑定的
叶子上工作时,根上的控制器依然可见、可切页: