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(events): the Event Binding guide, in both languages

yhh8e64f8020974
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 27d0ee1e4..84620795a 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -75,6 +75,7 @@ export default defineConfig({
translations: { 'zh-CN': '玩法' },
items: [
{ label: 'Scripting', translations: { 'zh-CN': '脚本' }, slug: 'guides/scripting' },
+ { label: 'Event Binding', translations: { 'zh-CN': '事件绑定' }, slug: 'guides/events' },
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
diff --git a/docs/astro/src/assets/guides/en/events-fsm.png b/docs/astro/src/assets/guides/en/events-fsm.png
new file mode 100644
index 000000000..2286932cf
Binary files /dev/null and b/docs/astro/src/assets/guides/en/events-fsm.png differ
diff --git a/docs/astro/src/assets/guides/en/events-palette.png b/docs/astro/src/assets/guides/en/events-palette.png
new file mode 100644
index 000000000..fa3280420
Binary files /dev/null and b/docs/astro/src/assets/guides/en/events-palette.png differ
diff --git a/docs/astro/src/assets/guides/en/events-section.png b/docs/astro/src/assets/guides/en/events-section.png
new file mode 100644
index 000000000..5fecef779
Binary files /dev/null and b/docs/astro/src/assets/guides/en/events-section.png differ
diff --git a/docs/astro/src/assets/guides/zh/events-fsm.png b/docs/astro/src/assets/guides/zh/events-fsm.png
new file mode 100644
index 000000000..b4c54bd76
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-fsm.png differ
diff --git a/docs/astro/src/assets/guides/zh/events-palette.png b/docs/astro/src/assets/guides/zh/events-palette.png
new file mode 100644
index 000000000..9c90c62f8
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-palette.png differ
diff --git a/docs/astro/src/assets/guides/zh/events-section.png b/docs/astro/src/assets/guides/zh/events-section.png
new file mode 100644
index 000000000..6ea83f418
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-section.png differ
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
index f640434c6..5e06c9f66 100644
--- a/docs/astro/src/content/docs/guides/ai.mdx
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -588,3 +588,5 @@ code is the shared leaves above plus the one-time grid.
- [Scripting](/docs/guides/scripting/) — behaviors are declarative systems; leaves are plain functions.
- [Animation](/docs/guides/animation/) — drive sprite clips from a state machine.
- [Scenes](/docs/guides/scene/) — `.esfsm` / `.esbt` assets load and serialize with the scene.
+- [Event Binding](/docs/guides/events/) — a click or a trigger can `fsm.fire` into a state
+ machine; actions and conditions come from this same registry.
diff --git a/docs/astro/src/content/docs/guides/events.mdx b/docs/astro/src/content/docs/guides/events.mdx
new file mode 100644
index 000000000..374a5e6fb
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/events.mdx
@@ -0,0 +1,194 @@
+---
+title: Event Binding
+description: Wire an entity event to a named action as authored data — a button click, a trigger area, a state machine hand-off — with no game code.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+A **wire** says: *when this entity sees this event, run this action on that entity.* It is
+a row of data on the emitting entity — no callback, no script file — so laying out a button
+and making it *do* something happen in the same place.
+
+```
+click ─▶ ui.setPage(tabs, settings) on "This entity"
+click ─▶ ui.setPage(badge, on) on "Card"
+```
+
+Wires are deliberately **not** a visual programming language. A row has no branches and no
+expressions; when something genuinely needs logic, the row names an action that hands off to
+[a state machine](/docs/guides/ai/) — the editor Estella already has for graphs.
+
+## A wire in the inspector
+
+![The Events section of the Details inspector](../../../assets/guides/en/events-section.png)
+
+*Two wires on a button: both fire on `click`, one switches a controller on the button's own
+ancestor chain, the other targets the `Card` entity by name.*
+
+Select any entity that can emit — a UI node, an `Interactable`, a collider — and the
+**Events** section lists its wires. Each row reads left to right:
+
+| Part | Meaning |
+|---|---|
+| ☑ | Row enabled. An unchecked row stays in the data and never fires. |
+| Event | The event type to listen for (`click`, `change`, `trigger_enter`, …). |
+| ↳ Target | Which entity the action runs on. *This entity* by default, or another **by name**. |
+| Action | A registered action name — the same palette the FSM and behaviour-tree editors use. |
+| Parameters | Whatever that action declares. An action with none gets a single free-text argument. |
+| ⚙ | Reveals **Condition** (a registered condition that must pass) and **Once**. |
+
+## The data
+
+A wire is the `EventBinding` component, so it serializes into scenes and travels with
+[prefabs](/docs/guides/prefab/) like any other component — no new asset type:
+
+```typescript
+import { EventBinding, UIEventType } from 'esengine';
+
+world.insert(button, EventBinding, {
+ rows: [
+ { event: UIEventType.Click, action: 'ui.setPage', params: { controller: 'tabs', page: 'settings' } },
+ { event: 'trigger_enter', target: 'Door', action: 'ui.setVisible', params: { visible: true }, once: true },
+ ],
+});
+```
+
+| `EventBindingRow` | Description |
+|---|---|
+| `event` | Event type to listen for. Any string — the built-ins are only the well-known set. |
+| `target` | Name of the entity the action runs on. Omitted = the entity carrying the row. |
+| `action` | Registered action name. |
+| `params` | The action's declared parameters by name. |
+| `arg` | The same input in canonical string form (`"tabs:settings"`). Either form runs. |
+| `guard` | Registered condition that must pass for the row to run. |
+| `once` | Run at most once per play session. |
+| `enabled` | `false` keeps the row inert without deleting it. |
+
+Wires fire in play mode only — the editor never runs your actions while you author.
+
+### Targets resolve by name, nearest first
+
+`target` is an entity **name**, searched outward: the row's own entity, then its subtree,
+then each ancestor's subtree, and finally the whole scene. Nearest wins, which is what keeps
+two instances of the same prefab from wiring into each other — a `Close` button inside
+dialog A finds dialog A's `Panel`, never dialog B's.
+
+A name that matches nothing is reported in the inspector (the target reads red) and warns at
+runtime instead of failing silently.
+
+## Actions
+
+An action is a named function in the shared registry — the same one `.esfsm` state hooks and
+`.esbt` leaves resolve against. Register once, and the name shows up in all three palettes.
+
+![The action palette, grouped by namespace](../../../assets/guides/en/events-palette.png)
+
+*The palette groups by `namespace.`, and the engine's own actions carry a one-line
+description.*
+
+These ship with the engine:
+
+| Action | What it does |
+|---|---|
+| `ui.setPage` | Switch a [UI controller](/docs/guides/ui-controllers/) to a page. |
+| `ui.setVisible` | Show/hide a UI subtree (`UINode.display`). |
+| `property.set` | Write any component field, addressed as `Component.dot.path`. |
+| `fsm.fire` | Fire a trigger on the target's state machine. |
+| `blackboard.set` | Set a blackboard value. |
+| `timeline.play` · `timeline.pause` | Drive a [timeline](/docs/guides/timeline/) on the target. |
+| `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | Drive a sprite flipbook. |
+
+### Your own actions
+
+One registration makes a name authorable everywhere:
+
+```typescript
+import { registerAction } from 'esengine';
+
+registerAction('game.award', {
+ params: [
+ { name: 'kind', type: 'enum', options: [{ label: 'Coin', value: 'coin' }, { label: 'Star', value: 'star' }] },
+ { name: 'amount', type: 'number' },
+ ],
+ run: (ctx, bb, arg, params) => {
+ grantReward(ctx.entity, params!.kind as string, params!.amount as number);
+ },
+});
+```
+
+Declaring `params` is what turns the editor's text box into a dropdown and a number field.
+`ctx` is the same context an FSM action gets — `entity`, `world`, `commands`, plus the
+blackboard.
+
+<Aside type="tip" title="Where to register">
+The editor never executes your gameplay code, so it learns your action names from the
+project's **declaration entry** (`src/components.ts` by default — the same module it reads
+components from). Register there and the names appear in every palette; register elsewhere
+and they still work at runtime, you just have to type them.
+</Aside>
+
+## Which events fire
+
+Widgets emit the standard set (`UIEventType`), and events **bubble**, so a row on a panel
+hears its buttons:
+
+`click` · `press` · `release` · `hover_enter` · `hover_exit` · `focus` · `blur` ·
+`change` · `submit` · `drag_start` · `drag_move` · `drag_end` · `scroll` · `select` · `deselect`
+
+[Physics](/docs/guides/physics/) contacts reach the same channel (`PhysicsEventType`), so a
+[trigger area](/docs/guides/markers/) is wired exactly like a button — both participants get
+the event, each told about the other:
+
+`collision_enter` · `collision_exit` · `collision_hit` · `trigger_enter` · `trigger_exit`
+
+The vocabulary is open: emit your own name from anywhere and a row can listen for it.
+
+```typescript
+import { EntityEvents } from 'esengine';
+
+app.getResource(EntityEvents).emit(chest, 'looted', { gold: 12 });
+```
+
+## When a wire needs logic
+
+A row runs one action; it has no "if" and no sequence. That is a deliberate ceiling, and
+`fsm.fire` is the way through it — the click fires a trigger, and the entity's
+[state machine](/docs/guides/ai/) decides what it means:
+
+```
+click ─▶ fsm.fire(start) on "Hint" → Idle ──start──▶ Running
+ onEnter: property.set(…)
+```
+
+![A state hook's declared parameters in the state machine editor](../../../assets/guides/en/events-fsm.png)
+
+*The same parameter controls, in the state-machine editor: `property.set` declares `path`
+and `value`, so the hook shows two fields instead of one opaque string.*
+
+An action declares its parameters once and every authoring surface shows them — an event
+row, an FSM state hook, a behaviour-tree leaf.
+
+## Two ways to write the same input
+
+Every action keeps a canonical string form. `{ controller: 'tabs', page: 'settings' }` and
+`"tabs:settings"` are projections of each other, and the registry converts between them, so:
+
+- data authored before an action declared its parameters keeps running, unchanged;
+- an action that only reads `arg` still receives it when a row is authored as parameters;
+- the editor can show real controls for a row that stores a plain string.
+
+You never choose: the inspector writes parameters, hand-written data may use either.
+
+<Aside type="caution" title="Not yet: asset and entity parameters">
+A parameter cannot be an asset reference or an entity handle. The cook's discovery pass and
+the scene's entity remapper do not look inside a row's parameters, so such a parameter would
+ship a build with a missing asset — a control that silently breaks the game is worse than no
+control. Address other entities by `target` name, and reference assets through a component
+the cook can see.
+</Aside>
+
+## Example
+
+`examples/ui-events` is the whole feature in one project — two tab buttons, a cross-entity
+badge, and a *Start run* button that hands off to a state machine. Its `src/main.ts` is
+empty; every behaviour in it is authored data.
diff --git a/docs/astro/src/content/docs/guides/markers.mdx b/docs/astro/src/content/docs/guides/markers.mdx
index 1d906c888..19414e534 100644
--- a/docs/astro/src/content/docs/guides/markers.mdx
+++ b/docs/astro/src/content/docs/guides/markers.mdx
@@ -169,3 +169,5 @@ if you need a shape's exact vertices.
- [Physics](/docs/guides/physics/) — sensors, collision filtering, and the
`PhysicsEvents` resource behind Trigger Areas.
- [Scenes](/docs/guides/scene/) — Markers and Trigger Areas serialize with the scene.
+- [Event Binding](/docs/guides/events/) — run an action when something enters a Trigger
+ Area, authored on the area itself with no code.
diff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/guides/ui-controllers.mdx
index f5d7a9da7..cce73f487 100644
--- a/docs/astro/src/content/docs/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/guides/ui-controllers.mdx
@@ -164,6 +164,13 @@ bindControllerPage(world, root, 'tab', activeTab); // the controller follows th
activeTab.set('shop'); // page switches, every geared element reflows
```
+**From a button, with no code** — an [event wire](/docs/guides/events/) on the button
+runs `ui.setPage` when it is clicked, targeting the entity that owns the controller:
+
+```json
+{ "event": "click", "action": "ui.setPage", "params": { "controller": "tab", "page": "shop" } }
+```
+
**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"`:
@@ -194,3 +201,4 @@ controller state → gear presentation.
- [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`.
+- [Event Binding](/docs/guides/events/) — wire a click straight to `ui.setPage`, no code.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
index 626fc7d4e..486732c14 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -544,3 +544,4 @@ export const setupNavGrid = defineSystem([Res(Nav)], (nav) => {
- [脚本](/docs/zh-cn/guides/scripting/) —— 行为是声明式系统;叶子就是普通函数。
- [动画](/docs/zh-cn/guides/animation/) —— 用状态机驱动精灵动画。
- [场景](/docs/zh-cn/guides/scene/) —— `.esfsm` / `.esbt` 资产随场景加载与序列化。
+- [事件绑定](/docs/zh-cn/guides/events/) —— 点击或触发可以 `fsm.fire` 进状态机;动作与条件出自同一个注册表。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/events.mdx b/docs/astro/src/content/docs/zh-cn/guides/events.mdx
new file mode 100644
index 000000000..b2bb88368
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/events.mdx
@@ -0,0 +1,182 @@
+---
+title: 事件绑定
+description: 把实体事件接到具名动作上,全部是授权数据——按钮点击、触发区、交给状态机——不写游戏代码。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+一根**连线(wire)**说的是:*当这个实体收到这个事件时,在那个实体上执行这个动作。* 它就是
+挂在发出事件那个实体上的一行数据——没有回调,没有脚本文件——所以摆好按钮和让它*做事*
+在同一个地方完成。
+
+```
+click ─▶ ui.setPage(tabs, settings) 目标「自身」
+click ─▶ ui.setPage(badge, on) 目标「Card」
+```
+
+连线**刻意不是**可视化编程语言。一行里没有分支、没有表达式;真的需要逻辑时,这行会指向一个
+把控制权交给[状态机](/docs/zh-cn/guides/ai/)的动作——Estella 已经有图编辑器了。
+
+## 检视器里的一根线
+
+![细节检视器中的「事件」区域](../../../../assets/guides/zh/events-section.png)
+
+*按钮上的两根线:都在 `click` 时触发,一根切换按钮自身祖先链上的控制器,另一根按名字指向
+`Card` 实体。*
+
+选中任意能发出事件的实体——UI 节点、`Interactable`、碰撞体——**事件**区域就列出它的连线。
+每一行从左到右是:
+
+| 部分 | 含义 |
+|---|---|
+| ☑ | 该行是否启用。不勾选则保留在数据里但永不触发。 |
+| 事件 | 要监听的事件类型(`click`、`change`、`trigger_enter`……)。 |
+| ↳ 目标 | 动作在哪个实体上执行。默认「自身」,也可**按名字**指向别的实体。 |
+| 动作 | 已注册的动作名——与 FSM、行为树编辑器**同一个**候选列表。 |
+| 参数 | 该动作声明了什么就显示什么。没声明参数的动作显示一个自由文本参数框。 |
+| ⚙ | 展开**条件**(必须通过的具名条件)与**仅一次**。 |
+
+## 数据本身
+
+一根线就是 `EventBinding` 组件,因此它会序列化进场景、随[预制体](/docs/zh-cn/guides/prefab/)
+一起走,和任何组件一样——不新增资产类型:
+
+```typescript
+import { EventBinding, UIEventType } from 'esengine';
+
+world.insert(button, EventBinding, {
+ rows: [
+ { event: UIEventType.Click, action: 'ui.setPage', params: { controller: 'tabs', page: 'settings' } },
+ { event: 'trigger_enter', target: 'Door', action: 'ui.setVisible', params: { visible: true }, once: true },
+ ],
+});
+```
+
+| `EventBindingRow` | 说明 |
+|---|---|
+| `event` | 要监听的事件类型。任意字符串——内建的只是众所周知的那一批。 |
+| `target` | 动作运行所在实体的名字。省略即挂着这行的实体自己。 |
+| `action` | 已注册的动作名。 |
+| `params` | 该动作声明的参数,按名字给。 |
+| `arg` | 同一份输入的规范字符串形式(`"tabs:settings"`)。两种写法都能跑。 |
+| `guard` | 必须通过才执行该行的具名条件。 |
+| `once` | 每次运行最多执行一次。 |
+| `enabled` | `false` 让该行失效但不删除。 |
+
+连线只在运行态触发——编辑时编辑器绝不会执行你的动作。
+
+### 目标按名字就近解析
+
+`target` 是实体**名字**,由内向外查找:本行所在实体、它的子树、各级祖先的子树,最后才是整个
+场景。就近者胜——这正是让同一预制体的两个实例不会互相串线的原因:对话框 A 里的 `Close`
+按钮找到的永远是 A 的 `Panel`,不会是 B 的。
+
+匹配不到的名字会在检视器里标红,运行时也会告警,而不是悄悄失效。
+
+## 动作
+
+动作是共享注册表里的一个具名函数——`.esfsm` 状态钩子和 `.esbt` 叶子解析的是**同一个**
+注册表。注册一次,三个候选列表里都能看到。
+
+![按命名空间分组的动作候选列表](../../../../assets/guides/zh/events-palette.png)
+
+*候选按 `namespace.` 分组,引擎自带的动作还带一行说明。*
+
+引擎自带这些:
+
+| 动作 | 作用 |
+|---|---|
+| `ui.setPage` | 把 [UI 控制器](/docs/zh-cn/guides/ui-controllers/)切到某一页。 |
+| `ui.setVisible` | 显示/隐藏一棵 UI 子树(`UINode.display`)。 |
+| `property.set` | 写任意组件字段,按 `Component.dot.path` 寻址。 |
+| `fsm.fire` | 向目标的状态机发一个触发器。 |
+| `blackboard.set` | 设置一个黑板变量。 |
+| `timeline.play` · `timeline.pause` | 驱动目标上的[时间轴](/docs/zh-cn/guides/timeline/)。 |
+| `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | 驱动精灵序列帧。 |
+
+### 你自己的动作
+
+注册一次,这个名字在所有地方都能授权使用:
+
+```typescript
+import { registerAction } from 'esengine';
+
+registerAction('game.award', {
+ params: [
+ { name: 'kind', type: 'enum', options: [{ label: '金币', value: 'coin' }, { label: '星星', value: 'star' }] },
+ { name: 'amount', type: 'number' },
+ ],
+ run: (ctx, bb, arg, params) => {
+ grantReward(ctx.entity, params!.kind as string, params!.amount as number);
+ },
+});
+```
+
+声明 `params` 正是把编辑器里那个文本框变成下拉框和数字框的原因。`ctx` 与 FSM 动作拿到的
+是同一种上下文——`entity`、`world`、`commands`,外加黑板。
+
+<Aside type="tip" title="注册写在哪">
+编辑器从不执行你的游戏代码,所以它是从项目的**声明入口**(默认 `src/components.ts`——
+也就是它读取组件的那个模块)得知你的动作名的。写在那里,名字就会出现在所有候选列表里;
+写在别处运行时照样有效,只是需要你手输名字。
+</Aside>
+
+## 有哪些事件
+
+控件发出标准的那一批(`UIEventType`),并且事件会**冒泡**,所以挂在面板上的一行能听到它子级
+按钮的事件:
+
+`click` · `press` · `release` · `hover_enter` · `hover_exit` · `focus` · `blur` ·
+`change` · `submit` · `drag_start` · `drag_move` · `drag_end` · `scroll` · `select` · `deselect`
+
+[物理](/docs/zh-cn/guides/physics/)接触也走同一条通道(`PhysicsEventType`),所以
+[触发区](/docs/zh-cn/guides/markers/)的接线方式和按钮一模一样——双方都会收到事件,各自拿到对方:
+
+`collision_enter` · `collision_exit` · `collision_hit` · `trigger_enter` · `trigger_exit`
+
+这套词汇是开放的:你在任何地方发出自己的事件名,某一行都能监听它。
+
+```typescript
+import { EntityEvents } from 'esengine';
+
+app.getResource(EntityEvents).emit(chest, 'looted', { gold: 12 });
+```
+
+## 当一根线需要逻辑时
+
+一行只跑一个动作,没有"如果",也没有先后序列。这是**刻意**设的天花板,而 `fsm.fire` 就是
+突破口——点击发出一个触发器,实体的[状态机](/docs/zh-cn/guides/ai/)来决定它意味着什么:
+
+```
+click ─▶ fsm.fire(start) 目标「Hint」 → Idle ──start──▶ Running
+ onEnter: property.set(…)
+```
+
+![状态机编辑器中,状态钩子的声明式参数](../../../../assets/guides/zh/events-fsm.png)
+
+*同一套参数控件,出现在状态机编辑器里:`property.set` 声明了 `path` 和 `value`,于是钩子
+显示两个字段,而不是一个含义不明的字符串。*
+
+一个动作只声明一次参数,所有授权界面都会长出来——事件行、FSM 状态钩子、行为树叶子。
+
+## 同一份输入的两种写法
+
+每个动作都保留一份规范字符串形式。`{ controller: 'tabs', page: 'settings' }` 和
+`"tabs:settings"` 是彼此的投影,注册表负责两个方向的转换,因此:
+
+- 在动作声明参数**之前**写下的数据照样能跑,不用迁移;
+- 只读 `arg` 的动作,在行以参数形式书写时依然能收到字符串;
+- 存的是普通字符串的行,编辑器照样能给出真控件。
+
+你不需要做选择:检视器写参数形式,手写数据两种都行。
+
+<Aside type="caution" title="暂不支持:资产与实体参数">
+参数不能是资产引用或实体句柄。打包的资产发现流程和场景的实体重映射都不会深入到行的参数里,
+这样的参数会让构建产物缺资产——一个会悄悄玩坏游戏的控件,比没有这个控件更糟。跨实体请用
+`target` 名字,引用资产请通过打包能看见的组件。
+</Aside>
+
+## 示例
+
+`examples/ui-events` 把整套能力放进一个项目——两个页签按钮、一个跨实体的角标,以及一个把
+控制权交给状态机的 *Start run* 按钮。它的 `src/main.ts` 是空的;里面的每一个行为都是授权数据。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/markers.mdx b/docs/astro/src/content/docs/zh-cn/guides/markers.mdx
index a26888d43..0d058b40e 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/markers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/markers.mdx
@@ -148,3 +148,4 @@ const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, mar
- [瓦片地图](/docs/zh-cn/guides/tilemap/) —— 碰撞(障碍)层与喂给同一批 Marker 的 Tiled 对象层。
- [物理](/docs/zh-cn/guides/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `PhysicsEvents` 资源。
- [场景](/docs/zh-cn/guides/scene/) —— Marker 与 Trigger Area 随场景序列化。
+- [事件绑定](/docs/zh-cn/guides/events/) —— 有东西进入 Trigger Area 时执行一个动作,直接挂在触发区上,不写代码。
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.mdx
index e3e5317fa..24dcad8fe 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
@@ -11,8 +11,8 @@ import { Aside } from '@astrojs/starlight/components';
或任何可反射的字段,可瞬切也可补间。
一个控制器驱动多个元素,而整套东西就是普通的 ECS 数据(两个组件 `UIController` 和
-`UIGear`),会随 [预制体](/docs/guides/prefab/) 一起走、序列化进场景。它是
-[按钮](/docs/guides/ui-components/#button) 那种"单控件状态"的共享化、多页化推广——
+`UIGear`),会随 [预制体](/docs/zh-cn/guides/prefab/) 一起走、序列化进场景。它是
+[按钮](/docs/zh-cn/guides/ui-components/#button) 那种"单控件状态"的共享化、多页化推广——
页签、单选组、按钮状态、面板显隐,统一用一套机制。
## 控制器
@@ -67,7 +67,7 @@ world.insert(card, UIGear, {
```
`gearBinding(controller, component, property, pages, tween?)` 寻址字段的方式和
-[时间轴](/docs/guides/timeline/) 属性轨道一致——组件名 + 点路径 `property`
+[时间轴](/docs/zh-cn/guides/timeline/) 属性轨道一致——组件名 + 点路径 `property`
(`"color"`、`"color.a"`、`"scale.x"`)。`pages` 是按页名索引的 **稀疏** 映射:某页没有条目就
不动这个字段。
@@ -125,7 +125,7 @@ world.insert(btn, UIGear, {
- **添加控制器**(指针按钮预设一键添加带四页的 `$interaction`),页以 **chip** 管理:
单击预览、双击重命名、拖拽排序、悬停 × 删除——重命名会级联进所有解析到该控制器的
绑定,删页会清掉该页已录的值。
-- 点击某个控制器使其 **活动**。在 [细节](/docs/guides/editor/) 面板里,每个字段旁便出现一个小的
+- 点击某个控制器使其 **活动**。在 [细节](/docs/zh-cn/guides/editor/) 面板里,每个字段旁便出现一个小的
**gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。再点已绑定的点,
打开设置:切页 **过渡**(时长 + 缓动,0 = 瞬切)与解绑。
- 打开 **录制**:此时每次编辑都写入控制器的 **当前页**——还没绑定的字段会当场自动
@@ -140,7 +140,7 @@ world.insert(btn, UIGear, {
两座桥从 *数据* 或 *逻辑* 切页,各自复用一套已有系统。
-**从信号** —— `bindControllerPage` 用一个 [响应式信号](/docs/guides/ui/) 驱动控制器的页,
+**从信号** —— `bindControllerPage` 用一个 [响应式信号](/docs/zh-cn/guides/ui/) 驱动控制器的页,
这是数据驱动页签的声明式路径:
```typescript
@@ -152,8 +152,15 @@ bindControllerPage(world, root, 'tab', activeTab); // 控制器跟随信号
activeTab.set('shop'); // 翻页,所有被绑定的元素重排
```
+**从按钮,且不写代码** —— 在按钮上挂一根[事件连线](/docs/zh-cn/guides/events/),点击时执行
+`ui.setPage`,目标指向持有该控制器的实体:
+
+```json
+{ "event": "click", "action": "ui.setPage", "params": { "controller": "tab", "page": "shop" } }
+```
+
**从状态机** —— `ui.setPage` 动作让数据驱动的
-[FSM / 行为树](/docs/guides/ai/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:
+[FSM / 行为树](/docs/zh-cn/guides/ai/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:
```json
{ "onEnter": { "name": "ui.setPage", "arg": "hud:alert" } }
@@ -171,7 +178,8 @@ activeTab.set('shop'); // 翻页,所有被绑定的元素重排
## 参见
-- [UI](/docs/guides/ui/) —— 绑定所驱动的 flexbox 组件模型。
-- [UI 控件](/docs/guides/ui-components/) —— 控件工厂。
-- [时间轴](/docs/guides/timeline/) —— 关键帧过渡;绑定用的是同一套字段寻址。
-- [游戏 AI](/docs/guides/ai/) —— 能调用 `ui.setPage` 的 `.esfsm` / `.esbt`。
+- [UI](/docs/zh-cn/guides/ui/) —— 绑定所驱动的 flexbox 组件模型。
+- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 控件工厂。
+- [时间轴](/docs/zh-cn/guides/timeline/) —— 关键帧过渡;绑定用的是同一套字段寻址。
+- [游戏 AI](/docs/zh-cn/guides/ai/) —— 能调用 `ui.setPage` 的 `.esfsm` / `.esbt`。
+- [事件绑定](/docs/zh-cn/guides/events/) —— 把点击直接接到 `ui.setPage`,不写代码。
diff --git a/examples/README.md b/examples/README.md
index 8573b3929..d6c3b1e10 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -43,7 +43,7 @@ for your own game.
| **ui-layout** | UI | Flexbox-style responsive UI layout. |
| **ui-list** | UI | A virtualized list and grid — `createListView`, live data, `scrollToIndex`. |
| **ui-controller** | UI | Shared UI controllers + declarative per-page gears: a tab bar, an `$interaction` button, and a tweened popup. |
-| **ui-events** | UI | Visual event binding — `EventBinding` rows wire a button's `click` to a named action (`ui.setPage`), including on another entity by name. `src/main.ts` is empty. |
+| **ui-events** | UI | Visual event binding — `EventBinding` rows wire a button's `click` to a named action (`ui.setPage`), on another entity by name, and via `fsm.fire` into a `.esfsm`. `src/main.ts` is empty. |
| **chat** | UI | A chat log — virtualized ListView + TextInput composer with two-way binding. |
| **rich-text** | UI | A live rich-text playground — type markup (and 中文 via IME) into a TextInput and watch a `Text` render bold/italic/color/font-size runs. |
| **enemy-ai** | AI | A state machine drives enemies to patrol, sense the player, and chase via A* navigation. |
diff --git a/examples/ui-events/assets/ai/director.esfsm b/examples/ui-events/assets/ai/director.esfsm
new file mode 100644
index 000000000..e27b3f6a9
--- /dev/null
+++ b/examples/ui-events/assets/ai/director.esfsm
@@ -0,0 +1,25 @@
+{
+ "initial": "Idle",
+ "states": [
+ {
+ "name": "Idle",
+ "x": 80,
+ "y": 110,
+ "transitions": [
+ { "to": "Running", "trigger": "start" }
+ ]
+ },
+ {
+ "name": "Running",
+ "x": 400,
+ "y": 110,
+ "onEnter": {
+ "name": "property.set",
+ "params": {
+ "path": "Text.content",
+ "value": "The button fired a trigger; this state machine wrote the line."
+ }
+ }
+ }
+ ]
+}
diff --git a/examples/ui-events/assets/ai/director.esfsm.meta b/examples/ui-events/assets/ai/director.esfsm.meta
new file mode 100644
index 000000000..c5a5bcbd5
--- /dev/null
+++ b/examples/ui-events/assets/ai/director.esfsm.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "f9f53061-1bd9-49ae-9874-bd401ec8d86a",
+ "version": "2.0",
+ "type": "statemachine",
+ "importer": {}
+}
diff --git a/examples/ui-events/assets/scenes/main.esscene b/examples/ui-events/assets/scenes/main.esscene
index 7bc8cc565..941265017 100644
--- a/examples/ui-events/assets/scenes/main.esscene
+++ b/examples/ui-events/assets/scenes/main.esscene
@@ -8,8 +8,25 @@
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
- { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
],
"visible": true
},
@@ -17,16 +34,45 @@
"id": 1,
"name": "Canvas",
"parent": null,
- "children": [2, 3, 5, 7, 10],
+ "children": [
+ 2,
+ 3,
+ 5,
+ 7,
+ 10,
+ 11
+ ],
"components": [
- { "type": "Transform", "data": {} },
- { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
- { "type": "UINode", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 800,
+ "y": 600
+ },
+ "scaleMode": 2
+ }
+ },
+ {
+ "type": "UINode",
+ "data": {}
+ },
{
"type": "UIController",
"data": {
"controllers": [
- { "name": "tabs", "pages": ["home", "settings"], "current": "home" }
+ {
+ "name": "tabs",
+ "pages": [
+ "home",
+ "settings"
+ ],
+ "current": "home"
+ }
]
}
}
@@ -39,16 +85,34 @@
"parent": 1,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 660, "unit": 0 },
- "height": { "value": 40, "unit": 0 },
- "insetLeft": { "value": 50, "unit": 1 },
- "marginLeft": { "value": -330, "unit": 0 },
- "insetTop": { "value": 36, "unit": 0 }
+ "width": {
+ "value": 660,
+ "unit": 0
+ },
+ "height": {
+ "value": 40,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": -330,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 36,
+ "unit": 0
+ }
}
},
{
@@ -56,7 +120,12 @@
"data": {
"content": "These buttons run actions with no game code — the wires are Events rows",
"fontSize": 17,
- "color": { "r": 0.9, "g": 0.92, "b": 0.96, "a": 1 },
+ "color": {
+ "r": 0.9,
+ "g": 0.92,
+ "b": 0.96,
+ "a": 1
+ },
"align": 1,
"verticalAlign": 1
}
@@ -68,27 +137,75 @@
"id": 3,
"name": "HomeButton",
"parent": 1,
- "children": [4],
+ "children": [
+ 4
+ ],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 170, "unit": 0 },
- "height": { "value": 44, "unit": 0 },
- "insetLeft": { "value": 50, "unit": 1 },
- "marginLeft": { "value": -180, "unit": 0 },
- "insetTop": { "value": 108, "unit": 0 }
+ "width": {
+ "value": 170,
+ "unit": 0
+ },
+ "height": {
+ "value": 44,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": -180,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 108,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.19,
+ "g": 0.21,
+ "b": 0.26,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
}
},
- { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.19, "g": 0.21, "b": 0.26, "a": 1 } } },
- { "type": "Interactable", "data": { "enabled": true, "blockRaycast": true, "raycastTarget": true } },
{
"type": "UIController",
"data": {
"controllers": [
- { "name": "$interaction", "pages": ["normal", "hover", "pressed", "disabled", "focused"], "current": "normal" }
+ {
+ "name": "$interaction",
+ "pages": [
+ "normal",
+ "hover",
+ "pressed",
+ "disabled",
+ "focused"
+ ],
+ "current": "normal"
+ }
]
}
},
@@ -101,11 +218,29 @@
"component": "UIVisual",
"property": "color",
"pages": {
- "normal": { "r": 0.19, "g": 0.21, "b": 0.26, "a": 1 },
- "hover": { "r": 0.26, "g": 0.29, "b": 0.36, "a": 1 },
- "pressed": { "r": 0.14, "g": 0.16, "b": 0.2, "a": 1 }
+ "normal": {
+ "r": 0.19,
+ "g": 0.21,
+ "b": 0.26,
+ "a": 1
+ },
+ "hover": {
+ "r": 0.26,
+ "g": 0.29,
+ "b": 0.36,
+ "a": 1
+ },
+ "pressed": {
+ "r": 0.14,
+ "g": 0.16,
+ "b": 0.2,
+ "a": 1
+ }
},
- "tween": { "easing": 5, "duration": 0.12 }
+ "tween": {
+ "easing": 5,
+ "duration": 0.12
+ }
}
]
}
@@ -114,8 +249,17 @@
"type": "EventBinding",
"data": {
"rows": [
- { "event": "click", "action": "ui.setPage", "arg": "tabs:home" },
- { "event": "click", "action": "ui.setPage", "arg": "badge:off", "target": "Card" }
+ {
+ "event": "click",
+ "action": "ui.setPage",
+ "arg": "tabs:home"
+ },
+ {
+ "event": "click",
+ "action": "ui.setPage",
+ "arg": "badge:off",
+ "target": "Card"
+ }
]
}
}
@@ -128,15 +272,30 @@
"parent": 3,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "insetLeft": { "value": 0, "unit": 0 },
- "insetRight": { "value": 0, "unit": 0 },
- "insetTop": { "value": 0, "unit": 0 },
- "insetBottom": { "value": 0, "unit": 0 }
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
}
},
{
@@ -144,7 +303,12 @@
"data": {
"content": "Home",
"fontSize": 16,
- "color": { "r": 0.93, "g": 0.94, "b": 0.97, "a": 1 },
+ "color": {
+ "r": 0.93,
+ "g": 0.94,
+ "b": 0.97,
+ "a": 1
+ },
"align": 1,
"verticalAlign": 1
}
@@ -156,27 +320,75 @@
"id": 5,
"name": "SettingsButton",
"parent": 1,
- "children": [6],
+ "children": [
+ 6
+ ],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 170, "unit": 0 },
- "height": { "value": 44, "unit": 0 },
- "insetLeft": { "value": 50, "unit": 1 },
- "marginLeft": { "value": 10, "unit": 0 },
- "insetTop": { "value": 108, "unit": 0 }
+ "width": {
+ "value": 170,
+ "unit": 0
+ },
+ "height": {
+ "value": 44,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": 10,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 108,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.19,
+ "g": 0.21,
+ "b": 0.26,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
}
},
- { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.19, "g": 0.21, "b": 0.26, "a": 1 } } },
- { "type": "Interactable", "data": { "enabled": true, "blockRaycast": true, "raycastTarget": true } },
{
"type": "UIController",
"data": {
"controllers": [
- { "name": "$interaction", "pages": ["normal", "hover", "pressed", "disabled", "focused"], "current": "normal" }
+ {
+ "name": "$interaction",
+ "pages": [
+ "normal",
+ "hover",
+ "pressed",
+ "disabled",
+ "focused"
+ ],
+ "current": "normal"
+ }
]
}
},
@@ -189,11 +401,29 @@
"component": "UIVisual",
"property": "color",
"pages": {
- "normal": { "r": 0.19, "g": 0.21, "b": 0.26, "a": 1 },
- "hover": { "r": 0.26, "g": 0.29, "b": 0.36, "a": 1 },
- "pressed": { "r": 0.14, "g": 0.16, "b": 0.2, "a": 1 }
+ "normal": {
+ "r": 0.19,
+ "g": 0.21,
+ "b": 0.26,
+ "a": 1
+ },
+ "hover": {
+ "r": 0.26,
+ "g": 0.29,
+ "b": 0.36,
+ "a": 1
+ },
+ "pressed": {
+ "r": 0.14,
+ "g": 0.16,
+ "b": 0.2,
+ "a": 1
+ }
},
- "tween": { "easing": 5, "duration": 0.12 }
+ "tween": {
+ "easing": 5,
+ "duration": 0.12
+ }
}
]
}
@@ -202,8 +432,23 @@
"type": "EventBinding",
"data": {
"rows": [
- { "event": "click", "action": "ui.setPage", "params": { "controller": "tabs", "page": "settings" } },
- { "event": "click", "action": "ui.setPage", "params": { "controller": "badge", "page": "on" }, "target": "Card" }
+ {
+ "event": "click",
+ "action": "ui.setPage",
+ "params": {
+ "controller": "tabs",
+ "page": "settings"
+ }
+ },
+ {
+ "event": "click",
+ "action": "ui.setPage",
+ "params": {
+ "controller": "badge",
+ "page": "on"
+ },
+ "target": "Card"
+ }
]
}
}
@@ -216,15 +461,30 @@
"parent": 5,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "insetLeft": { "value": 0, "unit": 0 },
- "insetRight": { "value": 0, "unit": 0 },
- "insetTop": { "value": 0, "unit": 0 },
- "insetBottom": { "value": 0, "unit": 0 }
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
}
},
{
@@ -232,7 +492,12 @@
"data": {
"content": "Settings",
"fontSize": 16,
- "color": { "r": 0.93, "g": 0.94, "b": 0.97, "a": 1 },
+ "color": {
+ "r": 0.93,
+ "g": 0.94,
+ "b": 0.97,
+ "a": 1
+ },
"align": 1,
"verticalAlign": 1
}
@@ -244,26 +509,65 @@
"id": 7,
"name": "Card",
"parent": 1,
- "children": [8, 9],
+ "children": [
+ 8,
+ 9
+ ],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 440, "unit": 0 },
- "height": { "value": 230, "unit": 0 },
- "insetLeft": { "value": 50, "unit": 1 },
- "marginLeft": { "value": -220, "unit": 0 },
- "insetTop": { "value": 186, "unit": 0 }
+ "width": {
+ "value": 440,
+ "unit": 0
+ },
+ "height": {
+ "value": 230,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": -220,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 186,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.22,
+ "g": 0.45,
+ "b": 0.78,
+ "a": 1
+ }
}
},
- { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.22, "g": 0.45, "b": 0.78, "a": 1 } } },
{
"type": "UIController",
"data": {
"controllers": [
- { "name": "badge", "pages": ["off", "on"], "current": "off" }
+ {
+ "name": "badge",
+ "pages": [
+ "off",
+ "on"
+ ],
+ "current": "off"
+ }
]
}
},
@@ -276,10 +580,23 @@
"component": "UIVisual",
"property": "color",
"pages": {
- "home": { "r": 0.22, "g": 0.45, "b": 0.78, "a": 1 },
- "settings": { "r": 0.45, "g": 0.3, "b": 0.72, "a": 1 }
+ "home": {
+ "r": 0.22,
+ "g": 0.45,
+ "b": 0.78,
+ "a": 1
+ },
+ "settings": {
+ "r": 0.45,
+ "g": 0.3,
+ "b": 0.72,
+ "a": 1
+ }
},
- "tween": { "easing": 5, "duration": 0.2 }
+ "tween": {
+ "easing": 5,
+ "duration": 0.2
+ }
}
]
}
@@ -293,15 +610,30 @@
"parent": 7,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "insetLeft": { "value": 24, "unit": 0 },
- "insetRight": { "value": 24, "unit": 0 },
- "insetTop": { "value": 0, "unit": 0 },
- "insetBottom": { "value": 0, "unit": 0 }
+ "insetLeft": {
+ "value": 24,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 24,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
}
},
{
@@ -310,7 +642,12 @@
"content": "HOME — the click switched the \"tabs\" controller, and this card's colour and text are gears reading it.",
"fontSize": 16,
"wordWrap": true,
- "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
"align": 1,
"verticalAlign": 1
}
@@ -340,18 +677,44 @@
"parent": 7,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 18, "unit": 0 },
- "height": { "value": 18, "unit": 0 },
- "insetRight": { "value": 14, "unit": 0 },
- "insetTop": { "value": 14, "unit": 0 }
+ "width": {
+ "value": 18,
+ "unit": 0
+ },
+ "height": {
+ "value": 18,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 14,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 14,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 1,
+ "g": 0.78,
+ "b": 0.25,
+ "a": 0
+ }
}
},
- { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 1, "g": 0.78, "b": 0.25, "a": 0 } } },
{
"type": "UIGear",
"data": {
@@ -361,10 +724,23 @@
"component": "UIVisual",
"property": "color",
"pages": {
- "off": { "r": 1, "g": 0.78, "b": 0.25, "a": 0 },
- "on": { "r": 1, "g": 0.78, "b": 0.25, "a": 1 }
+ "off": {
+ "r": 1,
+ "g": 0.78,
+ "b": 0.25,
+ "a": 0
+ },
+ "on": {
+ "r": 1,
+ "g": 0.78,
+ "b": 0.25,
+ "a": 1
+ }
},
- "tween": { "easing": 5, "duration": 0.2 }
+ "tween": {
+ "easing": 5,
+ "duration": 0.2
+ }
}
]
}
@@ -378,16 +754,34 @@
"parent": 1,
"children": [],
"components": [
- { "type": "Transform", "data": {} },
+ {
+ "type": "Transform",
+ "data": {}
+ },
{
"type": "UINode",
"data": {
"position": 1,
- "width": { "value": 660, "unit": 0 },
- "height": { "value": 46, "unit": 0 },
- "insetLeft": { "value": 50, "unit": 1 },
- "marginLeft": { "value": -330, "unit": 0 },
- "insetTop": { "value": 448, "unit": 0 }
+ "width": {
+ "value": 660,
+ "unit": 0
+ },
+ "height": {
+ "value": 46,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": -330,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 476,
+ "unit": 0
+ }
}
},
{
@@ -396,7 +790,198 @@
"content": "src/main.ts is empty. Select a button and open Details → Events to see the wire.",
"fontSize": 14,
"wordWrap": true,
- "color": { "r": 0.62, "g": 0.66, "b": 0.73, "a": 1 },
+ "color": {
+ "r": 0.62,
+ "g": 0.66,
+ "b": 0.73,
+ "a": 1
+ },
+ "align": 1,
+ "verticalAlign": 1
+ }
+ },
+ {
+ "type": "StateMachineAgent",
+ "data": {
+ "fsm": "assets/ai/director.esfsm"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 11,
+ "name": "StartButton",
+ "parent": 1,
+ "children": [
+ 12
+ ],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": {
+ "value": 190,
+ "unit": 0
+ },
+ "height": {
+ "value": 38,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 50,
+ "unit": 1
+ },
+ "marginLeft": {
+ "value": -95,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 428,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.24,
+ "g": 0.3,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ },
+ {
+ "type": "UIController",
+ "data": {
+ "controllers": [
+ {
+ "name": "$interaction",
+ "pages": [
+ "normal",
+ "hover",
+ "pressed",
+ "disabled",
+ "focused"
+ ],
+ "current": "normal"
+ }
+ ]
+ }
+ },
+ {
+ "type": "UIGear",
+ "data": {
+ "bindings": [
+ {
+ "controller": "$interaction",
+ "component": "UIVisual",
+ "property": "color",
+ "pages": {
+ "normal": {
+ "r": 0.24,
+ "g": 0.3,
+ "b": 0.28,
+ "a": 1
+ },
+ "hover": {
+ "r": 0.3,
+ "g": 0.4,
+ "b": 0.36,
+ "a": 1
+ },
+ "pressed": {
+ "r": 0.18,
+ "g": 0.24,
+ "b": 0.22,
+ "a": 1
+ }
+ },
+ "tween": {
+ "easing": 5,
+ "duration": 0.12
+ }
+ }
+ ]
+ }
+ },
+ {
+ "type": "EventBinding",
+ "data": {
+ "rows": [
+ {
+ "event": "click",
+ "target": "Hint",
+ "action": "fsm.fire",
+ "params": {
+ "trigger": "start"
+ }
+ }
+ ]
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 12,
+ "name": "StartLabel",
+ "parent": 11,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Start run",
+ "fontSize": 15,
+ "color": {
+ "r": 0.9,
+ "g": 0.94,
+ "b": 0.92,
+ "a": 1
+ },
"align": 1,
"verticalAlign": 1
}
diff --git a/examples/ui-events/project.esproject b/examples/ui-events/project.esproject
index f439a4b75..7c5c0bdd6 100644
--- a/examples/ui-events/project.esproject
+++ b/examples/ui-events/project.esproject
@@ -1,7 +1,7 @@
{
"formatVersion": "1",
"name": "UI Events (no code)",
- "description": "Authored event wiring: buttons drive a UIController through EventBinding rows — the whole project ships zero gameplay code.",
+ "description": "Authored event wiring: buttons drive a UIController through EventBinding rows, and one hands off to a state machine — the whole project ships zero gameplay code.",
"tag": "UI",
"version": "0.1.0",
"defaultScene": "assets/scenes/main.esscene",
diff --git a/examples/ui-events/src/main.ts b/examples/ui-events/src/main.ts
index d2ed3ed55..6658e6ae7 100644
--- a/examples/ui-events/src/main.ts
+++ b/examples/ui-events/src/main.ts
@@ -6,11 +6,15 @@
// Open the scene, select a button, and look at the Details panel's Events
// section — that is the whole program.
//
-// The two buttons are deliberately authored differently: Home's rows carry the
+// The tab buttons are deliberately authored differently: Home's rows carry the
// canonical string (`tabs:home`), Settings' carry named parameters. Both run the
// same action the same way — the registry projects between the forms — so data
// written before an action declared its parameters keeps working.
//
+// "Start run" shows the ceiling and the way through it: a wire has no logic of
+// its own, so the row fires a trigger and the `.esfsm` on the Hint entity decides
+// what that means. Still no code — a state machine is data too.
+//
// The entry point exists because a project has one; there is nothing to put in
// it. Wiring only needs code when it needs LOGIC, and then the row points at an
// action name (`fsm.fire`) instead of growing branches of its own.