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: six things v0.37.0 and v0.38.0 shipped that the guides never mentioned

yhhce65a483da67
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index c05e26489..fffa2b3a4 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -268,10 +268,16 @@ The Content Browser is your project's asset explorer. Its **create** menu makes
assets in place:
- New Scene, New Animation, New Input Map, New Material, New Material Graph,
- **New Shader**, New State Machine, New Behavior Tree, New Folder.
+ **New Shader**, New State Machine, New Behavior Tree, **New Script…**, New Folder.
- Context actions per asset type: **Create Tileset** (from a texture), **Create
Tilemap** (from a tileset), **Create Material Instance** (from a material).
+**New Script…** is the one that writes more than a file: a module nothing imports is
+never bundled and its component never reaches Add Component, so the dialog also adds
+the one line in your project's script entry that pulls it in — which entry depending
+on whether you're making a component or a system. See
+[Scripting](/docs/guides/scripting/#the-new-script-dialog).
+
**Import** by dragging files in from Finder / Explorer, or via Import…. Each asset gets
a `.meta` sidecar the first time it's seen. Per-asset context actions include Rename,
Duplicate, Copy Path, Copy Reference, **Find Usages**, Show in Explorer, and Delete.
diff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/guides/mcp.mdx
index 3b89bda6d..ee2992a8c 100644
--- a/docs/astro/src/content/docs/guides/mcp.mdx
+++ b/docs/astro/src/content/docs/guides/mcp.mdx
@@ -98,6 +98,7 @@ reconnects automatically rather than stranding the agent.
| Edit scenes | `apply_scene_ops` (batch authoring), `create_entity` (the Create-menu catalog via `list_entity_templates`), `set_field`, `set_entity_xy`, `set_parent`, `duplicate_entity`, `undo` / `redo` |
| Projects & assets | `create_project` / `open_project`, `open_scene`, `open_asset` (any asset in its own editor), `get_document`, `save_scene`, `create_scene_file`, `create_asset`, `import_assets`, `list_assets`, `get_import_settings` / `set_import_settings` |
| Prefabs | `create_prefab_from_entity`, `edit_prefab` / `exit_prefab_mode` (Prefab Mode), `apply_prefab`, `revert_prefab`, `unpack_prefab`, `create_prefab_variant` |
+| Behaviour without code | `get_event_bindings` / `set_event_bindings` (wire a button), `add_component` / `remove_component` |
| Game code | `read_project_file`, `write_project_file`, `list_project_files` |
| Run & ship | `toggle_play` + `get_play_state`, `export_game` (web / desktop / wechat / playable) |
@@ -152,6 +153,31 @@ hundreds of KB of JSON, which does not belong in a chat message. Write it with
{ "opsPath": "assets/scenes/shop.ops.json", "label": "Build the shop" }
```
+### Wiring a button
+
+A scene can give a button behaviour without any game code — an
+[Event Binding](/docs/guides/events/) row says *when this event fires, run that
+named action*. `set_event_bindings` replaces an entity's rows in **one undo step**
+(an empty list unwires it), and `get_event_bindings` reads them back:
+
+```json
+{ "entity": 42, "rows": [
+ { "event": "click", "action": "panel.open",
+ "params": { "prefab": "assets/prefabs/Shop.esprefab" } }
+] }
+```
+
+`action` is any name in the action registry — an engine built-in (`property.set`,
+`ui.setVisible`, `fsm.fire`, …) or one the project registered — and `target` names
+another entity to run it on, resolved nearest-first from this one.
+
+<Aside type="caution">
+`EventBinding` has **no Add Component entry** (the Details panel adds it implicitly
+when you add the first wire), so `add_component` with that name will not create one —
+`set_event_bindings` is its door. `add_component` refuses an unknown component name
+rather than silently accepting it, so a typo fails loudly.
+</Aside>
+
<Aside type="note">
Some things live in **import settings**, not on a component — a texture's 9-slice
border is the one that bites: a `UIVisual` set to NineSlice reads its border from
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/guides/mobile.mdx
index 0e059c7e6..37f2cc72e 100644
--- a/docs/astro/src/content/docs/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/guides/mobile.mdx
@@ -49,6 +49,30 @@ project under **Output** in the Android section when the game needs to add an SD
permission or an Activity of its own — that is the same shape iOS has always had,
where Xcode does the assembling.
+## What a packaged game runs on
+
+| | Android | iOS |
+|---|---|---|
+| Minimum OS | **Android 10** (API 29) | **iOS 17.0** |
+| Declared target | API 33 | — |
+| CPU | `arm64-v8a` (every real device) + `x86_64` (the emulator) | arm64 device + simulator slice |
+| GPU | **Vulkan 1.0.3 required** — declared `required="true"`, so a device without it does not see the app on Play | Metal |
+
+Android's floor is 29 because the engine's font path calls `AFontMatcher_create`,
+which is API 29 — below that there is nothing to fall back to. It was **declared** as
+26 through v0.37.0, which was a claim rather than a capability: those builds install
+on Android 10 and 11 and then fail to start, because the NDK was told to build against
+a higher API and turned every guarded symbol into a load-time requirement. Nothing
+that ran on v0.37.0 stops running on v0.38.0 — the number now says what was always
+true.
+
+<Aside type="note">
+ The Vulkan requirement follows from the runtime: the engine renders through Dawn,
+ and Dawn's Android backend is Vulkan. There is no GLES fallback path in a packaged
+ game. It is declared in the manifest, so Play filters on it rather than letting an
+ incapable device install and fail.
+</Aside>
+
## Prerequisites
The Package dialog distinguishes **two kinds** of missing prerequisite, and they
diff --git a/docs/astro/src/content/docs/guides/scripting.mdx b/docs/astro/src/content/docs/guides/scripting.mdx
index 7977ec011..cd560b212 100644
--- a/docs/astro/src/content/docs/guides/scripting.mdx
+++ b/docs/astro/src/content/docs/guides/scripting.mdx
@@ -88,6 +88,36 @@ moment after you save. If a component never shows up, look at
`.esengine/cache/schemas.json`: absent there means it was never reached; present there
but missing in the inspector is a different problem.
+### The New Script dialog
+
+Because reachability is the rule, a hand-created `.ts` file is dead until an entry
+imports it. **Content Browser → create menu → New Script…** writes both halves.
+
+Pick what the module **is**, and the editor knows which entry to wire it into — the
+distinction is your project's architecture, not a menu convenience:
+
+| Kind | What it is | Where it lands |
+|---|---|---|
+| **Component** | a declaration the editor reads without running the game | re-exported from the declaration entry — `export * from './Health';` |
+| **System** | behavior the play realm bundles and runs | imported by the startup entry for its registration side effect — `import './Patrol';` |
+
+The dialog shows the module path it will write and the exact line the entry gains,
+before the file exists. A few things worth knowing:
+
+- **The name is asked for up front**, not left to inline rename, because a script's
+ name is not only its file name — it is the exported identifier and the string every
+ scene serializes. It must be a plain JS identifier.
+- **The entries come from the manifest** (`scripts.register` / `scripts.main`), so a
+ project that moved them is wired at its own pair, not at the conventional one.
+- **The file lands in the folder you're browsing** when that folder is inside the
+ source root, and in the source root otherwise — creating "here" under `assets/`
+ would hand back a module neither entry can reach, which is the failure this exists
+ to prevent.
+- **A component is in Add Component the moment the dialog closes** — creating
+ re-extracts the schemas rather than waiting on the file watcher. The new file is
+ revealed in the Content Browser, not opened: the editor has no code editor of its
+ own.
+
## The lifecycle
Each hook is optional; define only the ones you need.
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
index 7e0fc1ccd..adda6e10b 100644
--- a/docs/astro/src/content/docs/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -90,11 +90,28 @@ A timeline is a set of tracks evaluated together each frame:
| Sprite frames | `AnimFrames` | Swap sprite-sheet frames over time. |
| Sprite clip | `SpriteAnim` | Start a named `anim-clip` at a time. |
| Audio | `Audio` | Fire one-shot sounds at keyframes. |
-| Activation | `Activation` | Toggle entities on/off over ranges. |
+| Activation | `Activation` | Toggle entities on/off over ranges — `enabled` on a renderer, `UINode.display` on a UI node (see [below](#activation-ranges)). |
| Spine | `Spine` | Play Spine animations as clips. |
| Marker | `Marker` | Named time markers. |
| Custom event | `CustomEvent` | Named events with a payload, for your own systems. |
+### Activation ranges
+
+An activation track says *this child is on for these spans* — which is how a chest
+opens (a closed image hands over to an open one partway through, along with its glow),
+how a badge appears at the end of a flourish, how any two-state widget is animated.
+
+What it writes depends on what the target is:
+
+- **A renderer** — `Sprite`, `SpineAnimation`, `SpriteAnimator` — gets its `enabled`
+ field flipped.
+- **A UI node** gets `UINode.display`. A UI node has no `enabled`; `display` is its
+ show/hide, and the only one that **takes the subtree with it**, which is exactly
+ what an activation range means.
+
+Either way the write only happens when the state actually flips, so a track that is
+not moving does not dirty change detection every frame.
+
## Author in the Sequencer
Double-click an `.estimeline` (or open the timeline of a selected entity) to author
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index 0e45c5cd4..3b62308d3 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -323,7 +323,7 @@ const name = createTextInput({
| `onSubmit(value, entity)` | — | Fires on Enter (single-line). |
The factory is sugar over the `TextInput` **component** — insert that directly on any
-UI entity for full manual control (same fields as above, plus the live `focused` /
+UI entity for full manual control (every field above, plus the live `focused` /
`cursorPos` state):
```typescript
@@ -336,6 +336,31 @@ events.on(field, 'change', () => { /* value edited */ });
events.on(field, 'submit', () => save(world.get(field, TextInput).value)); // Enter
```
+The component carries three fields the factory doesn't take — the ones a field
+authored in a scene needs to stop looking generic:
+
+| Field | Default | Description |
+|---|---|---|
+| `font` | `0` | A font asset **this project ships** (`.ttf` / `.otf`), the same slot [`Text.font`](/docs/guides/ui-text/#custom-fonts) uses. Set, it wins over `fontFamily` — so a field on a panel drawn in the game's typeface is drawn in it too, rather than in Arial. |
+| `textAlign` | `Left` | Where the value sits in the field: `Left` / `Center` / `Right`. A single line holds the alignment **while the value fits**; past that the field scrolls to follow the caret, exactly as a left-aligned one always has. Multiline aligns per line. |
+| `renderMode` | `Auto` | Glyph pipeline for the field text — mirrors `Text.renderMode`. |
+
+**A skinned field keeps its skin.** The field draws over the entity's own
+`UIVisual`, and it only manages that visual when it is a **plain fill** —
+`backgroundColor` is the fallback for a field nobody skinned. Give the entity a
+9-sliced `UIVisual` (the frame every UI pack draws its input boxes with) and it is
+left alone, so the art survives; `backgroundColor` then does nothing.
+
+```typescript
+// A skinned field: the frame is the entity's own visual, and TextInput draws into it.
+const field = spawnUIEntity({
+ world, parent,
+ node: { width: px(240), height: px(40) },
+ visual: { visualType: UIVisualType.NineSlice, texture: frameTex, sliceBorder: { x: 12, y: 12, z: 12, w: 12 } },
+});
+world.insert(field, TextInput, { placeholder: 'Name', font: gameFont, textAlign: TextAlign.Center });
+```
+
Click (or Tab to) the field to focus it; **Escape** blurs, **Enter** fires
`submit` on single-line fields. A value longer than the box **clips to it and scrolls
horizontally** so the caret stays in view as you type.
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdx
index a2cc488a4..c2ba17587 100644
--- a/docs/astro/src/content/docs/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/guides/ui-text.mdx
@@ -84,7 +84,7 @@ Defaults below are the component defaults (what the inspector shows).
| `lineHeight` | number | `1.2` | Line spacing as a **ratio of `fontSize`** (baseline-to-baseline = `lineHeight × fontSize`). |
| `bold` / `italic` | boolean | `false` | Base font style (rich-text `<b>`/`<i>` layer on top). |
| `strokeColor` | Color | `{0,0,0,1}` | Outline color. |
-| `strokeWidth` | number | `0` | Outline width in px; `0` disables. Drawn as recolored glyph copies fanned out in 8 directions. |
+| `strokeWidth` | number | `0` | Outline width in px; `0` disables. On an SDF atlas the glyph's own edge is pushed outward, so it stays the glyph's shape at any width (see [below](#outlines)). |
| `shadowColor` | Color | `{0,0,0,1}` | Drop-shadow color. |
| `shadowOffsetX` / `shadowOffsetY` | number | `0` | Shadow offset in px. |
| `shadowBlur` | number | `0` | Softens the shadow, in px. `0` is a hard offset copy; above that the shadow spreads into a ring, so it reads as a soft mass under the glyphs rather than a second stamp of them. A blur with no offset is a halo. |
@@ -121,6 +121,29 @@ nothing.
edge the same way. This is what you want for world-space labels — damage
numbers, nameplates — where "center on the entity" is one field, not math.
+## Outlines
+
+`strokeWidth` + `strokeColor` outline the glyphs, `shadow*` drops a shadow behind
+them. Both are drawn from the same atlas as the fill, so a styled label still
+batches with an unstyled one.
+
+**An outline moves the glyph's edge — it is not a fan of copies.** SDF glyphs
+carry a distance to their own edge, so the outline is that edge pushed outward:
+the same quads draw the same shape, grown. The width you ask for is converted
+through the atlas's spread and render size, so it means the same thing at every
+`fontSize` and every camera zoom, and asking for more than the atlas can dilate
+degrades to the widest real outline instead of flooding the glyph's cell.
+
+**Bitmap** glyphs have no distance to push, so they keep the old eight-direction
+stamp of the glyph. That reads as an outline while it is a hairline and merges
+into a blob past a few pixels — force [`renderMode: Sdf`](#the-two-glyph-pipelines)
+for anything thicker than about a pixel.
+
+A `shadowBlur` above 0 stamps the shadow at the centre plus a ring of eight
+around it, with each tap's alpha inverted out of the compositing equation so the
+stack lands at the alpha you asked for. Unlike the outline it *softens* the edge
+rather than moving it, which is why the two are separate fields.
+
## Rich text
Set `richText: true` and mark up `content` with inline tags. Styles nest as a
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 7d10bad3b..9ade52e80 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -221,10 +221,15 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即
内容浏览器是你项目的资产浏览器。它的**创建**菜单就地新建资产:
-- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、新建文件夹。
+- 新建场景、新建动画、新建输入映射、新建材质、新建材质图、**新建着色器**、新建状态机、新建行为树、**新建脚本…**、新建文件夹。
- 按资产类型的上下文动作:**创建瓦片集**(从纹理)、**创建瓦片地图**(从瓦片集)、
**创建材质实例**(从材质)。
+**新建脚本…** 是唯一一个不止写一个文件的:没人 import 的模块永远不会被打包,它的组件
+也永远进不了 Add Component,所以对话框还会在项目的脚本入口里加上够到它的那一行——加到
+哪个入口,取决于你建的是组件还是系统。见
+[脚本编写](/docs/zh-cn/guides/scripting/#新建脚本对话框)。
+
**导入**可从访达/资源管理器把文件拖进来,或用"导入…"。每个资产首次出现时会得到一个 `.meta`
边车。按资产的上下文动作包括重命名、复制、复制路径、复制引用、**查找引用**、在文件管理器中
显示、删除。重命名、移动和复制各会弹出一个带**撤销**按钮的 toast——而且重命名或移动资产会
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
index 4da6fcde1..007e672a9 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
@@ -91,6 +91,7 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
| 编辑场景 | `apply_scene_ops`(批量搭建)、`create_entity`(配合 `list_entity_templates` 的创建目录)、`set_field`、`set_entity_xy`、`set_parent`、`duplicate_entity`、`undo` / `redo` |
| 项目与资产 | `create_project` / `open_project`、`open_scene`、`open_asset`(把任意资产在它自己的编辑器里打开)、`get_document`、`save_scene`、`create_scene_file`、`create_asset`、`import_assets`、`list_assets`、`get_import_settings` / `set_import_settings` |
| 预制体 | `create_prefab_from_entity`、`edit_prefab` / `exit_prefab_mode`(Prefab Mode)、`apply_prefab`、`revert_prefab`、`unpack_prefab`、`create_prefab_variant` |
+| 零代码行为 | `get_event_bindings` / `set_event_bindings`(给按钮接线)、`add_component` / `remove_component` |
| 游戏代码 | `read_project_file`、`write_project_file`、`list_project_files` |
| 运行与发布 | `toggle_play` + `get_play_state`、`export_game`(web / desktop / wechat / playable) |
@@ -141,6 +142,29 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
{ "opsPath": "assets/scenes/shop.ops.json", "label": "搭建商店" }
```
+### 给按钮接线
+
+场景不写一行游戏代码也能给按钮行为——一行[事件绑定](/docs/zh-cn/guides/events/)
+说的是*当这个事件发生,就跑那个具名动作*。`set_event_bindings` 在**一个撤销步骤**
+里整体替换某实体的绑定行(传空列表即拆线),`get_event_bindings` 读回来:
+
+```json
+{ "entity": 42, "rows": [
+ { "event": "click", "action": "panel.open",
+ "params": { "prefab": "assets/prefabs/Shop.esprefab" } }
+] }
+```
+
+`action` 是动作注册表里的任意名字——引擎内置的(`property.set`、`ui.setVisible`、
+`fsm.fire`……)或项目自己注册的——而 `target` 点名要在哪个实体上跑,从当前实体
+就近解析。
+
+<Aside type="caution">
+`EventBinding` **没有 Add Component 入口**(你加第一条线时细节面板会隐式加上它),
+所以拿这个名字调 `add_component` 建不出来——`set_event_bindings` 才是它的门。
+另外 `add_component` 现在会拒绝不认识的组件名而不是默默接受,所以打错字会当场报错。
+</Aside>
+
<Aside type="note">
有些东西在**导入设置**里,不在组件上——最容易踩的是纹理的九宫格边框:
`UIVisual` 设成 NineSlice 后,边框是从纹理元数据读的,所以没配
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
index 4b1208bfe..68ab13834 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
@@ -42,6 +42,27 @@ Android 两者都给,是因为它两者都做得到:编辑器既能直接装配
本该由之构建的那个 Gradle 工程。游戏需要接自己的 SDK、加权限或加 Activity 时,在 Android
分区的**输出**里选「Android Studio 工程」——这正是 iOS 一直以来的形状,那边由 Xcode 收尾。
+## 打出来的游戏跑在什么设备上
+
+| | Android | iOS |
+|---|---|---|
+| 最低系统 | **Android 10**(API 29) | **iOS 17.0** |
+| 声明的 target | API 33 | — |
+| CPU | `arm64-v8a`(所有真机)+ `x86_64`(模拟器) | arm64 真机 + 模拟器切片 |
+| GPU | **要求 Vulkan 1.0.3**——声明为 `required="true"`,不具备的设备在 Play 上根本看不到这个应用 | Metal |
+
+Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,那是 API 29——
+再往下没有可退的路。直到 v0.37.0 它**声明**的都还是 26,而那是个说法而非能力:
+那些构建能装到 Android 10 和 11 上,然后起不来——因为 NDK 被要求按更高的 API 构建,
+于是把每个受保护的符号都变成了加载期的硬依赖。v0.37.0 上能跑的东西在 v0.38.0 上
+一样能跑,这个数字只是终于说了实话。
+
+<Aside type="note">
+ Vulkan 的要求来自这套运行时:引擎经 Dawn 渲染,而 Dawn 的 Android 后端就是 Vulkan。
+ 打包后的游戏里没有 GLES 退路。它写在清单里,所以 Play 会据此过滤,而不是让不具备
+ 条件的设备装上再失败。
+</Aside>
+
## 前置条件
打包对话框区分**两类**缺失的前置条件,二者严重程度并不相同:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
index 84e101cea..b2d80951f 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
@@ -75,6 +75,31 @@ export * from './components/health';
如果某个组件始终不出现,去看 `.esengine/cache/schemas.json`:不在里面说明它压根没被够到;
在里面但检视器仍然空着,那是另一个问题。
+### 新建脚本对话框
+
+既然规则是可达性,那么手工新建的 `.ts` 在入口 import 它之前就是死的。
+**内容浏览器 → 创建菜单 → 新建脚本…** 会把两半都写掉。
+
+选它**是什么**,编辑器就知道该接进哪个入口——这个区分是你项目的架构,不是菜单上的便利:
+
+| 种类 | 它是什么 | 落到哪里 |
+|---|---|---|
+| **组件** | 声明,编辑器不跑游戏也要读 | 从声明入口重导出——`export * from './Health';` |
+| **系统** | 行为,由播放域打包并运行 | 由启动入口 import,取其注册副作用——`import './Patrol';` |
+
+文件还不存在时,对话框就已显示将写入的模块路径与入口将增加的那一行。几点值得知道:
+
+- **名字是先问的**,不像别的创建那样丢给内容浏览器就地重命名,因为脚本的名字不只是
+ 文件名——它同时是导出的标识符,以及每个场景序列化下去的那个字符串。必须是一个
+ 普通的 JS 标识符。
+- **入口取自项目清单**(`scripts.register` / `scripts.main`),所以挪过入口的项目接的是
+ 它自己那一对,而不是约定俗成的那一对。
+- **文件落在你正浏览的文件夹**——前提是该文件夹在源码根内,否则落到源码根。在
+ `assets/` 下遵从"就建在这儿"只会交还一个两个入口都够不到的模块,而这正是此功能
+ 要防的失败。
+- **对话框一关,组件就已在 Add Component 里**——创建会立即重新提取 schema,不等文件
+ 监视器。新文件是在内容浏览器里**定位**而非打开:本编辑器自身没有代码编辑器。
+
## 生命周期
每个钩子都是可选的;只定义你需要的那些。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
index 1d18709e8..6dd4ec52d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
@@ -86,11 +86,25 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelin
| 精灵帧 | `AnimFrames` | 随时间切换精灵表帧。 |
| 精灵剪辑 | `SpriteAnim` | 在某时刻启动一个命名 `anim-clip`。 |
| 音频 | `Audio` | 在关键帧触发一次性声音。 |
-| 激活 | `Activation` | 按区间开关实体。 |
+| 激活 | `Activation` | 按区间开关实体——渲染器写 `enabled`,UI 节点写 `UINode.display`([见下文](#激活区间))。 |
| Spine | `Spine` | 把 Spine 动画作为片段播放。 |
| 标记 | `Marker` | 命名时间标记。 |
| 自定义事件 | `CustomEvent` | 带 payload 的命名事件,供你自己的系统消费。 |
+### 激活区间
+
+激活轨道说的是*这个子对象在这些区间里是开着的*——宝箱就是这么开的(关着的图在某一刻
+交给开着的图,连同它的辉光一起),徽章就是这么在一段华彩末尾冒出来的,任何双态控件的
+动画都是这么做的。
+
+它写什么,取决于目标是什么:
+
+- **渲染器**——`Sprite`、`SpineAnimation`、`SpriteAnimator`——翻的是它的 `enabled` 字段。
+- **UI 节点**写的是 `UINode.display`。UI 节点没有 `enabled`;`display` 才是它的显示/隐藏,
+ 而且是唯一**会把整棵子树一起带走**的那个——这正是一个激活区间的含义。
+
+两种情况下都只在状态真的翻转时才写,所以一条不动的轨道不会每帧把变更检测弄脏。
+
## 在 Sequencer 里创作
双击一个 `.estimeline`(或打开选中实体的时间轴),就在 **Sequencer**(关键帧动画编辑器)里
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
index c3949483b..ed3d60630 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
@@ -309,7 +309,7 @@ const name = createTextInput({
| `onSubmit(value, entity)` | — | Enter 触发(单行)。 |
工厂是 `TextInput` **组件**之上的语法糖——直接把组件插到任意 UI 实体上可获得完全的
-手动控制(字段同上,外加实时的 `focused` / `cursorPos` 状态):
+手动控制(上表所有字段,外加实时的 `focused` / `cursorPos` 状态):
```typescript
import { spawnUIEntity, TextInput, px } from 'esengine';
@@ -321,6 +321,29 @@ events.on(field, 'change', () => { /* value edited */ });
events.on(field, 'submit', () => save(world.get(field, TextInput).value)); // Enter
```
+组件上还有三个字段是工厂不收的——恰是场景里创作的输入框想摆脱"千框一面"所需的:
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `font` | `0` | **本项目自带**的字体资源(`.ttf` / `.otf`),与 [`Text.font`](/docs/zh-cn/guides/ui-text/#自定义字体) 是同一个槽位。设了它就压过 `fontFamily`——于是画在游戏自有字体面板上的输入框也用那套字,而不是 Arial。 |
+| `textAlign` | `Left` | 值在框内的位置:`Left` / `Center` / `Right`。单行**在放得下时**保持该对齐;放不下之后改为跟随光标横向滚动,与一向左对齐时的行为一致。多行按行对齐。 |
+| `renderMode` | `Auto` | 框内文本的字形管线——与 `Text.renderMode` 对应。 |
+
+**已换皮的输入框会保住它的皮。** 输入框画在实体自己的 `UIVisual` 上,而它**只**在
+这个 visual 是**纯色填充**时才去管它——`backgroundColor` 是给没人换皮的框兜底用的。
+给实体一个九宫格 `UIVisual`(所有 UI 素材包画输入框用的那种边框),它就不会被动,
+美术得以保全;此时 `backgroundColor` 不起作用。
+
+```typescript
+// 换皮的输入框:边框是实体自己的 visual,TextInput 往里画。
+const field = spawnUIEntity({
+ world, parent,
+ node: { width: px(240), height: px(40) },
+ visual: { visualType: UIVisualType.NineSlice, texture: frameTex, sliceBorder: { x: 12, y: 12, z: 12, w: 12 } },
+});
+world.insert(field, TextInput, { placeholder: 'Name', font: gameFont, textAlign: TextAlign.Center });
+```
+
点击(或 Tab 到)输入框即聚焦;**Escape** 失焦,单行框 **Enter** 触发 `submit`。
超出盒宽的内容**裁剪到盒内并横向滚动**,输入时光标始终可见。
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 e6469a3bd..35b091479 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
@@ -78,7 +78,7 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t
| `lineHeight` | number | `1.2` | 行距,为 **`fontSize` 的比率**(基线间距 = `lineHeight × fontSize`)。 |
| `bold` / `italic` | boolean | `false` | 基础字体样式(富文本 `<b>`/`<i>` 在其上叠加)。 |
| `strokeColor` | Color | `{0,0,0,1}` | 描边颜色。 |
-| `strokeWidth` | number | `0` | 描边宽度(px);`0` 关闭。以 8 方向扇形展开的换色字形副本绘制。 |
+| `strokeWidth` | number | `0` | 描边宽度(px);`0` 关闭。SDF 图集上是把字形自己的边缘向外推,所以任意宽度下描出来的仍是这个字的形状([见下文](#描边))。 |
| `shadowColor` | Color | `{0,0,0,1}` | 投影颜色。 |
| `shadowOffsetX` / `shadowOffsetY` | number | `0` | 投影偏移(px)。 |
| `shadowBlur` | number | `0` | 投影柔度(px)。`0` 是硬边偏移副本;大于 0 时投影摊成一圈,读起来是字下面一团柔和的暗,而不是又盖了一遍字。只给柔度不给偏移就是一圈光晕。 |
@@ -110,6 +110,24 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t
顶/中/底缘。世界空间标签——伤害数字、名牌——"以实体为中心"就是一个字段,
不用算。
+## 描边
+
+`strokeWidth` + `strokeColor` 给字形描边,`shadow*` 在其后投影。两者都从填充所用的
+同一张图集绘制,所以带样式的标签仍与不带样式的合批。
+
+**描边是把字形的边缘推出去,不是围一圈副本。** SDF 字形自带到自身边缘的距离,
+描边就是把这条边缘向外推:同样的四边形画出同一个形状,只是长大了。你给的宽度会
+经图集的 spread 与渲染尺寸换算,因此在任何 `fontSize`、任何相机缩放下含义一致;
+要得比图集能膨胀的更宽时,退化为最宽的那圈真实描边,而不是糊满字形的格子。
+
+**Bitmap** 字形没有距离可推,仍走旧的 8 方向字形拓印。那在发丝宽时读起来像描边,
+超过几个像素就糊成一团——要更粗的描边,请强制
+[`renderMode: Sdf`](#双字形管线)。
+
+`shadowBlur` 大于 0 时,投影在中心加外围一圈共九次拓印,每次的 alpha 从合成方程里
+反解出来,使叠起来正好是你要的 alpha。与描边不同,它是把边缘**变柔**而不是挪动,
+这也是两者分成两个字段的原因。
+
## 富文本
设 `richText: true`,在 `content` 里写内联标签。样式按栈嵌套;闭合标签弹出最内层