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: say what 9-slice and masking are FOR, not just which field sets them

esenginef8e10d3030e7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d30ba3c05..73157750b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,8 +14,67 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **The target screen now governs the running game, not just the canvas you author
+ against.** The device selection shaped the edit overlay and nothing else: a game played
+ in the viewport or the Game panel filled whatever space the dock happened to have, so a
+ project authored for a phone was only ever *run* at whatever aspect its panel was
+ dragged to. One selection now drives all three views — editing previews it, and both
+ play hosts letterbox to it. The Game panel gained an overlay bar carrying that control
+ plus a readout of the simulated size. `Design` stays the "no simulation" choice, so a
+ desktop project is unchanged. The letterbox is applied to the element hosting the realm
+ rather than inside the engine, so the realm sees a canvas of the device's shape and its
+ own `ScreenScaling` adapts exactly as it would on the hardware.
+- **A project declares the screens it tests on.** The built-in device list is a guess, and
+ a guess nobody can correct means everyone tests on approximately the wrong screen.
+ `screenPresets` in `project.esproject` adds rows to the dropdown, editable in Project
+ Settings → Display (id, name, portrait size, and safe-area insets behind a per-row
+ expander). An entry reusing a built-in id **replaces** that built-in, so a studio can
+ make "iPhone" mean the exact handset it ships to and every saved selection still
+ resolves. Presets ride version control with the project.
+- **UI: subtree opacity, a pointer gate, mask shapes, and `object-fit`.** `UINode.opacity`
+ multiplies down the tree like CSS `opacity` (fading a panel no longer means touching
+ every visual's alpha) and `UINode.pointerEvents = None` makes a node and its subtree
+ transparent to the pointer, so a decorative overlay stops eating clicks. Both resolve in
+ the same hierarchical pass that already resolves `display`. `UIMask.alphaCutoff` above 0
+ clips to the shape the mask *draws* instead of its box, so a circular avatar frame stops
+ cutting a square. `UIVisual.fit` is CSS `object-fit`: `Contain` letterboxes the image
+ inside its box, `Cover` crops it — neither distorts art whose ratio differs from its slot.
+- **A game can ship its own font.** `Text.font` is a real asset reference to an imported
+ `.ttf`/`.otf`, so it rides the same machinery as every other asset slot (dependency
+ tracking, cook inclusion, `@uuid:` refs, hot update, ref counting). Previously `Text`
+ could only name a family the *host* already had, which on native meant there was no
+ answer at all. Shipped fonts are not a second text path — the loader mints a family name
+ and the pipeline still speaks one language for "which typeface".
+- **Drag a 9-slice border on the texture instead of typing four numbers.** The asset
+ inspector draws the four guides on the preview and they are draggable; the numeric
+ fields stay in sync for exact nudges.
+- **An agent can build a scene through MCP, not just poke at one.** The editor's MCP
+ surface could observe anything and change one field at a time — fine for a tweak,
+ hopeless for authoring. `apply_scene_ops` runs a program of create/parent/component/field
+ ops as one undoable, atomic batch: if any op fails, the error names it and the whole
+ batch rolls back rather than leaving a half-built subtree.
+
### Fixed
+- **9-slice borders were dropped everywhere except the edit viewport.** A frame that
+ sliced correctly while authoring stretched the moment you pressed Play, and would have
+ stretched in every shipped build. Three separate breaks stacked: scene preloading asked
+ the import-settings resolver with the *resolved* path while suppliers key by the
+ authored ref; the editor keyed its Play payload by `@uuid:` alone, so a ported or
+ hand-authored scene holding paths got nothing; and assembling the addressable manifest
+ dropped the importer block entirely, so a packaged build had no channel for the `.meta`
+ at all. Import settings now travel with the asset through one description that Play, a
+ playable and a cooked build all read.
+- **Orientation was a clickable no-op for the default screen.** Landscape/Portrait took
+ clicks and changed nothing while `Design` was selected — there is no screen being held
+ one way when none is simulated. The rows are disabled with a note saying what enables them.
+- **Concurrent writes could corrupt `project.esproject`.** Every project-settings writer
+ did an unserialized read-modify-write of the manifest, so two edits in flight both read
+ the pre-edit file and the second landed on top of the first — losing it, or interleaving
+ into JSON that no longer parses. Typing across the fields of one settings row produced
+ exactly that. All manifest patches now queue on one chain.
- **A DragonBones armature ignored its Color.** The field was in the inspector and
did nothing — the runtime's ABI had no tint entry point, so the value was
authored, saved, and dropped. It tints now, and **multiplies** each slot's own
diff --git a/docs/astro/src/assets/guides/en/game-target-screen.png b/docs/astro/src/assets/guides/en/game-target-screen.png
new file mode 100644
index 000000000..956f7fef5
Binary files /dev/null and b/docs/astro/src/assets/guides/en/game-target-screen.png differ
diff --git a/docs/astro/src/assets/guides/en/nine-slice-drag.png b/docs/astro/src/assets/guides/en/nine-slice-drag.png
new file mode 100644
index 000000000..11fc25b91
Binary files /dev/null and b/docs/astro/src/assets/guides/en/nine-slice-drag.png differ
diff --git a/docs/astro/src/assets/guides/en/settings-screen-presets.png b/docs/astro/src/assets/guides/en/settings-screen-presets.png
new file mode 100644
index 000000000..ac8025e7e
Binary files /dev/null and b/docs/astro/src/assets/guides/en/settings-screen-presets.png differ
diff --git a/docs/astro/src/assets/guides/nine-slice.svg b/docs/astro/src/assets/guides/nine-slice.svg
new file mode 100644
index 000000000..93d270801
--- /dev/null
+++ b/docs/astro/src/assets/guides/nine-slice.svg
@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 300" width="720" height="300" role="img">
+ <style>
+ .t { font-family: ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif; }
+ .h { fill: #cbd0db; font-size: 13px; font-weight: 600; }
+ .c { fill: #8b91a0; font-size: 11px; }
+ .n { fill: #8b91a0; font-size: 10px; }
+ .bad { fill: #e8615f; font-size: 11px; font-weight: 600; }
+ .good { fill: #54c479; font-size: 11px; font-weight: 600; }
+ </style>
+
+ <!-- source texture -->
+ <text class="t h" x="12" y="18">Source · 100 × 112</text>
+ <rect x="12" y="28" width="100" height="112" rx="16" fill="#3a2f1a" stroke="#f0bd4f" stroke-width="5"/>
+ <rect x="30" y="44" width="64" height="10" rx="5" fill="#f0bd4f" opacity="0.55"/>
+ <text class="t n" x="12" y="156">rounded corners, 5px rim</text>
+
+ <!-- stretched -->
+ <text class="t h" x="180" y="18">Stretched to 450 × 130</text>
+ <rect x="180" y="28" width="450" height="130" rx="72" ry="18" fill="#3a2f1a" stroke="#e8615f" stroke-width="5"/>
+ <rect x="261" y="46" width="288" height="12" rx="6" fill="#f0bd4f" opacity="0.4"/>
+ <text class="t bad" x="180" y="176">✗ corners smeared 4.5× wide, rim thickened</text>
+
+ <!-- the grid -->
+ <text class="t h" x="12" y="214">The 3 × 3 cut</text>
+ <g stroke="#2b2f3a" stroke-width="1" fill="#14161c">
+ <rect x="12" y="224" width="36" height="26"/><rect x="48" y="224" width="86" height="26"/><rect x="134" y="224" width="34" height="26"/>
+ <rect x="12" y="250" width="36" height="24"/><rect x="48" y="250" width="86" height="24"/><rect x="134" y="250" width="34" height="24"/>
+ <rect x="12" y="274" width="36" height="18"/><rect x="48" y="274" width="86" height="18"/><rect x="134" y="274" width="34" height="18"/>
+ </g>
+ <g class="t" fill="#54c479" font-size="13" text-anchor="middle" font-weight="700">
+ <text x="30" y="242">·</text><text x="151" y="242">·</text><text x="30" y="290">·</text><text x="151" y="290">·</text>
+ </g>
+ <g class="t" fill="#5b9cf0" font-size="12" text-anchor="middle">
+ <text x="91" y="242">↔</text><text x="91" y="290">↔</text><text x="30" y="267">↕</text><text x="151" y="267">↕</text>
+ <text x="91" y="267">↔↕</text>
+ </g>
+ <text class="t n" x="12" y="222" fill="#8b91a0"></text>
+ <g class="t n" fill="#8b91a0">
+ <text x="184" y="238"><tspan fill="#54c479">·</tspan> corners — drawn 1:1, never scaled</text>
+ <text x="184" y="256"><tspan fill="#5b9cf0">↔ ↕</tspan> edges — stretched along one axis only</text>
+ <text x="184" y="274"><tspan fill="#5b9cf0">↔↕</tspan> middle — stretched both ways</text>
+ <text x="184" y="292">sliceBorder = how far in the fixed bands reach</text>
+ </g>
+
+ <!-- 9-sliced result -->
+ <text class="t h" x="430" y="214">9-sliced to the same 450 × 130</text>
+ <rect x="430" y="224" width="278" height="56" rx="16" fill="#3a2f1a" stroke="#54c479" stroke-width="5"/>
+ <rect x="448" y="238" width="242" height="10" rx="5" fill="#f0bd4f" opacity="0.55"/>
+ <text class="t good" x="430" y="296">✓ corners and rim keep their exact pixels</text>
+</svg>
diff --git a/docs/astro/src/assets/guides/object-fit.svg b/docs/astro/src/assets/guides/object-fit.svg
new file mode 100644
index 000000000..7a76cc495
--- /dev/null
+++ b/docs/astro/src/assets/guides/object-fit.svg
@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 210" width="640" height="210" role="img">
+ <style>
+ .t { font-family: ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif; }
+ .h { fill: #cbd0db; font-size: 13px; font-weight: 600; }
+ .n { fill: #8b91a0; font-size: 11px; }
+ .bad { fill: #e8615f; font-size: 11px; font-weight: 600; }
+ .good { fill: #54c479; font-size: 11px; font-weight: 600; }
+ </style>
+ <defs>
+ <clipPath id="coverClip"><rect x="470" y="46" width="110" height="110"/></clipPath>
+ <linearGradient id="art" x1="0" y1="0" x2="1" y2="0">
+ <stop offset="0" stop-color="#5b9cf0"/><stop offset="1" stop-color="#54c479"/>
+ </linearGradient>
+ </defs>
+
+ <!-- the mismatch -->
+ <text class="t h" x="12" y="18">Wide art in a square slot</text>
+ <rect x="12" y="72" width="176" height="58" rx="4" fill="url(#art)"/>
+ <circle cx="60" cy="101" r="17" fill="#0d0f14" opacity="0.45"/>
+ <text class="t n" x="12" y="150">176 × 58 image · 110 × 110 box</text>
+
+ <!-- Fill -->
+ <text class="t h" x="234" y="18">Fill · default</text>
+ <rect x="234" y="46" width="110" height="110" rx="4" fill="url(#art)"/>
+ <ellipse cx="264" cy="101" rx="10.6" ry="32" fill="#0d0f14" opacity="0.45"/>
+ <rect x="234" y="46" width="110" height="110" rx="4" fill="none" stroke="#e8615f" stroke-width="2"/>
+ <text class="t bad" x="234" y="176">✗ squashed</text>
+ <text class="t n" x="234" y="194">stretched to the box</text>
+
+ <!-- Contain -->
+ <text class="t h" x="352" y="18">Contain</text>
+ <rect x="352" y="46" width="110" height="110" rx="4" fill="none" stroke="#2b2f3a" stroke-width="1" stroke-dasharray="4 4"/>
+ <rect x="352" y="83" width="110" height="36" rx="3" fill="url(#art)"/>
+ <circle cx="382" cy="101" r="10.5" fill="#0d0f14" opacity="0.45"/>
+ <text class="t good" x="352" y="176">✓ whole image</text>
+ <text class="t n" x="352" y="194">shrinks; box keeps its size</text>
+
+ <!-- Cover -->
+ <text class="t h" x="470" y="18">Cover</text>
+ <g clip-path="url(#coverClip)">
+ <rect x="304" y="46" width="333" height="110" fill="url(#art)"/>
+ <circle cx="395" cy="101" r="32" fill="#0d0f14" opacity="0.45"/>
+ </g>
+ <rect x="470" y="46" width="110" height="110" rx="4" fill="none" stroke="#54c479" stroke-width="2"/>
+ <text class="t good" x="470" y="176">✓ fills the box</text>
+ <text class="t n" x="470" y="194">crops the overflow</text>
+</svg>
diff --git a/docs/astro/src/assets/guides/ui-mask.svg b/docs/astro/src/assets/guides/ui-mask.svg
new file mode 100644
index 000000000..5d0c9a96b
--- /dev/null
+++ b/docs/astro/src/assets/guides/ui-mask.svg
@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 220" width="640" height="220" role="img">
+ <style>
+ .t { font-family: ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif; }
+ .h { fill: #cbd0db; font-size: 13px; font-weight: 600; }
+ .n { fill: #8b91a0; font-size: 11px; }
+ .bad { fill: #e8615f; font-size: 11px; font-weight: 600; }
+ .good { fill: #54c479; font-size: 11px; font-weight: 600; }
+ </style>
+ <defs>
+ <clipPath id="boxClip"><rect x="238" y="46" width="110" height="110"/></clipPath>
+ <clipPath id="shapeClip"><circle cx="493" cy="101" r="55"/></clipPath>
+ <linearGradient id="photo" x1="0" y1="0" x2="1" y2="1">
+ <stop offset="0" stop-color="#5b9cf0"/><stop offset="0.55" stop-color="#54c479"/><stop offset="1" stop-color="#f0bd4f"/>
+ </linearGradient>
+ </defs>
+
+ <!-- inputs -->
+ <text class="t h" x="12" y="18">Child · a square photo</text>
+ <rect x="12" y="46" width="110" height="110" rx="3" fill="url(#photo)"/>
+ <text class="t h" x="12" y="186">Mask · a circular graphic</text>
+ <circle cx="67" cy="101" r="55" fill="none" stroke="#8b91a0" stroke-width="2" stroke-dasharray="5 4"/>
+ <text class="t n" x="12" y="204">drawn round; often tinted invisible</text>
+
+ <!-- box clip -->
+ <text class="t h" x="238" y="18">Default — clipped to the BOX</text>
+ <g clip-path="url(#boxClip)"><rect x="238" y="46" width="110" height="110" fill="url(#photo)"/></g>
+ <rect x="238" y="46" width="110" height="110" fill="none" stroke="#e8615f" stroke-width="2"/>
+ <circle cx="293" cy="101" r="55" fill="none" stroke="#8b91a0" stroke-width="1" stroke-dasharray="4 4" opacity="0.5"/>
+ <text class="t bad" x="238" y="186">✗ still a square</text>
+ <text class="t n" x="238" y="204">the mask is round, the clip is not</text>
+
+ <!-- shape clip -->
+ <text class="t h" x="438" y="18">alphaCutoff &gt; 0 — clipped to the SHAPE</text>
+ <g clip-path="url(#shapeClip)"><rect x="438" y="46" width="110" height="110" fill="url(#photo)"/></g>
+ <circle cx="493" cy="101" r="55" fill="none" stroke="#54c479" stroke-width="2"/>
+ <text class="t good" x="438" y="186">✓ the avatar is round</text>
+ <text class="t n" x="438" y="204">tests the sprite's alpha, not its tint</text>
+</svg>
diff --git a/docs/astro/src/assets/guides/zh/game-target-screen.png b/docs/astro/src/assets/guides/zh/game-target-screen.png
new file mode 100644
index 000000000..250bd9723
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/game-target-screen.png differ
diff --git a/docs/astro/src/assets/guides/zh/nine-slice-drag.png b/docs/astro/src/assets/guides/zh/nine-slice-drag.png
new file mode 100644
index 000000000..10d54a939
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/nine-slice-drag.png differ
diff --git a/docs/astro/src/assets/guides/zh/settings-screen-presets.png b/docs/astro/src/assets/guides/zh/settings-screen-presets.png
new file mode 100644
index 000000000..1ad133394
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/settings-screen-presets.png differ
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index ba999051b..51c0e2860 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -127,14 +127,58 @@ 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 — *simulates* a target screen (iPhone / iPad / 1080p …) in any mode:
- draws the device's aspect as letterbox bars + safe-area insets over your scene, so you
- preview how it fits. A preview only — it does **not** change your design resolution.
+- **Device** dropdown — picks the **target screen** (iPhone / iPad / 1080p …) in any mode.
+ While editing it draws that screen's aspect as letterbox bars + safe-area insets over
+ your scene; when you press **Play** the running game is letterboxed to the same shape,
+ in the viewport and in the **Game** panel alike. It never changes your design
+ resolution — it changes what you are looking at it *through*.
+- **Orientation** (same dropdown) — swaps the device's width and height. It applies to a
+ **device**, so it is disabled while `Design` is selected: with no screen simulated
+ there is nothing to rotate.
- **Camera Fit** (Project Settings → Display) — how the **main camera** scales the design
resolution, independent of any UI Canvas. `None` (default) keeps the camera's own
orthoSize; any other mode letterboxes the game the same way on every device, and the
device preview then shows the **real** framing (WYSIWYG for gameplay, not just UI).
+**One screen, edit and run.** The `Design` entry is the "no simulation" choice: the game
+fills whatever space the panel has, which is what authoring for desktop wants. Pick any
+real device and both the edit overlay and the running game commit to its shape — so a
+project authored for a phone is never only ever *run* at whatever aspect the dock
+happened to be dragged to.
+
+![A scene running in the viewport, framed to the selected target screen rather than to the panel's own shape](../../../assets/guides/en/game-target-screen.png)
+
+### Project screen presets
+
+The built-in device list is a guess. A team that ships to specific hardware corrects it
+in **Project Settings → Display → Screen presets**: add a row with an id, a name and the
+portrait size, and it joins the dropdown for everyone who opens the project.
+
+- **Id** is what a saved selection resolves through, so keep it stable. Reusing a built-in
+ id (`iphone`, `ipad`, `1080p`, `720p`) **replaces** that built-in rather than sitting
+ beside it — which is how a studio makes "iPhone" mean the exact handset it tests on.
+- **Sizes are stored portrait** (width ≤ height), like the built-ins, so the orientation
+ toggle means the same thing for every screen.
+- **Safe area** (the row's ▸ expander) sets the notch / home-indicator insets in device
+ pixels. Leave them at zero and nothing is written to the project file — the viewport's
+ *Safe area* overlay then has nothing to draw for that screen.
+
+![Project Settings showing a screen preset row with its safe-area insets expanded](../../../assets/guides/en/settings-screen-presets.png)
+
+Presets live in `project.esproject`, so they are shared through version control:
+
+```json title="project.esproject"
+{
+ "screenPresets": [
+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
+ {
+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }
+ }
+ ]
+}
+```
+
## Building a scene
### Creating entities
@@ -203,6 +247,18 @@ widget** — most of them for UI nodes:
Details also serves as the **asset inspector**: select an asset in the Content Browser to
edit its import settings or, for a material, its parameters.
+**Dragging a 9-slice border.** A texture's slice border decides where a `NineSlice` panel
+keeps its corners crisp, and typing four numbers means guessing at them. Select the
+texture and drag the four guides directly on the preview instead — the numeric fields stay
+in sync, so you can nudge one edge exactly after eyeballing the rest.
+
+Import settings describe the **asset**, not the scene that happens to use it, and they now
+reach every place the texture is drawn: the edit viewport, Play (in the viewport and in
+the Game panel), and a packaged build. A frame that slices correctly while you author it
+slices correctly in the shipped game.
+
+![Dragging the 9-slice border guides on a texture in the asset inspector](../../../assets/guides/en/nine-slice-drag.png)
+
## The Content Browser
The Content Browser is your project's asset explorer. Its **create** menu makes new
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdx
index 39cf240d0..565bbfa28 100644
--- a/docs/astro/src/content/docs/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/guides/ui-text.mdx
@@ -215,11 +215,26 @@ addStartupSystem(buildBubble);
## Custom fonts
-`fontFamily` is resolved by the platform's **Canvas2D** when glyphs rasterize —
-any family the host page can resolve works: system fonts, or a web font the page
-loads (CSS `@font-face` or the `FontFace` API). The SDK does not fetch font
-files for the `Text` component itself; make sure a web font is loaded before the
-text first renders, or its glyphs rasterize with the fallback font.
+There are two ways to say *which typeface*, and they end in the same place — a family
+name the platform's text stack rasterizes with.
+
+**Ship the font with the game (`Text.font`).** Import a `.ttf` / `.otf` / `.woff2` into
+the project and assign it to the `font` slot in the inspector. It is a real asset
+reference, so it rides the machinery every other asset slot rides: dependency tracking,
+cook inclusion, `@uuid:` refs, hot update, ref counting. The loader registers the file
+with the platform's text stack under a family name it mints, and `Text` uses that name —
+so a shipped font is not a second text path, just another way to arrive at a family. This
+is the answer on **native**, where there is no page to load a web font into.
+
+**Name a font the host already has (`fontFamily`).** Resolved by the platform's
+**Canvas2D** on the web (or the OS font matcher on native) when glyphs rasterize — system
+fonts, or a web font the page loads itself (CSS `@font-face` or the `FontFace` API). The
+SDK does not fetch these; make sure a web font is loaded before the text first renders,
+or its glyphs rasterize with the fallback font.
+
+`font` wins when both are set. Prefer it for anything your brand depends on: `fontFamily`
+alone silently falls back to a different typeface on a machine that lacks the family, and
+that failure only shows up on someone else's device.
Separately, **bitmap font assets** (`.fnt` / `.bmfont`) load through the asset
pipeline — `Assets.loadFont(ref)` resolves the `.fnt`, loads its page texture,
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdx
index bd5ffe0cc..e13011f09 100644
--- a/docs/astro/src/content/docs/guides/ui.mdx
+++ b/docs/astro/src/content/docs/guides/ui.mdx
@@ -114,10 +114,74 @@ Each layer builds on the one before it:
| `Tiled` | `tileSize` | Texture repeated across the box. |
| `Filled` | `fillAmount`, `fillMethod`, `fillOrigin` | Cropped fill (health/progress bars, cooldown rings). |
+#### What 9-slice is for
+
+A button drawn at 100×112 and used at 450×130 is stretched 4.5× wide — and the border,
+the rounded corners and the highlight stretch with it. The frame looks melted, and you
+cannot fix it by drawing a second image for every button size in the game.
+
+9-slice cuts the image into a 3×3 grid and scales each piece differently:
+
+![A source button texture stretched wide smears its corners; cut into a 3×3 grid the corners stay 1:1, the edges stretch along one axis and only the middle stretches both ways](../../../assets/guides/nine-slice.svg)
+
+`sliceBorder` is those four numbers: how far in from each edge the "do not stretch" band
+reaches. Corners keep their exact pixels at any size, so one 100×112 texture serves a tiny
+tooltip and a full-width banner. The border belongs to the **image**, not to the entity
+using it, so it is a texture import setting — set it once and every `NineSlice` that
+references the texture is sliced the same way. See
+[dragging the border](/docs/guides/editor/#the-content-browser) in the asset inspector.
+
+#### What a mask is for
+
+A mask answers "show this content, but only inside that region". The classic cases are a
+square avatar photo that has to appear circular, and a scrolling list whose items must
+disappear at the edge of their viewport rather than spilling over the rest of the screen.
+
+Add `UIMask` to a node and its children are clipped to that node. By default the clip is
+the node's **box** — a rectangle. That is enough for a list viewport, but it is why a
+circular avatar frame used to still cut a square: the mask graphic was round, the clip
+was not. `alphaCutoff` above 0 switches the clip to the shape the mask actually draws.
+
+![A square photo under a circular mask: clipped to the box it stays square; with alphaCutoff above zero it is clipped to the circle](../../../assets/guides/ui-mask.svg)
+
`UIVisual.enabled` hides this entity's visual only; `UINode.display = None`
removes the node **and its whole subtree** from layout, rendering, and
hit-testing. Add `UIMask` to a node to clip its children to the box.
+**`UIVisual.fit` — CSS `object-fit`.** By default an image is *stretched* to its box, so
+art whose ratio differs from its slot is visibly squashed. `Contain` shrinks the quad
+until the whole image fits (the box keeps its layout size); `Cover` keeps the box and
+crops the UV instead. Neither ever distorts the artwork. `NineSlice` and `Tiled` ignore
+it — adapting to the box is their whole job.
+
+![Wide art in a square slot: Fill squashes it, Contain shrinks the whole image inside the box, Cover fills the box and crops the overflow](../../../assets/guides/object-fit.svg)
+
+**`UIMask.alphaCutoff` — clip to the shape, not the box.** A stencil mask clips to the
+mask's *rectangle*, so a circular avatar frame still cut a square. Above `0` it clips to
+the shape the mask actually draws, testing the **sprite's** alpha (not the tinted result,
+because a mask graphic is routinely tinted to near-zero alpha so it masks without being
+seen). `0` stays the default, so scenes authored against box clipping are unchanged.
+
+### Subtree opacity and pointer gating
+
+`UINode` carries two fields that resolve **hierarchically**, in the same pass that already
+resolves `display`:
+
+| Field | Default | Effect |
+|---|---|---|
+| `opacity` | `1` | Multiplied down the tree like CSS `opacity`. Fades a whole panel with one value. |
+| `pointerEvents` | `Auto` | `None` makes the node **and its subtree** transparent to the pointer — still drawn, hits pass straight through. |
+
+These are the "CanvasGroup" knobs: fading a panel used to mean touching every visual's
+`color.a`, and a decorative overlay had no way to stop eating clicks (`Interactable.blockRaycast`
+is per-entity, not inherited). `opacity` follows CSS semantics — it multiplies per visual
+rather than compositing the subtree offscreen, the same trade every UI toolkit makes.
+
+```ts
+// Fade a whole dialog out and let clicks through while it animates away.
+world.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvents.None });
+```
+
## Editor or code
![A UI Canvas laid out in the editor viewport](../../../assets/guides/en/ui-screen.png)
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 cf8a342f6..e4f73c34f 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -110,12 +110,48 @@ UI Canvas 也能在真机上预览。场景里有 Canvas 时,UI 会额外按其
- **Design** 下拉(视口工具栏)——设置设计分辨率并成帧到它(可撤销)。有 Canvas 时改的是该 Canvas,
否则改的是项目值。
-- **Device** 下拉——在任意模式*模拟*一个目标屏幕(iPhone / iPad / 1080p …):在场景上画出该设备宽高比的
- letterbox 黑边和安全区,预览它如何适配。只是预览,**不会**改动你的设计分辨率。
+- **Device** 下拉——在任意模式选择**目标屏幕**(iPhone / iPad / 1080p …)。编辑时它在场景上画出该
+ 屏幕宽高比的 letterbox 黑边和安全区;按下**运行**后,运行中的游戏也会被 letterbox 成同一形状——
+ 视口内运行和 **游戏** 面板都是如此。它不会改动你的设计分辨率,改的是你**透过什么**去看它。
+- **方向**(同一下拉)——交换设备的宽和高。它作用于**设备**,所以选中 `设计` 时是禁用的:没有模拟
+ 任何屏幕,也就没有东西可转。
- **相机适配**(项目设置 → 显示)——**主相机**如何按设计分辨率缩放,独立于任何 UI Canvas。`无`(默认)
保持相机自身的 orthoSize;其他模式让游戏在每台设备上一致 letterbox,设备预览也随之显示**真实**取景
(玩法也所见即所得,不止 UI)。
+**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向
+桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机
+创作的项目,不会只能在"面板恰好被拖成的比例"下运行。
+
+![在视口内运行的场景,按选定的目标屏幕取景,而不是按面板自身的形状](../../../../assets/guides/zh/game-target-screen.png)
+
+### 项目屏幕预设
+
+内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:
+添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。
+
+- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、
+ `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。
+- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。
+- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——
+ 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。
+
+![项目设置中展开了安全区域的屏幕预设行](../../../../assets/guides/zh/settings-screen-presets.png)
+
+预设保存在 `project.esproject` 中,因此可以随版本控制共享:
+
+```json title="project.esproject"
+{
+ "screenPresets": [
+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },
+ {
+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,
+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }
+ }
+ ]
+}
+```
+
## 搭建场景
### 创建实体
@@ -169,6 +205,16 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)
编辑其参数。
+**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字
+等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好
+其余边,再精确微调某一条。
+
+导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:
+编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的
+游戏里同样正确。
+
+![在资产检视器中拖动纹理的九宫格参考线](../../../../assets/guides/zh/nine-slice-drag.png)
+
## 内容浏览器
内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
index feb6f5b0d..f3001dfa0 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
@@ -191,10 +191,21 @@ addStartupSystem(buildBubble);
## 自定义字体
-`fontFamily` 在字形栅格化时由平台的 **Canvas2D** 解析——宿主页面能解析的任何
-字体族都可用:系统字体,或页面自己加载的 Web 字体(CSS `@font-face` 或
-`FontFace` API)。SDK 不会替 `Text` 组件抓取字体文件;请确保 Web 字体在文本
-首次渲染前已加载,否则其字形会用回退字体栅格化。
+指定*用哪套字体*有两条途径,它们最终都落到同一处——平台文本栈据以栅格化的字体族名。
+
+**把字体随游戏一起发布(`Text.font`)。** 把 `.ttf` / `.otf` / `.woff2` 导入项目,
+在检查器里赋给 `font` 槽位。它是真正的资产引用,因此享有其他资产槽位一样的机制:
+依赖追踪、cook 收录、`@uuid:` 引用、热更新、引用计数。加载器会用它铸造的族名把文件
+注册进平台文本栈,`Text` 再用这个名字——所以自带字体不是第二条文本路径,只是抵达
+族名的另一种方式。在**原生**平台这是唯一答案,那里没有页面可供加载 Web 字体。
+
+**指定宿主已有的字体(`fontFamily`)。** 字形栅格化时由平台的 **Canvas2D**(原生上
+则是系统字体匹配器)解析——系统字体,或页面自己加载的 Web 字体(CSS `@font-face` 或
+`FontFace` API)。SDK 不会替你抓取这些文件;请确保 Web 字体在文本首次渲染前已加载,
+否则其字形会用回退字体栅格化。
+
+两者都设置时 `font` 优先。凡是品牌依赖的字体都建议用它:只写 `fontFamily` 时,缺少
+该字体族的机器会静默回退成另一套字体,而这种失败只会在别人的设备上暴露。
另有**位图字体资产**(`.fnt` / `.bmfont`)走资产管线——`Assets.loadFont(ref)`
解析 `.fnt`、加载其页纹理,返回 `FontResult`(`{ handle }`)。它们驱动
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
index 5a074d293..2567af699 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
@@ -108,9 +108,64 @@ addStartupSystem(buildPauseMenu);
| `Tiled` | `tileSize` | 纹理在盒内平铺重复。 |
| `Filled` | `fillAmount`、`fillMethod`、`fillOrigin` | 裁剪式填充(血条/进度条、冷却环)。 |
+#### 九宫格是用来做什么的
+
+一张按 100×112 绘制的按钮图,用在 450×130 的位置上时会被横向拉伸 4.5 倍——边框、圆角和高光
+一并被拉长,整个框看起来像是化开了。而你不可能为游戏里每一种按钮尺寸都画一张图。
+
+九宫格把图切成 3×3 的网格,每一块按不同方式缩放:
+
+![原图被直接拉宽后四角糊掉;切成 3×3 后四角保持 1:1,四边只沿一个轴拉伸,只有中间双向拉伸](../../../../assets/guides/nine-slice.svg)
+
+`sliceBorder` 就是那四个数字:从每条边往内多远是"不该拉伸"的区带。四角在任何尺寸下都保留自己
+的精确像素,于是同一张 100×112 的纹理既能做小提示框,也能做通栏横幅。这个边框属于**图像**本身,
+而不属于用到它的实体,所以它是纹理的导入设置——设一次,引用该纹理的每个 `NineSlice` 都按同样
+方式切片。参见资产检视器中的[拖拽边框](/zh-cn/docs/guides/editor/#内容浏览器)。
+
+#### 遮罩是用来做什么的
+
+遮罩回答的是"显示这块内容,但只在那个区域内可见"。典型场景有两个:方形的头像照片需要呈现为
+圆形;滚动列表的条目必须在视口边缘消失,而不是溢出到屏幕其余部分。
+
+给节点加上 `UIMask`,它的子项就会被裁剪到该节点。默认裁剪的是节点的**外框**——一个矩形。
+这对列表视口足够了,但也正是圆形头像框以前仍然裁出方形的原因:遮罩图形是圆的,裁剪范围不是。
+`alphaCutoff` 大于 0 时,裁剪范围切换为遮罩实际绘制出的形状。
+
+![方形照片配圆形遮罩:按外框裁剪时仍是方的;alphaCutoff 大于 0 后被裁成圆形](../../../../assets/guides/ui-mask.svg)
+
`UIVisual.enabled` 只隐藏本实体的视觉;`UINode.display = None` 把该节点**连同整棵
子树**从布局、渲染和命中测试中移除。给节点加 `UIMask` 可把子项裁剪到盒内。
+**`UIVisual.fit` —— CSS `object-fit`。** 默认情况下图片会被*拉伸*到它的盒子,于是比例与
+槽位不同的美术资源会明显被压扁。`Contain` 缩小四边形直到整张图放得下(盒子保持它的布局尺寸);
+`Cover` 保持盒子、改为裁剪 UV。两者都不会让美术变形。`NineSlice` 和 `Tiled` 会忽略它——
+适配盒子本来就是它们的职责。
+
+![宽图放进方形槽位:Fill 把它压扁,Contain 缩小到整张图放得下,Cover 填满盒子并裁掉溢出部分](../../../../assets/guides/object-fit.svg)
+
+**`UIMask.alphaCutoff` —— 按形状裁剪,而不是按外框。** 模板遮罩裁剪的是遮罩的*矩形*,所以
+圆形头像框裁出来仍是方的。大于 `0` 时它按遮罩实际绘制的形状裁剪,判定用的是**精灵**的 alpha
+(而非着色后的结果——遮罩图形常被调到接近全透明,好让它遮挡而不被看见)。默认仍是 `0`,因此
+按外框裁剪创作的场景不受影响。
+
+### 子树透明度与指针门
+
+`UINode` 上有两个**沿层级解析**的字段,与已有的 `display` 在同一趟里完成:
+
+| 字段 | 默认 | 效果 |
+|---|---|---|
+| `opacity` | `1` | 像 CSS `opacity` 一样沿树相乘。一个值淡出整块面板。 |
+| `pointerEvents` | `Auto` | `None` 让该节点**及其子树**对指针透明——照常绘制,点击直接穿过。 |
+
+这就是 "CanvasGroup" 那组旋钮:以前淡出一块面板意味着挨个改每个视觉的 `color.a`,而装饰性
+覆盖层没有办法不吃掉点击(`Interactable.blockRaycast` 是逐实体的,不继承)。`opacity` 遵循
+CSS 语义——逐视觉相乘而不是把子树离屏合成,这是每个 UI 工具包都会做的取舍。
+
+```ts
+// 淡出整个对话框,并在它退场动画期间让点击穿过。
+world.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvents.None });
+```
+
## 编辑器还是代码
![在编辑器视口里排好的一个 UI Canvas](../../../../assets/guides/zh/ui-screen.png)