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(events): the Event Binding guide, in both languages
yhh8e64f8020974
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.pngnew file mode 100644index 000000000..2286932cfBinary files /dev/null and b/docs/astro/src/assets/guides/en/events-fsm.png differdiff --git a/docs/astro/src/assets/guides/en/events-palette.png b/docs/astro/src/assets/guides/en/events-palette.pngnew file mode 100644index 000000000..fa3280420Binary files /dev/null and b/docs/astro/src/assets/guides/en/events-palette.png differdiff --git a/docs/astro/src/assets/guides/en/events-section.png b/docs/astro/src/assets/guides/en/events-section.pngnew file mode 100644index 000000000..5fecef779Binary files /dev/null and b/docs/astro/src/assets/guides/en/events-section.png differdiff --git a/docs/astro/src/assets/guides/zh/events-fsm.png b/docs/astro/src/assets/guides/zh/events-fsm.pngnew file mode 100644index 000000000..b4c54bd76Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-fsm.png differdiff --git a/docs/astro/src/assets/guides/zh/events-palette.png b/docs/astro/src/assets/guides/zh/events-palette.pngnew file mode 100644index 000000000..9c90c62f8Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-palette.png differdiff --git a/docs/astro/src/assets/guides/zh/events-section.png b/docs/astro/src/assets/guides/zh/events-section.pngnew file mode 100644index 000000000..6ea83f418Binary files /dev/null and b/docs/astro/src/assets/guides/zh/events-section.png differdiff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdxindex 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.mdxnew file mode 100644index 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++++*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 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(…)+```++++*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.mdxindex 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.mdxindex 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 thactiveTab.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.mdxindex 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.mdxnew file mode 100644index 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 已经有图编辑器了。++## 检视器里的一根线++++*按钮上的两根线:都在 `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` 叶子解析的是**同一个**+注册表。注册一次,三个候选列表里都能看到。++++*候选按 `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(…)+```++++*同一套参数控件,出现在状态机编辑器里:`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.mdxindex 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.mdxindex 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.mdindex 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.esfsmnew file mode 100644index 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.metanew file mode 100644index 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.essceneindex 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.esprojectindex 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.tsindex 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.