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
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.mdxindex 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 }),},