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: add UI Controllers & Gears guide (bilingual)
yhh52de3f56fb4c
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex f1f4df7b3..2b2e55e13 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -90,6 +90,7 @@ export default defineConfig({{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },{ label: 'UI Components', translations: { 'zh-CN': 'UI 控件' }, slug: 'guides/ui-components' },+ { label: 'UI Controllers', translations: { 'zh-CN': 'UI 控制器' }, slug: 'guides/ui-controllers' },{ label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },{ label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'guides/postprocess' },{ label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'guides/material' },diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdxindex d303c1b3d..2ae94aa49 100644--- a/docs/astro/src/content/docs/guides/ui-components.mdx+++ b/docs/astro/src/content/docs/guides/ui-components.mdx@@ -20,6 +20,13 @@ layout), and visual overrides.tree with the UI components on it, so you can compose your own the same way.</Aside>+<Aside type="note">+ For **shared** state across many elements — tabs, radio groups, show/hide panels, or+ custom button states driven from data — reach for+ [UI Controllers](/docs/guides/ui-controllers/): a named "page" state plus declarative+ per-page field bindings, authorable in the editor.+</Aside>+## Button`createButton(opts)` spawns a clickable entity (with an optional child label) thatdiff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/guides/ui-controllers.mdxnew file mode 100644index 000000000..bd0f4f3a4--- /dev/null+++ b/docs/astro/src/content/docs/guides/ui-controllers.mdx@@ -0,0 +1,183 @@+---+title: UI Controllers & Gears+description: Shared, named "page" state (UIController) plus declarative per-page field bindings (UIGear) — with editor authoring, record mode, and data-driven page switching.+---++import { Aside } from '@astrojs/starlight/components';++A **controller** is a named enum of *pages* scoped to a UI root — `{ up, over, down }`,+`{ home, shop, about }`, `{ closed, open }`. A **gear** binds one component field to a+value *per page*, so when the controller switches page, every geared element reflows —+color, position, visibility, text, or any reflected field, snapping or tweening.++One controller drives many elements, and the whole thing is plain ECS data (two+components, `UIController` and `UIGear`) that travels with a [prefab](/docs/guides/prefab/)+and serializes into a scene. It is the shared, multi-page generalization of the+per-widget state a [button](/docs/guides/ui-components/#button) uses — one mechanism for+tabs, radio groups, button states, and show/hide panels.++## Controllers++Put a `UIController` on a UI root (a `Canvas` or any node). It holds one or more named+controllers, each with a page list and the current page:++```typescript+import { UIController, controllerState, setControllerPage, getControllerPage } from 'esengine';++world.insert(root, UIController, {+ controllers: [controllerState('tab', ['home', 'shop', 'about'], 'home')],+});++setControllerPage(world, anyDescendant, 'tab', 'shop'); // switch page+getControllerPage(world, anyDescendant, 'tab'); // → 'shop'+```++`controllerState(name, pages, current?)` builds one controller (current defaults to the+first page). `setControllerPage` / `getControllerPage` resolve the nearest controller of+that name walking **self → ancestors**, so a gear on a leaf finds the controller on the+root. `setControllerPage` is a no-op on an unknown controller, an unknown page, or the+current page (it guards typos rather than failing).++| `ControllerState` field | Description |+|---|---|+| `name` | Controller name, referenced by gears (e.g. `"tab"`, `"$interaction"`). |+| `pages` | Ordered page names — the enum's members. |+| `current` | The currently selected page. |++## Gears++Put a `UIGear` on any element under the controller. Each binding says *"while controller+C is on page P, this field holds value V"*:++```typescript+import { UIGear, gearBinding, EasingType } from 'esengine';++world.insert(card, UIGear, {+ bindings: [+ // The card's colour follows the 'tab' page, easing over 0.18s.+ gearBinding('tab', 'UIVisual', 'color', {+ home: { r: 0.16, g: 0.18, b: 0.26, a: 1 },+ shop: { r: 0.21, g: 0.16, b: 0.26, a: 1 },+ about: { r: 0.15, g: 0.23, b: 0.21, a: 1 },+ }, { easing: EasingType.EaseOutCubic, duration: 0.18 }),++ // Its label text follows the same page (strings snap — no interpolation).+ gearBinding('tab', 'Text', 'content', {+ home: 'Welcome home', shop: 'Buy stuff', about: 'About us',+ }),+ ],+});+```++`gearBinding(controller, component, property, pages, tween?)` addresses a field the same+way a [Timeline](/docs/guides/timeline/) property track does — a component name plus a+dot-path `property` (`"color"`, `"color.a"`, `"scale.x"`). `pages` is a **sparse** map+keyed by page name: a page with no entry leaves the field untouched.++| `GearBinding` field | Description |+|---|---|+| `controller` | Which controller drives this (resolved self → ancestors). |+| `component` | Target component name — `"UIVisual"`, `"Transform"`, `"Text"`, `"UINode"`. |+| `property` | Dot-path within the component (`"color"`, `"color.a"`, `"scale"`). |+| `pages` | `page → value` map; a page absent here leaves the field alone. |+| `tween?` | `{ easing, duration }` to interpolate on page change; omit for an instant snap. |++**Values** — numbers, colours (`{r,g,b,a}`), and vectors (`{x,y,z}`) interpolate when the+binding has a `tween`; strings and booleans always snap. A geared element is owned by the+controller for that field: on each page change the gear applies the page's value.++<Aside type="note">+ Gears apply in **edit mode too** — the system that applies them isn't gated to play. So+ in the editor, switching a controller's page previews it live in the viewport, with no+ Play needed.+</Aside>++## A button, without bespoke state++The built-in controller name **`$interaction`** is driven by pointer state+(`normal` / `hover` / `pressed` / `disabled`). Give an element an `$interaction`+controller + an `Interactable` + a gear, and it reproduces button states with no+`StateMachine` — the unified replacement for the old state components:++```typescript+import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';++world.insert(btn, UIController, { controllers: [interactionController()] });+world.insert(btn, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });+world.insert(btn, UIGear, {+ bindings: [gearBinding('$interaction', 'UIVisual', 'color', {+ normal: { r: 0.30, g: 0.33, b: 0.42, a: 1 },+ hover: { r: 0.39, g: 0.43, b: 0.55, a: 1 },+ pressed: { r: 0.22, g: 0.24, b: 0.32, a: 1 },+ disabled: { r: 0.20, g: 0.20, b: 0.24, a: 0.6 },+ }, { easing: EasingType.EaseOutCubic, duration: 0.1 })],+});+```++`interactionController(pages?)` defaults to the four canonical pages. Because a gear can+drive *any* field, the same button can also gear its scale, a child icon's tint, or a+label — all four states, one mechanism.++## Authoring in the editor++Everything above can be authored visually — no code. Select a UI root and the+**Controllers** panel (revealed in UI mode) lists its controllers:++- **Add a controller**, then add/remove **pages**; the page selector switches `current`+ and the viewport reflows live.+- Click a controller to make it **active**. In the [Details](/docs/guides/editor/) panel,+ every field then shows a small **gear dot** — click it to bind that field to the active+ controller (seeding the current page with the field's value).+- Turn on **Record**: now editing a geared field writes the value into the controller's+ **current page**. Switch page, edit, switch page, edit — each page captures its own+ values. This is the fast path — "pick a page, change things, it's recorded".++Controllers and gears are components, so they save into the scene / prefab like anything+else, and instance with it.++## Data-driven pages++Two bridges switch pages from *data* or *logic*, each reusing an existing system.++**From a signal** — `bindControllerPage` drives a controller's page from a+[reactive signal](/docs/guides/ui/), the declarative path to a data-driven tab bar:++```typescript+import { signal, bindControllerPage } from 'esengine';++const activeTab = signal('home');+bindControllerPage(world, root, 'tab', activeTab); // the controller follows the signal++activeTab.set('shop'); // page switches, every geared element reflows+```++**From a state machine** — the `ui.setPage` action lets a data-driven+[FSM / behavior tree](/docs/guides/ai/) (`.esfsm` / `.esbt`) switch a page with no code.+Its argument is `"controller:page"`:++```json+{ "onEnter": { "name": "ui.setPage", "arg": "hud:alert" } }+```++This is the same layering as the built-in `timeline.play` glue: logic (`.esfsm`) →+controller state → gear presentation.++## Best practices++- **Controller on the root, gears on the leaves.** Resolution walks up the tree, so a+ controller on the `Canvas` drives gears anywhere under it.+- **One controller, many gears.** A tab controller drives the tab highlights, the content+ panel, *and* its label — set the page once, everything follows.+- **Snap vs tween.** Add a `tween` for colour/position/scale transitions; leave it off for+ text and visibility (which snap anyway).+- **Radio buttons via one controller** — give each tab button a gear that's the accent+ colour on its own page and muted on the others.+- **Switch pages from data**, not scattered mutations — `bindControllerPage(signal)` or+ `ui.setPage` keep the "what page am I on" decision in one place.++## See also++- [UI](/docs/guides/ui/) — the flexbox component model gears drive.+- [UI Components](/docs/guides/ui-components/) — the widget factories.+- [Timeline](/docs/guides/timeline/) — keyframed transitions; gears use the same field addressing.+- [Gameplay AI](/docs/guides/ai/) — the `.esfsm` / `.esbt` that can call `ui.setPage`.diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdxindex b20364d7c..139965217 100644--- a/docs/astro/src/content/docs/guides/ui.mdx+++ b/docs/astro/src/content/docs/guides/ui.mdx@@ -197,6 +197,8 @@ parent chain — read the `UIEvents` resource (the UI event bus).## See also+- [UI Components](/docs/guides/ui-components/) — the built-in widget factories.+- [UI Controllers](/docs/guides/ui-controllers/) — shared "page" state + declarative per-page field bindings (tabs, button states, show/hide).- [Input](/docs/guides/input/) — raw keyboard/mouse/touch below the UI layer.- [Localization](/docs/guides/localization/) — bind `Text.content` to translated keys.- [Animation](/docs/guides/animation/) — tween UI color/position for juice.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.mdxindex 4392bacba..097962c08 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@@ -18,6 +18,12 @@ import { Aside } from '@astrojs/starlight/components';自己的控件。</Aside>+<Aside type="note">+ 需要跨多个元素的 **共享** 状态——页签、单选组、显隐面板、或从数据驱动的自定义按钮状态——+ 请用 [UI 控制器](/docs/zh-cn/guides/ui-controllers/):一个具名的"页"状态,加上声明式的每页字段+ 绑定,可在编辑器里授权。+</Aside>+## Button 按钮`createButton(opts)` 生成一个可点击实体(带可选子标签),在各视觉状态间过渡。返回按钮**实体**。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.mdxnew file mode 100644index 000000000..c2679c1ba--- /dev/null+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx@@ -0,0 +1,166 @@+---+title: UI 控制器与属性绑定+description: 共享的具名"页"状态(UIController)+ 声明式的每页字段绑定(UIGear)——含编辑器授权、录制模式与数据驱动的翻页。+---++import { Aside } from '@astrojs/starlight/components';++**控制器(controller)** 是挂在 UI 根上的一个具名"页"枚举——`{ up, over, down }`、+`{ home, shop, about }`、`{ closed, open }`。**属性绑定(gear)** 把某个组件字段绑定到+*每一页* 的值:控制器一切换页,所有被绑定的元素就随之重排——颜色、位置、可见性、文本,+或任何可反射的字段,可瞬切也可补间。++一个控制器驱动多个元素,而整套东西就是普通的 ECS 数据(两个组件 `UIController` 和+`UIGear`),会随 [预制体](/docs/guides/prefab/) 一起走、序列化进场景。它是+[按钮](/docs/guides/ui-components/#button) 那种"单控件状态"的共享化、多页化推广——+页签、单选组、按钮状态、面板显隐,统一用一套机制。++## 控制器++把 `UIController` 挂在 UI 根上(一个 `Canvas` 或任意节点)。它持有一个或多个具名控制器,+每个有页列表和当前页:++```typescript+import { UIController, controllerState, setControllerPage, getControllerPage } from 'esengine';++world.insert(root, UIController, {+ controllers: [controllerState('tab', ['home', 'shop', 'about'], 'home')],+});++setControllerPage(world, anyDescendant, 'tab', 'shop'); // 切换页+getControllerPage(world, anyDescendant, 'tab'); // → 'shop'+```++`controllerState(name, pages, current?)` 构造一个控制器(current 默认取第一页)。+`setControllerPage` / `getControllerPage` 会沿 **自身 → 祖先** 找到最近的同名控制器,+所以叶子上的绑定能找到根上的控制器。`setControllerPage` 对未知控制器、未知页、或已是当前页+都是空操作(防拼写错,而不是报错)。++| `ControllerState` 字段 | 说明 |+|---|---|+| `name` | 控制器名,供绑定引用(如 `"tab"`、`"$interaction"`)。 |+| `pages` | 有序的页名——枚举的成员。 |+| `current` | 当前选中的页。 |++## 属性绑定++把 `UIGear` 挂在控制器下的任意元素上。每条绑定表达 *"当控制器 C 处于页 P 时,该字段取值 V"*:++```typescript+import { UIGear, gearBinding, EasingType } from 'esengine';++world.insert(card, UIGear, {+ bindings: [+ // 卡片颜色跟随 'tab' 页,0.18 秒缓动。+ gearBinding('tab', 'UIVisual', 'color', {+ home: { r: 0.16, g: 0.18, b: 0.26, a: 1 },+ shop: { r: 0.21, g: 0.16, b: 0.26, a: 1 },+ about: { r: 0.15, g: 0.23, b: 0.21, a: 1 },+ }, { easing: EasingType.EaseOutCubic, duration: 0.18 }),++ // 标签文本跟随同一页(字符串直接瞬切,不插值)。+ gearBinding('tab', 'Text', 'content', {+ home: 'Welcome home', shop: 'Buy stuff', about: 'About us',+ }),+ ],+});+```++`gearBinding(controller, component, property, pages, tween?)` 寻址字段的方式和+[时间轴](/docs/guides/timeline/) 属性轨道一致——组件名 + 点路径 `property`+(`"color"`、`"color.a"`、`"scale.x"`)。`pages` 是按页名索引的 **稀疏** 映射:某页没有条目就+不动这个字段。++| `GearBinding` 字段 | 说明 |+|---|---|+| `controller` | 由哪个控制器驱动(沿自身 → 祖先解析)。 |+| `component` | 目标组件名——`"UIVisual"`、`"Transform"`、`"Text"`、`"UINode"`。 |+| `property` | 组件内的点路径(`"color"`、`"color.a"`、`"scale"`)。 |+| `pages` | `页 → 值` 映射;此处缺失的页不动该字段。 |+| `tween?` | `{ easing, duration }` 在切页时插值;省略则瞬切。 |++**取值**——数字、颜色(`{r,g,b,a}`)、向量(`{x,y,z}`)在有 `tween` 时插值;字符串和布尔总是瞬切。+被绑定的元素在该字段上归控制器所有:每次切页,绑定就把该页的值写上去。++<Aside type="note">+ 绑定在 **编辑期也生效**——应用它的系统不受 play 门控。所以在编辑器里切换控制器的页,+ 视口立即预览,无需运行。+</Aside>++## 无需专用状态的按钮++内建控制器名 **`$interaction`** 由指针状态驱动+(`normal` / `hover` / `pressed` / `disabled`)。给元素配一个 `$interaction` 控制器 ++一个 `Interactable` + 一条绑定,它就重现出按钮状态,不需要 `StateMachine`——这是对旧状态组件的+统一替代:++```typescript+import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';++world.insert(btn, UIController, { controllers: [interactionController()] });+world.insert(btn, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });+world.insert(btn, UIGear, {+ bindings: [gearBinding('$interaction', 'UIVisual', 'color', {+ normal: { r: 0.30, g: 0.33, b: 0.42, a: 1 },+ hover: { r: 0.39, g: 0.43, b: 0.55, a: 1 },+ pressed: { r: 0.22, g: 0.24, b: 0.32, a: 1 },+ disabled: { r: 0.20, g: 0.20, b: 0.24, a: 0.6 },+ }, { easing: EasingType.EaseOutCubic, duration: 0.1 })],+});+```++`interactionController(pages?)` 默认给出这四个规范页。因为绑定能驱动 *任意* 字段,同一个按钮+还能把缩放、子图标的着色、或标签一并绑上——四态,一套机制。++## 在编辑器里授权++上面的一切都能可视化授权,无需写码。选中一个 UI 根,**控制器** 面板(在 UI 模式下弹出)+列出它的控制器:++- **添加控制器**,再增删 **页**;页选择器切换 `current`,视口实时重排。+- 点击某个控制器使其 **活动**。在 [细节](/docs/guides/editor/) 面板里,每个字段旁便出现一个小的+ **gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。+- 打开 **录制**:此时编辑一个被绑定的字段,值就写入控制器的 **当前页**。切页、改、切页、改——+ 每页各自记录自己的值。这是快捷路径——"选一页,随便改,自动录制"。++控制器和绑定都是组件,所以它们像别的东西一样存进场景 / 预制体,并随之实例化。++## 数据驱动的翻页++两座桥从 *数据* 或 *逻辑* 切页,各自复用一套已有系统。++**从信号** —— `bindControllerPage` 用一个 [响应式信号](/docs/guides/ui/) 驱动控制器的页,+这是数据驱动页签的声明式路径:++```typescript+import { signal, bindControllerPage } from 'esengine';++const activeTab = signal('home');+bindControllerPage(world, root, 'tab', activeTab); // 控制器跟随信号++activeTab.set('shop'); // 翻页,所有被绑定的元素重排+```++**从状态机** —— `ui.setPage` 动作让数据驱动的+[FSM / 行为树](/docs/guides/ai/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:++```json+{ "onEnter": { "name": "ui.setPage", "arg": "hud:alert" } }+```++这与内建的 `timeline.play` 胶水是同一套分层:逻辑(`.esfsm`)→ 控制器状态 → 绑定表现。++## 最佳实践++- **控制器放根上,绑定放叶子上。** 解析沿树上行,所以 `Canvas` 上的一个控制器能驱动其下任意处的绑定。+- **一个控制器,多条绑定。** 一个页签控制器同时驱动页签高亮、内容面板、*以及* 它的标签——切一次页,全部跟随。+- **瞬切还是补间。** 颜色/位置/缩放过渡加 `tween`;文本和可见性不加(本就瞬切)。+- **用一个控制器做单选按钮**——给每个页签按钮一条绑定:在自己那页是强调色,其余页是暗色。+- **从数据切页**,别到处散着改——`bindControllerPage(signal)` 或 `ui.setPage` 把"我现在在哪一页"这个决定收在一处。++## 参见++- [UI](/docs/guides/ui/) —— 绑定所驱动的 flexbox 组件模型。+- [UI 控件](/docs/guides/ui-components/) —— 控件工厂。+- [时间轴](/docs/guides/timeline/) —— 关键帧过渡;绑定用的是同一套字段寻址。+- [游戏 AI](/docs/guides/ai/) —— 能调用 `ui.setPage` 的 `.esfsm` / `.esbt`。diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdxindex 1a26c8ab1..bc9d93b09 100644--- a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx@@ -187,6 +187,8 @@ const onTiles = defineSystem([Query(Interactable, UIInteraction)], (q) => {## 参见+- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 内建控件工厂。+- [UI 控制器](/docs/zh-cn/guides/ui-controllers/) —— 共享的"页"状态 + 声明式的每页字段绑定(页签、按钮状态、显隐)。- [输入](/docs/zh-cn/guides/input/) —— UI 层之下的原始键鼠/触摸。- [本地化](/docs/zh-cn/guides/localization/) —— 把 `Text.content` 绑到翻译 key。- [动画](/docs/zh-cn/guides/animation/) —— 补间 UI 颜色/位置增加手感。