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: 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.pngnew file mode 100644index 000000000..24474d4dcBinary files /dev/null and b/docs/astro/src/assets/guides/en/controllers-strip.png differdiff --git a/docs/astro/src/assets/guides/en/editor-overview.png b/docs/astro/src/assets/guides/en/editor-overview.pngnew file mode 100644index 000000000..a3bf40ca6Binary files /dev/null and b/docs/astro/src/assets/guides/en/editor-overview.png differdiff --git a/docs/astro/src/assets/guides/en/inspector-flex.png b/docs/astro/src/assets/guides/en/inspector-flex.pngnew file mode 100644index 000000000..24c2bcec5Binary files /dev/null and b/docs/astro/src/assets/guides/en/inspector-flex.png differdiff --git a/docs/astro/src/assets/guides/en/material-shader.png b/docs/astro/src/assets/guides/en/material-shader.pngnew file mode 100644index 000000000..a635c3531Binary files /dev/null and b/docs/astro/src/assets/guides/en/material-shader.png differdiff --git a/docs/astro/src/assets/guides/en/prefab-mode.png b/docs/astro/src/assets/guides/en/prefab-mode.pngnew file mode 100644index 000000000..5e6f21d42Binary files /dev/null and b/docs/astro/src/assets/guides/en/prefab-mode.png differdiff --git a/docs/astro/src/assets/guides/en/tilemap-overview.png b/docs/astro/src/assets/guides/en/tilemap-overview.pngnew file mode 100644index 000000000..513d12996Binary files /dev/null and b/docs/astro/src/assets/guides/en/tilemap-overview.png differdiff --git a/docs/astro/src/assets/guides/en/tilemap-tools.png b/docs/astro/src/assets/guides/en/tilemap-tools.pngnew file mode 100644index 000000000..c8fc004b0Binary files /dev/null and b/docs/astro/src/assets/guides/en/tilemap-tools.png differdiff --git a/docs/astro/src/assets/guides/zh/controllers-strip.png b/docs/astro/src/assets/guides/zh/controllers-strip.pngnew file mode 100644index 000000000..da2c927d1Binary files /dev/null and b/docs/astro/src/assets/guides/zh/controllers-strip.png differdiff --git a/docs/astro/src/assets/guides/zh/editor-overview.png b/docs/astro/src/assets/guides/zh/editor-overview.pngnew file mode 100644index 000000000..ece071e2fBinary files /dev/null and b/docs/astro/src/assets/guides/zh/editor-overview.png differdiff --git a/docs/astro/src/assets/guides/zh/inspector-flex.png b/docs/astro/src/assets/guides/zh/inspector-flex.pngnew file mode 100644index 000000000..412bbaef2Binary files /dev/null and b/docs/astro/src/assets/guides/zh/inspector-flex.png differdiff --git a/docs/astro/src/assets/guides/zh/material-shader.png b/docs/astro/src/assets/guides/zh/material-shader.pngnew file mode 100644index 000000000..04b399f9eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/material-shader.png differdiff --git a/docs/astro/src/assets/guides/zh/prefab-mode.png b/docs/astro/src/assets/guides/zh/prefab-mode.pngnew file mode 100644index 000000000..9f635a5f3Binary files /dev/null and b/docs/astro/src/assets/guides/zh/prefab-mode.png differdiff --git a/docs/astro/src/assets/guides/zh/tilemap-overview.png b/docs/astro/src/assets/guides/zh/tilemap-overview.pngnew file mode 100644index 000000000..cab72b5bdBinary files /dev/null and b/docs/astro/src/assets/guides/zh/tilemap-overview.png differdiff --git a/docs/astro/src/assets/guides/zh/tilemap-tools.png b/docs/astro/src/assets/guides/zh/tilemap-tools.pngnew file mode 100644index 000000000..a449f1554Binary files /dev/null and b/docs/astro/src/assets/guides/zh/tilemap-tools.png differdiff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdxindex 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 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 drcopies. 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 valuethey'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 itsdeclared 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).++++*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 makesassets 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), **CreateTilemap** (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 tapalette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps canbe **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 graphsfor AI. See [Gameplay AI](/docs/guides/ai/).- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. Seediff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/guides/material.mdxindex 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** submecreates 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: 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` formatdiff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdxindex 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 canlayer 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.++++*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 spawneddiff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdxindex 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+++*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 theviewport — 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.+++*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 onestamp. 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.mdxindex 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 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 thediff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdxindex 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 风格的**可## 工作区+++*默认工作区:视口居中,世界大纲与细节在右侧,内容浏览器在底部,运行控制在顶部。*+从外到内的默认布局:- **活动栏(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 节点的检视器:**布局内 / 绝对**切换、可点击的 **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.mdxindex 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** 区及其选择器(这里是 `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.mdxindex 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:**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.mdxindex 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 文件导入,无需额外设置。## 在编辑器里绘制+++*选中一个 `TilemapLayer`,**瓦片画笔**就在左侧打开——上面是工具,下面是图集调色板。直接在视口里作画。*+选中带 `TilemapLayer` 组件的实体,**瓦片画笔**面板会带着图集调色板打开。选一个工具,直接在视口里绘制——每一笔都有印章虚影(stamp ghost)预览:@@ -39,6 +43,10 @@ Tiled 文件导入,无需额外设置。绘制工具激活期间,`H` / `V` 翻转印章,`R` 旋转 90°。按 `Q`、`W` 或 `Esc` 离开绘制模式,键位交还给变换工具。+++*画笔面板特写:工具行(画笔、橡皮、矩形、椭圆、直线、油漆桶、框选、吸管、地形)、当前图集标签,以及你用来盖章的瓦片调色板。*+- **多瓦片印章** —— 在调色板上拖动,把一整块瓦片抓成一个印章。调色板也支持键盘:**方向键**移动选择,**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.mdxindex 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, {## 在编辑器里授权+++*控制器条:当前激活的控制器(这里是从 Canvas 继承来的 `theme`)、以芯片形式排列的**翻页**(`sky` / `rose`),以及**此实体的绑定**——每个绑定到控制器的字段。*+上面的一切都能可视化授权,无需写码。选中任意 UI 实体,**控制器** 面板(在 UI 模式下弹出)列出它能看到的所有控制器——自己的加上每个祖先的(继承行标注所有者名字),所以在被绑定的叶子上工作时,根上的控制器依然可见、可切页: