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: UI Components reference (en + zh)

esengine8d1ddf31bbfc
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 1525b1021..238f1527d 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -67,6 +67,7 @@ export default defineConfig({
{ label: 'Sprites & Rendering', translations: { 'zh-CN': '精灵与渲染' }, slug: 'guides/sprites' },
{ 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: '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.mdx
new file mode 100644
index 000000000..e095d4046
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -0,0 +1,218 @@
+---
+title: UI Components
+description: The built-in widget factories — Button, Toggle, Slider, Progress, Dropdown, and Dialog — their options and imperative handles, built on the UI component model.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The widget factories build common controls out of the [UI](/docs/guides/ui/) component
+model (`UINode` + `Interactable` + `StateMachine` + `StateVisuals`), so you don't wire
+each one by hand. Each factory takes an options object and returns either the created
+entity (Button) or a **handle** with imperative methods to read and drive it.
+
+Interactive widgets need the world and the UI event queue — `world` from `GetWorld()`
+and `events` from `Res(UIEvents)`, exactly as in the [UI guide](/docs/guides/ui/). They
+all accept `parent?`, a `node?` ([`UINode`](/docs/guides/ui/#uinode--the-layout-box)
+layout), and visual overrides.
+
+<Aside type="tip">
+ These are a convenient starting point, not a closed set — a widget is just an entity
+ tree with the UI components on it, so you can compose your own the same way.
+</Aside>
+
+## Button
+
+`createButton(opts)` spawns a clickable entity (with an optional child label) that
+transitions between visual states. Returns the button **entity**. A click is a
+press-then-release *over* the button.
+
+```typescript
+import { createButton } from 'esengine';
+
+const btn = createButton({
+ world, events, parent,
+ text: 'Play',
+ node: { width: px(160), height: px(44) },
+ states: {
+ normal: { color: { r: 0.20, g: 0.55, b: 1.0, a: 1 } },
+ hover: { color: { r: 0.30, g: 0.65, b: 1.0, a: 1 } },
+ pressed: { color: { r: 0.12, g: 0.45, b: 0.9, a: 1 } },
+ disabled:{ color: { r: 0.3, g: 0.3, b: 0.3, a: 1 } },
+ },
+ onClick: (entity) => { /* … */ },
+});
+```
+
+| Option | Description |
+|---|---|
+| `text` | Label — a string or a `TextInit`. Omit for no label. |
+| `states` | Map of state name (`normal` / `hover` / `pressed` / `disabled`) → color / sprite / scale override. |
+| `background` | Background visual (default: solid white). |
+| `transitionFlags` / `fadeDuration` | Transition type (default `ColorTint`) and lerp time (default `0` = snap). |
+| `disabled` | Start disabled. |
+| `onClick(entity)` | Click callback. |
+
+Flip a custom state later with `setButtonState(world, entity, 'loading')`.
+
+## Toggle
+
+`createToggle(opts)` composes a button with an on/off check indicator. Returns a
+`ToggleHandle`.
+
+```typescript
+import { createToggle } from 'esengine';
+
+const toggle = createToggle({
+ world, events, parent,
+ interactionStates: { normal: { color: /* … */ }, hover: { /* … */ }, pressed: { /* … */ } },
+ check: { color: { r: 0.2, g: 0.8, b: 0.4, a: 1 } }, // the "on" indicator
+ isOn: true,
+ onChange: (isOn, entity) => { /* … */ },
+});
+
+toggle.setIsOn(false); // programmatic change (fires onChange)
+toggle.setIsOn(true, true); // silent — skips onChange
+```
+
+| Option | Description |
+|---|---|
+| `interactionStates` | Frame visual states (like the button's `states`). |
+| `check` | The on-state indicator: `{ node?, color?, sprite? }`, shown when on. |
+| `isOn` | Initial state. |
+| `onChange(isOn, entity)` | Fires on toggle. |
+
+**Handle:** `isOn()`, `setIsOn(value, silent?)`, `entity`, `dispose()`.
+
+## Slider
+
+`createSlider(opts)` builds a track + fill + handle. Returns a `SliderHandle`.
+
+```typescript
+import { createSlider } from 'esengine';
+
+const slider = createSlider({
+ world, parent,
+ min: 0, max: 100, value: 50, step: 5,
+ onChange: (value) => { /* … */ },
+});
+
+slider.setValue(75);
+```
+
+| Option | Description |
+|---|---|
+| `min` / `max` / `value` | Range and initial value. |
+| `step` | Quantization step (`0` = continuous). |
+| `handleWidth` | Thumb width in pixels (default `12`). |
+| `trackVisual` / `fillVisual` / `handleVisual` | Per-part visuals. |
+| `onChange(value, entity)` | Fires on value change. |
+
+**Handle:** `getValue()`, `setValue(v)`, `valueAtLocalX(localX, trackWidth)`,
+`dispose()`, plus `trackEntity` / `fillEntity` / `handleEntity`.
+
+<Aside type="note">
+ The slider has **no built-in pointer input** — wire your own drag/click handler and
+ convert the pointer position with `valueAtLocalX()`, or call `setValue()` directly.
+</Aside>
+
+## Progress
+
+`createProgress(opts)` is a non-interactive fill bar. Returns a `ProgressHandle`.
+
+```typescript
+import { createProgress } from 'esengine';
+
+const bar = createProgress({
+ world, parent,
+ direction: 'right',
+ fill: { color: { r: 0.2, g: 0.8, b: 0.4, a: 1 } },
+ value: 0,
+});
+
+bar.setValue(0.6); // 0..1
+```
+
+| Option | Description |
+|---|---|
+| `value` | Initial progress, `0..1`. |
+| `direction` | Fill growth: `'right'` (default), `'left'`, `'up'`, `'down'`. |
+| `background` / `fill` | Track and fill visuals. |
+
+**Handle:** `value()`, `setValue(v)`, `dispose()`, plus `fillEntity`.
+
+## Dropdown
+
+`createDropdown(opts)` shows the current selection and opens a popup of option rows.
+It's generic over the option type. Returns a `DropdownHandle<T>`.
+
+```typescript
+import { createDropdown } from 'esengine';
+
+const dd = createDropdown({
+ world, events, parent,
+ options: ['Low', 'Medium', 'High'],
+ selectedIndex: 1,
+ onSelect: (index, option) => { /* … */ },
+});
+
+// Objects need a label mapper:
+createDropdown({
+ world, events, parent,
+ options: resolutions, // e.g. { w, h }[]
+ optionToLabel: (r) => `${r.w}×${r.h}`,
+ onSelect: (i, r) => applyResolution(r),
+});
+```
+
+| Option | Description |
+|---|---|
+| `options` | The list of selectable values. |
+| `selectedIndex` | Initial selection. |
+| `optionToLabel(option, i)` | Map a non-string option to its display text. |
+| `buttonStates` / `optionStates` | Colors for the main button and the option rows. |
+| `optionHeight` | Row height in pixels (default `32`). |
+| `onSelect(index, option, entity)` | Fires on selection. |
+
+**Handle:** `getSelected()`, `getSelectedIndex()`, `setSelectedIndex(i, silent?)`,
+`open()`, `close()`, `isOpen()`, `dispose()`.
+
+<Aside type="note">
+ Click-outside-to-close isn't wired — call `close()` from your own global input layer
+ if you need it.
+</Aside>
+
+## Dialog
+
+`createDialog(opts)` is a modal: a click-blocking backdrop with a centered panel,
+hidden until opened. Returns a `DialogHandle`. **Add your content as children of
+`panelEntity`.**
+
+```typescript
+import { createDialog, spawnUIEntity } from 'esengine';
+
+const dialog = createDialog({
+ world, parent,
+ panelNode: { width: px(420), height: px(260) },
+});
+
+spawnUIEntity({ world, parent: dialog.panelEntity, text: { content: 'Are you sure?' } });
+
+dialog.open();
+// …later
+dialog.close();
+```
+
+| Option | Description |
+|---|---|
+| `backdropNode` / `backdropVisual` | The full-viewport scrim behind the panel. |
+| `panelNode` / `panelVisual` | The modal panel (default: 400×300, centered). |
+| `startHidden` | Start closed (default `true`). |
+
+**Handle:** `open()`, `close()`, `isOpen()`, `dispose()`, plus `backdropEntity` /
+`panelEntity`.
+
+## Editor prefabs
+
+The same widgets ship as editor prefabs, so **Create… → UI** drops a ready-made
+Button, Toggle, Slider, and so on into the scene, which you then edit in Details. See
+[The Editor](/docs/guides/editor/).
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
new file mode 100644
index 000000000..7da5822c4
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
@@ -0,0 +1,210 @@
+---
+title: UI 控件
+description: 内置控件工厂——Button、Toggle、Slider、Progress、Dropdown、Dialog——它们的选项与命令式句柄,构建在 UI 组件模型之上。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+控件工厂用 [UI](/docs/zh-cn/guides/ui/) 组件模型(`UINode` + `Interactable` + `StateMachine` +
+`StateVisuals`)构建常见控件,免得你逐个手动接线。每个工厂接收一个选项对象,返回创建的实体
+(Button)或一个带命令式方法、用于读取和驱动它的**句柄(handle)**。
+
+交互式控件需要 world 和 UI 事件队列——`world` 来自 `GetWorld()`,`events` 来自 `Res(UIEvents)`,
+和 [UI 指南](/docs/zh-cn/guides/ui/)里一样。它们都接受 `parent?`、一个 `node?`
+([`UINode`](/docs/zh-cn/guides/ui/#uinode--the-layout-box) 布局)和视觉覆盖。
+
+<Aside type="tip">
+ 这些是方便的起点,而非封闭集合——一个控件不过是挂了 UI 组件的实体树,所以你能用同样方式组合
+ 自己的控件。
+</Aside>
+
+## Button 按钮
+
+`createButton(opts)` 生成一个可点击实体(带可选子标签),在各视觉状态间过渡。返回按钮**实体**。
+一次点击是在按钮*上*按下再松开。
+
+```typescript
+import { createButton } from 'esengine';
+
+const btn = createButton({
+ world, events, parent,
+ text: 'Play',
+ node: { width: px(160), height: px(44) },
+ states: {
+ normal: { color: { r: 0.20, g: 0.55, b: 1.0, a: 1 } },
+ hover: { color: { r: 0.30, g: 0.65, b: 1.0, a: 1 } },
+ pressed: { color: { r: 0.12, g: 0.45, b: 0.9, a: 1 } },
+ disabled:{ color: { r: 0.3, g: 0.3, b: 0.3, a: 1 } },
+ },
+ onClick: (entity) => { /* … */ },
+});
+```
+
+| 选项 | 说明 |
+|---|---|
+| `text` | 标签——字符串或 `TextInit`。省略则无标签。 |
+| `states` | 状态名(`normal` / `hover` / `pressed` / `disabled`)→ 颜色 / sprite / 缩放覆盖的映射。 |
+| `background` | 背景视觉(默认:纯白)。 |
+| `transitionFlags` / `fadeDuration` | 过渡类型(默认 `ColorTint`)和插值时间(默认 `0` = 立即)。 |
+| `disabled` | 初始禁用。 |
+| `onClick(entity)` | 点击回调。 |
+
+之后可用 `setButtonState(world, entity, 'loading')` 切到自定义状态。
+
+## Toggle 开关
+
+`createToggle(opts)` 用一个按钮加一个开/关勾选指示器组合而成。返回 `ToggleHandle`。
+
+```typescript
+import { createToggle } from 'esengine';
+
+const toggle = createToggle({
+ world, events, parent,
+ interactionStates: { normal: { color: /* … */ }, hover: { /* … */ }, pressed: { /* … */ } },
+ check: { color: { r: 0.2, g: 0.8, b: 0.4, a: 1 } }, // "开"指示器
+ isOn: true,
+ onChange: (isOn, entity) => { /* … */ },
+});
+
+toggle.setIsOn(false); // 程序化改变(触发 onChange)
+toggle.setIsOn(true, true); // 静默——跳过 onChange
+```
+
+| 选项 | 说明 |
+|---|---|
+| `interactionStates` | 框架视觉状态(类似按钮的 `states`)。 |
+| `check` | 开状态指示器:`{ node?, color?, sprite? }`,开时显示。 |
+| `isOn` | 初始状态。 |
+| `onChange(isOn, entity)` | 切换时触发。 |
+
+**句柄:** `isOn()`、`setIsOn(value, silent?)`、`entity`、`dispose()`。
+
+## Slider 滑块
+
+`createSlider(opts)` 构建轨道 + 填充 + 手柄。返回 `SliderHandle`。
+
+```typescript
+import { createSlider } from 'esengine';
+
+const slider = createSlider({
+ world, parent,
+ min: 0, max: 100, value: 50, step: 5,
+ onChange: (value) => { /* … */ },
+});
+
+slider.setValue(75);
+```
+
+| 选项 | 说明 |
+|---|---|
+| `min` / `max` / `value` | 范围与初始值。 |
+| `step` | 量化步长(`0` = 连续)。 |
+| `handleWidth` | 手柄宽度(像素,默认 `12`)。 |
+| `trackVisual` / `fillVisual` / `handleVisual` | 各部件视觉。 |
+| `onChange(value, entity)` | 值改变时触发。 |
+
+**句柄:** `getValue()`、`setValue(v)`、`valueAtLocalX(localX, trackWidth)`、`dispose()`,
+以及 `trackEntity` / `fillEntity` / `handleEntity`。
+
+<Aside type="note">
+ 滑块**没有内置指针输入**——自己接一个拖拽/点击处理器,用 `valueAtLocalX()` 把指针位置转成值,
+ 或直接调 `setValue()`。
+</Aside>
+
+## Progress 进度条
+
+`createProgress(opts)` 是一个非交互的填充条。返回 `ProgressHandle`。
+
+```typescript
+import { createProgress } from 'esengine';
+
+const bar = createProgress({
+ world, parent,
+ direction: 'right',
+ fill: { color: { r: 0.2, g: 0.8, b: 0.4, a: 1 } },
+ value: 0,
+});
+
+bar.setValue(0.6); // 0..1
+```
+
+| 选项 | 说明 |
+|---|---|
+| `value` | 初始进度,`0..1`。 |
+| `direction` | 填充增长方向:`'right'`(默认)、`'left'`、`'up'`、`'down'`。 |
+| `background` / `fill` | 轨道和填充视觉。 |
+
+**句柄:** `value()`、`setValue(v)`、`dispose()`,以及 `fillEntity`。
+
+## Dropdown 下拉
+
+`createDropdown(opts)` 显示当前选择,并弹出一个选项行列表。它对选项类型是泛型的。返回
+`DropdownHandle<T>`。
+
+```typescript
+import { createDropdown } from 'esengine';
+
+const dd = createDropdown({
+ world, events, parent,
+ options: ['Low', 'Medium', 'High'],
+ selectedIndex: 1,
+ onSelect: (index, option) => { /* … */ },
+});
+
+// 对象需要一个标签映射:
+createDropdown({
+ world, events, parent,
+ options: resolutions, // 例如 { w, h }[]
+ optionToLabel: (r) => `${r.w}×${r.h}`,
+ onSelect: (i, r) => applyResolution(r),
+});
+```
+
+| 选项 | 说明 |
+|---|---|
+| `options` | 可选值列表。 |
+| `selectedIndex` | 初始选择。 |
+| `optionToLabel(option, i)` | 把非字符串选项映射为显示文本。 |
+| `buttonStates` / `optionStates` | 主按钮和选项行的颜色。 |
+| `optionHeight` | 行高(像素,默认 `32`)。 |
+| `onSelect(index, option, entity)` | 选择时触发。 |
+
+**句柄:** `getSelected()`、`getSelectedIndex()`、`setSelectedIndex(i, silent?)`、`open()`、
+`close()`、`isOpen()`、`dispose()`。
+
+<Aside type="note">
+ 点击外部关闭没有接线——需要的话从你自己的全局输入层调 `close()`。
+</Aside>
+
+## Dialog 对话框
+
+`createDialog(opts)` 是一个模态:一个挡住点击的背景加一个居中面板,打开前隐藏。返回
+`DialogHandle`。**把你的内容作为 `panelEntity` 的子实体加进去。**
+
+```typescript
+import { createDialog, spawnUIEntity } from 'esengine';
+
+const dialog = createDialog({
+ world, parent,
+ panelNode: { width: px(420), height: px(260) },
+});
+
+spawnUIEntity({ world, parent: dialog.panelEntity, text: { content: '确定吗?' } });
+
+dialog.open();
+// …之后
+dialog.close();
+```
+
+| 选项 | 说明 |
+|---|---|
+| `backdropNode` / `backdropVisual` | 面板后方的全视口遮罩。 |
+| `panelNode` / `panelVisual` | 模态面板(默认:400×300,居中)。 |
+| `startHidden` | 初始关闭(默认 `true`)。 |
+
+**句柄:** `open()`、`close()`、`isOpen()`、`dispose()`,以及 `backdropEntity` / `panelEntity`。
+
+## 编辑器预制体
+
+这些控件同时作为编辑器预制体提供,所以 **创建… → UI** 会把现成的 Button、Toggle、Slider 等放进
+场景,你再在 Details 里编辑。见 [编辑器](/docs/zh-cn/guides/editor/)。