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.

refactor(ui): share FILL_AXIS across progress/slider + document the Filled fill primitive

yhhdd444e0890ef
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index cfffb5ed9..799d32014 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -130,16 +130,30 @@ const bar = createProgress({
});
bar.setValue(0.6); // 0..1
+
+// Radial gauge (cooldown / ring meter) — a clockwise wedge from 12 o'clock:
+const ring = createProgress({ world, parent, radial: true, value: 0.75 });
```
| Option | Description |
|---|---|
| `value` | Initial progress, `0..1`. |
-| `direction` | Fill growth: `'right'` (default), `'left'`, `'up'`, `'down'`. |
+| `direction` | Linear fill growth: `'right'` (default), `'left'`, `'up'`, `'down'`. |
+| `radial` | Radial gauge instead of a bar — a clockwise wedge sweeping the full circle. Ignores `direction`. |
| `background` / `fill` | Track and fill visuals. |
**Handle:** `value()`, `setValue(v)`, `dispose()`, plus `fillEntity`.
+<Aside type="note">
+ **One fill primitive.** A progress bar is a single [`UIVisual`](/docs/guides/ui/) in
+ **`Filled`** mode — the same primitive the slider's fill is built on, mirroring Unity's
+ "health bar = Filled Image". `setValue()` writes `fillAmount`, so the fill is a
+ render-time crop with **no per-frame layout pass**, and a sprite fill *reveals* along
+ the axis instead of stretching. `direction` resolves to the `Filled` crop axis and
+ anchor edge through the shared `FILL_AXIS` table, so progress, slider, and any other
+ Filled-based widget fill identically.
+</Aside>
+
## Dropdown
`createDropdown(opts)` shows the current selection and opens a popup of option rows.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
index 2ccf5dd33..96e1cbe5b 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
@@ -126,16 +126,29 @@ const bar = createProgress({
});
bar.setValue(0.6); // 0..1
+
+// 径向仪表(冷却 / 环形计量)——从 12 点钟方向顺时针扫过的扇形:
+const ring = createProgress({ world, parent, radial: true, value: 0.75 });
```
| 选项 | 说明 |
|---|---|
| `value` | 初始进度,`0..1`。 |
-| `direction` | 填充增长方向:`'right'`(默认)、`'left'`、`'up'`、`'down'`。 |
+| `direction` | 线性填充增长方向:`'right'`(默认)、`'left'`、`'up'`、`'down'`。 |
+| `radial` | 用径向仪表替代进度条——顺时针扫过整圆的扇形。忽略 `direction`。 |
| `background` / `fill` | 轨道和填充视觉。 |
**句柄:** `value()`、`setValue(v)`、`dispose()`,以及 `fillEntity`。
+<Aside type="note">
+ **同一个填充原语。** 进度条就是一个处于 **`Filled`** 模式的
+ [`UIVisual`](/docs/guides/ui/)——与滑块填充共用同一个原语,对应 Unity 的
+ "血条 = Filled Image"。`setValue()` 写入 `fillAmount`,因此填充是渲染期裁剪、
+ **不触发每帧布局**,贴图填充会沿轴**揭示**而非拉伸。`direction` 通过共享的
+ `FILL_AXIS` 表解析为 `Filled` 的裁剪轴与锚定边,让进度条、滑块以及其他基于
+ Filled 的控件填充行为完全一致。
+</Aside>
+
## Dropdown 下拉
`createDropdown(opts)` 显示当前选择,并弹出一个选项行列表。它对选项类型是泛型的。返回
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index 6011f4a1e..e97653425 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -117,6 +117,8 @@ export {
buildText,
spawnUIEntity,
setUIVisible,
+ FILL_AXIS,
+ type LinearFillDirection,
type UINodeInit,
type UIVisualInit,
type TextInit,
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index ac17f7a28..bfa08abd4 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -186,6 +186,8 @@ export {
buildText,
spawnUIEntity,
setUIVisible,
+ FILL_AXIS,
+ type LinearFillDirection,
type UINodeInit,
type UIVisualInit,
type TextInit,
diff --git a/sdk/src/ui/widgets/helpers.ts b/sdk/src/ui/widgets/helpers.ts
index 389dc1f26..671573f69 100644
--- a/sdk/src/ui/widgets/helpers.ts
+++ b/sdk/src/ui/widgets/helpers.ts
@@ -105,6 +105,27 @@ export function buildUIVisual(init: UIVisualInit = {}): UIVisualData {
};
}
+/**
+ * Linear fill direction — the edge a partial fill grows toward. Shared
+ * vocabulary for progress bars, slider fills, and any widget built on the
+ * {@link UIVisualType.Filled} primitive.
+ */
+export type LinearFillDirection = 'right' | 'left' | 'up' | 'down';
+
+/**
+ * Map a {@link LinearFillDirection} to the `Filled` visual's crop axis
+ * ({@link FillMethod}) and anchor edge ({@link FillOrigin}): the fill grows
+ * along `direction`, cropped from the opposite edge. One canonical table so
+ * progress, slider, and future Filled widgets reveal identically — no
+ * per-widget re-derivation of "which axis, which origin".
+ */
+export const FILL_AXIS: Record<LinearFillDirection, readonly [FillMethod, FillOrigin]> = {
+ right: [FillMethod.Horizontal, FillOrigin.Left],
+ left: [FillMethod.Horizontal, FillOrigin.Right],
+ up: [FillMethod.Vertical, FillOrigin.Bottom],
+ down: [FillMethod.Vertical, FillOrigin.Top],
+};
+
export interface TextInit extends Partial<TextData> {}
export function buildText(init: TextInit = {}): TextData {
diff --git a/sdk/src/ui/widgets/progress.ts b/sdk/src/ui/widgets/progress.ts
index 02cea0875..1f53ef485 100644
--- a/sdk/src/ui/widgets/progress.ts
+++ b/sdk/src/ui/widgets/progress.ts
@@ -11,7 +11,13 @@ import {
type UIVisualData,
} from '../core/ui-visual';
-import { spawnUIEntity, type UINodeInit, type UIVisualInit } from './helpers';
+import {
+ spawnUIEntity,
+ FILL_AXIS,
+ type UINodeInit,
+ type UIVisualInit,
+ type LinearFillDirection,
+} from './helpers';
import { themeColors } from '../theme/tokens';
export interface ProgressOptions {
@@ -23,7 +29,7 @@ export interface ProgressOptions {
/** Fill renderer config (the filled bar). */
fill?: { color?: Color; sprite?: number };
/** Direction the fill grows (linear bars). Default: 'right'. */
- direction?: 'right' | 'left' | 'up' | 'down';
+ direction?: LinearFillDirection;
/**
* Radial gauge instead of a linear bar: the fill is a clockwise wedge
* sweeping the full circle from 12 o'clock (cooldown / ring meter).
@@ -102,11 +108,3 @@ export function createProgress(opts: ProgressOptions): ProgressHandle {
function clamp01(v: number): number {
return v < 0 ? 0 : v > 1 ? 1 : v;
}
-
-// Fill grows along `dir`, anchored at the opposite edge.
-const FILL_AXIS: Record<'right' | 'left' | 'up' | 'down', readonly [FillMethod, FillOrigin]> = {
- right: [FillMethod.Horizontal, FillOrigin.Left],
- left: [FillMethod.Horizontal, FillOrigin.Right],
- up: [FillMethod.Vertical, FillOrigin.Bottom],
- down: [FillMethod.Vertical, FillOrigin.Top],
-};
diff --git a/sdk/src/ui/widgets/slider.ts b/sdk/src/ui/widgets/slider.ts
index 1724ae912..93a3306e0 100644
--- a/sdk/src/ui/widgets/slider.ts
+++ b/sdk/src/ui/widgets/slider.ts
@@ -5,9 +5,9 @@ import type { World } from '../../world';
import { UINode, type UINodeData } from '../core/ui-node';
import { px, percent } from '../core/dimension';
-import { UIVisual, UIVisualType, FillMethod, FillOrigin, type UIVisualData } from '../core/ui-visual';
+import { UIVisual, UIVisualType, type UIVisualData } from '../core/ui-visual';
-import { spawnUIEntity, type UINodeInit, type UIVisualInit } from './helpers';
+import { spawnUIEntity, FILL_AXIS, type UINodeInit, type UIVisualInit } from './helpers';
import { themeColors } from '../theme/tokens';
export interface SliderOptions {
@@ -62,6 +62,10 @@ export function createSlider(opts: SliderOptions): SliderHandle {
const c = themeColors();
+ // Slider fill is a horizontal Filled bar growing from the left — the same
+ // partial-fill primitive progress uses, shared via FILL_AXIS.
+ const [fillMethod, fillOrigin] = FILL_AXIS.right;
+
const track = spawnUIEntity({
world: opts.world,
parent: opts.parent,
@@ -75,8 +79,8 @@ export function createSlider(opts: SliderOptions): SliderHandle {
node: { fill: true },
visual: {
visualType: UIVisualType.Filled,
- fillMethod: FillMethod.Horizontal,
- fillOrigin: FillOrigin.Left,
+ fillMethod,
+ fillOrigin,
fillAmount: fraction(value, min, max),
...(opts.fillVisual ?? { color: c.primary }),
},