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: say what 9-slice and masking are FOR, not just which field sets them
esenginef8e10d3030e7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 anddid nothing — the runtime's ABI had no tint entry point, so the value wasauthored, saved, and dropped. It tints now, and **multiplies** each slot's owndiff --git a/docs/astro/src/assets/guides/en/game-target-screen.png b/docs/astro/src/assets/guides/en/game-target-screen.pngnew file mode 100644index 000000000..956f7fef5Binary files /dev/null and b/docs/astro/src/assets/guides/en/game-target-screen.png differdiff --git a/docs/astro/src/assets/guides/en/nine-slice-drag.png b/docs/astro/src/assets/guides/en/nine-slice-drag.pngnew file mode 100644index 000000000..11fc25b91Binary files /dev/null and b/docs/astro/src/assets/guides/en/nine-slice-drag.png differdiff --git a/docs/astro/src/assets/guides/en/settings-screen-presets.png b/docs/astro/src/assets/guides/en/settings-screen-presets.pngnew file mode 100644index 000000000..ac8025e7eBinary files /dev/null and b/docs/astro/src/assets/guides/en/settings-screen-presets.png differdiff --git a/docs/astro/src/assets/guides/nine-slice.svg b/docs/astro/src/assets/guides/nine-slice.svgnew file mode 100644index 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.svgnew file mode 100644index 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.svgnew file mode 100644index 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 > 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.pngnew file mode 100644index 000000000..250bd9723Binary files /dev/null and b/docs/astro/src/assets/guides/zh/game-target-screen.png differdiff --git a/docs/astro/src/assets/guides/zh/nine-slice-drag.png b/docs/astro/src/assets/guides/zh/nine-slice-drag.pngnew file mode 100644index 000000000..10d54a939Binary files /dev/null and b/docs/astro/src/assets/guides/zh/nine-slice-drag.png differdiff --git a/docs/astro/src/assets/guides/zh/settings-screen-presets.png b/docs/astro/src/assets/guides/zh/settings-screen-presets.pngnew file mode 100644index 000000000..1ad133394Binary files /dev/null and b/docs/astro/src/assets/guides/zh/settings-screen-presets.png differdiff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdxindex 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 designresolution, independent of any UI Canvas. `None` (default) keeps the camera's ownorthoSize; any other mode letterboxes the game the same way on every device, and thedevice preview then shows the **real** framing (WYSIWYG for gameplay, not just UI).+**One screen, edit and run.** The `Design` entry is the "no simulation" choice: the game+fills whatever space the panel has, which is what authoring for desktop wants. Pick any+real device and both the edit overlay and the running game commit to its shape — so a+project authored for a phone is never only ever *run* at whatever aspect the dock+happened to be dragged to.++++### Project screen presets++The built-in device list is a guess. A team that ships to specific hardware corrects it+in **Project Settings → Display → Screen presets**: add a row with an id, a name and the+portrait size, and it joins the dropdown for everyone who opens the project.++- **Id** is what a saved selection resolves through, so keep it stable. Reusing a built-in+ id (`iphone`, `ipad`, `1080p`, `720p`) **replaces** that built-in rather than sitting+ beside it — which is how a studio makes "iPhone" mean the exact handset it tests on.+- **Sizes are stored portrait** (width ≤ height), like the built-ins, so the orientation+ toggle means the same thing for every screen.+- **Safe area** (the row's ▸ expander) sets the notch / home-indicator insets in device+ pixels. Leave them at zero and nothing is written to the project file — the viewport's+ *Safe area* overlay then has nothing to draw for that screen.++++Presets live in `project.esproject`, so they are shared through version control:++```json title="project.esproject"+{+ "screenPresets": [+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },+ {+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }+ }+ ]+}+```+## Building a scene### Creating entities@@ -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 toedit its import settings or, for a material, its parameters.+**Dragging a 9-slice border.** A texture's slice border decides where a `NineSlice` panel+keeps its corners crisp, and typing four numbers means guessing at them. Select the+texture and drag the four guides directly on the preview instead — the numeric fields stay+in sync, so you can nudge one edge exactly after eyeballing the rest.++Import settings describe the **asset**, not the scene that happens to use it, and they now+reach every place the texture is drawn: the edit viewport, Play (in the viewport and in+the Game panel), and a packaged build. A frame that slices correctly while you author it+slices correctly in the shipped game.+++## The Content BrowserThe Content Browser is your project's asset explorer. Its **create** menu makes newdiff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdxindex 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 assetpipeline — `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.mdxindex 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:++++`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.+++`UIVisual.enabled` hides this entity's visual only; `UINode.display = None`removes the node **and its whole subtree** from layout, rendering, andhit-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.++++**`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 codediff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdxindex 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)。+**一个屏幕,编辑与运行一致。** `设计` 这一项是"不模拟"的选择:游戏填满面板给它的空间,这正是面向+桌面创作时想要的。选中任何真实设备,编辑时的叠加层和运行中的游戏都会遵守它的形状——于是一个为手机+创作的项目,不会只能在"面板恰好被拖成的比例"下运行。++++### 项目屏幕预设++内置设备清单只是一种猜测。发行到特定硬件的团队可以在**项目设置 → 显示 → 屏幕预设**里修正它:+添加一行,填写标识、名称和竖屏尺寸,它就会出现在下拉中,对每个打开该项目的人生效。++- **标识**是已保存的选择据以解析的键,请保持稳定。使用与内置相同的标识(`iphone`、`ipad`、+ `1080p`、`720p`)会**替换**该内置项而不是并列——工作室正是这样让"iPhone"指向自己实测的那台机器。+- **尺寸按竖屏存储**(宽 ≤ 高),与内置项一致,这样方向开关对每块屏幕的含义都相同。+- **安全区域**(行尾的 ▸ 展开)以设备像素设置刘海 / Home 条的内缩。全部留空则不会写入项目文件——+ 视口的 *安全区域* 叠加层对该屏幕也就没有东西可画。++++预设保存在 `project.esproject` 中,因此可以随版本控制共享:++```json title="project.esproject"+{+ "screenPresets": [+ { "id": "steam-deck", "label": "Steam Deck", "width": 800, "height": 1280 },+ {+ "id": "iphone", "label": "iPhone 15 Pro", "width": 1179, "height": 2556,+ "safe": { "top": 59, "bottom": 34, "left": 0, "right": 0 }+ }+ ]+}+```+## 搭建场景### 创建实体@@ -169,6 +205,16 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即可编辑其导入设置,或(对材质)编辑其参数。+**拖拽九宫格边框。** 纹理的切片边框决定了 `NineSlice` 面板在哪里保持四角锐利,而填四个数字+等于在猜。改为选中纹理后直接在预览图上拖动四条参考线——数值字段会同步,于是你可以先目测调好+其余边,再精确微调某一条。++导入设置描述的是**资产**本身,而不是恰好用到它的场景;它们现在会抵达纹理被绘制的每一处:+编辑视口、运行时(视口内运行与游戏面板)、以及打包后的构建。创作时切片正确的框,在发布的+游戏里同样正确。+++## 内容浏览器内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产: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.mdxindex 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.mdxindex 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 的网格,每一块按不同方式缩放:++++`sliceBorder` 就是那四个数字:从每条边往内多远是"不该拉伸"的区带。四角在任何尺寸下都保留自己+的精确像素,于是同一张 100×112 的纹理既能做小提示框,也能做通栏横幅。这个边框属于**图像**本身,+而不属于用到它的实体,所以它是纹理的导入设置——设一次,引用该纹理的每个 `NineSlice` 都按同样+方式切片。参见资产检视器中的[拖拽边框](/zh-cn/docs/guides/editor/#内容浏览器)。++#### 遮罩是用来做什么的++遮罩回答的是"显示这块内容,但只在那个区域内可见"。典型场景有两个:方形的头像照片需要呈现为+圆形;滚动列表的条目必须在视口边缘消失,而不是溢出到屏幕其余部分。++给节点加上 `UIMask`,它的子项就会被裁剪到该节点。默认裁剪的是节点的**外框**——一个矩形。+这对列表视口足够了,但也正是圆形头像框以前仍然裁出方形的原因:遮罩图形是圆的,裁剪范围不是。+`alphaCutoff` 大于 0 时,裁剪范围切换为遮罩实际绘制出的形状。+++`UIVisual.enabled` 只隐藏本实体的视觉;`UINode.display = None` 把该节点**连同整棵子树**从布局、渲染和命中测试中移除。给节点加 `UIMask` 可把子项裁剪到盒内。+**`UIVisual.fit` —— CSS `object-fit`。** 默认情况下图片会被*拉伸*到它的盒子,于是比例与+槽位不同的美术资源会明显被压扁。`Contain` 缩小四边形直到整张图放得下(盒子保持它的布局尺寸);+`Cover` 保持盒子、改为裁剪 UV。两者都不会让美术变形。`NineSlice` 和 `Tiled` 会忽略它——+适配盒子本来就是它们的职责。++++**`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 });+```+## 编辑器还是代码