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.

feat(ui): unify progress/slider fill on UIVisual.Filled + radial gauges

esenginedaaea3b68b0c
diff --git a/desktop/package.json b/desktop/package.json
index 0d9e20ef3..59b5dcb24 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -30,6 +30,7 @@
"verify:render:text:rect": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-rect.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs",
"verify:render:uinode": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-node-flex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-node-flex.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 electron scripts/headless-verify.mjs",
"verify:render:uimask": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-list-mask.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-list-mask.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":60},{\\\"x\\\":0.9,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60},{\\\"x\\\":0.5,\\\"y\\\":0.85,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60},{\\\"x\\\":0.5,\\\"y\\\":0.15,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60}]\" electron scripts/headless-verify.mjs",
+ "verify:render:filled": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-visual-filled.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-visual-filled.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.18,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.40,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40},{\\\"x\\\":0.58,\\\"y\\\":0.75,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.58,\\\"y\\\":0.25,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40},{\\\"x\\\":0.30,\\\"y\\\":0.20,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.20,\\\"y\\\":0.333,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:transform": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-transform.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-transform.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,255,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,0,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:material": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
diff --git a/desktop/public/scenes/ui-visual-filled.esscene b/desktop/public/scenes/ui-visual-filled.esscene
new file mode 100644
index 000000000..f6b16bd9b
--- /dev/null
+++ b/desktop/public/scenes/ui-visual-filled.esscene
@@ -0,0 +1,185 @@
+{
+ "version": "1.0",
+ "name": "UIVisual Filled — geometry+UV crop reveals a solid/textured fill along fillMethod/fillOrigin (progress/slider basis)",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "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 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [2, 4, 6],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
+ { "type": "UINode", "data": {} }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "HTrack",
+ "parent": 1,
+ "children": [3],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 80, "unit": 0 },
+ "insetTop": { "value": 270, "unit": 0 },
+ "width": { "value": 280, "unit": 0 },
+ "height": { "value": 60, "unit": 0 }
+ }
+ },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 1, "g": 0, "b": 0, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "HFill",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 0, "unit": 0 },
+ "insetTop": { "value": 0, "unit": 0 },
+ "insetRight": { "value": 0, "unit": 0 },
+ "insetBottom": { "value": 0, "unit": 0 }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 5,
+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "fillMethod": 0,
+ "fillOrigin": 0,
+ "fillAmount": 0.5,
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "VTrack",
+ "parent": 1,
+ "children": [5],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 440, "unit": 0 },
+ "insetTop": { "value": 80, "unit": 0 },
+ "width": { "value": 60, "unit": 0 },
+ "height": { "value": 440, "unit": 0 }
+ }
+ },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 1, "g": 0, "b": 0, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "VFill",
+ "parent": 4,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 0, "unit": 0 },
+ "insetTop": { "value": 0, "unit": 0 },
+ "insetRight": { "value": 0, "unit": 0 },
+ "insetBottom": { "value": 0, "unit": 0 }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 5,
+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "fillMethod": 1,
+ "fillOrigin": 2,
+ "fillAmount": 0.5,
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 6,
+ "name": "RTrack",
+ "parent": 1,
+ "children": [7],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 120, "unit": 0 },
+ "insetTop": { "value": 80, "unit": 0 },
+ "width": { "value": 160, "unit": 0 },
+ "height": { "value": 160, "unit": 0 }
+ }
+ },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 1, "g": 0, "b": 0, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 7,
+ "name": "RFill",
+ "parent": 6,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": { "value": 0, "unit": 0 },
+ "insetTop": { "value": 0, "unit": 0 },
+ "insetRight": { "value": 0, "unit": 0 },
+ "insetBottom": { "value": 0, "unit": 0 }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 5,
+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "fillMethod": 2,
+ "fillOrigin": 3,
+ "fillAmount": 0.25,
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/ui-visual-filled.textures.json b/desktop/public/scenes/ui-visual-filled.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/ui-visual-filled.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index 5d10e0198..8a4ef6f31 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding, VisualState } from './wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = 'b5571b685cb3643f';
+export const ABI_LAYOUT_HASH = 'd5ee06760541c1d8';
export interface AssetFieldMeta {
field: string;
@@ -599,7 +599,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'fillAmount'],
fields: {
visualType: { enum: [{ label: 'None', value: 0 }, { label: 'SolidColor', value: 1 }, { label: 'Image', value: 2 }, { label: 'NineSlice', value: 3 }, { label: 'Tiled', value: 4 }, { label: 'Filled', value: 5 }] },
- fillMethod: { enum: [{ label: 'Horizontal', value: 0 }, { label: 'Vertical', value: 1 }] },
+ fillMethod: { enum: [{ label: 'Horizontal', value: 0 }, { label: 'Vertical', value: 1 }, { label: 'Radial360', value: 2 }] },
fillOrigin: { enum: [{ label: 'Left', value: 0 }, { label: 'Right', value: 1 }, { label: 'Bottom', value: 2 }, { label: 'Top', value: 3 }] },
},
},
diff --git a/sdk/src/ui/core/ui-visual.ts b/sdk/src/ui/core/ui-visual.ts
index 654e0d7cc..b06f58bf6 100644
--- a/sdk/src/ui/core/ui-visual.ts
+++ b/sdk/src/ui/core/ui-visual.ts
@@ -32,10 +32,14 @@ export const UIVisualType = {
} as const;
export type UIVisualType = (typeof UIVisualType)[keyof typeof UIVisualType];
-/** Fill axis for Filled visuals (mirrors the C++ UIFillMethod enum). */
+/** Fill mode for Filled visuals (mirrors the C++ UIFillMethod enum). */
export const FillMethod = {
+ /** Linear crop along X. */
Horizontal: 0,
+ /** Linear crop along Y. */
Vertical: 1,
+ /** Angular clockwise sweep of the full circle (cooldown / ring gauge). */
+ Radial360: 2,
} as const;
export type FillMethod = (typeof FillMethod)[keyof typeof FillMethod];
diff --git a/sdk/src/ui/widgets/prefabs/Progress.esprefab b/sdk/src/ui/widgets/prefabs/Progress.esprefab
index 3fc6419b9..f17f8b460 100644
--- a/sdk/src/ui/widgets/prefabs/Progress.esprefab
+++ b/sdk/src/ui/widgets/prefabs/Progress.esprefab
@@ -204,8 +204,8 @@
"data": {
"position": 1,
"width": {
- "value": 40,
- "unit": 1
+ "value": 0,
+ "unit": 2
},
"height": {
"value": 0,
@@ -260,7 +260,7 @@
},
"insetRight": {
"value": 0,
- "unit": 2
+ "unit": 0
},
"insetBottom": {
"value": 0,
@@ -271,7 +271,7 @@
{
"type": "UIVisual",
"data": {
- "visualType": 1,
+ "visualType": 5,
"texture": 0,
"color": {
"r": 0.25,
@@ -299,7 +299,7 @@
},
"fillMethod": 0,
"fillOrigin": 0,
- "fillAmount": 1,
+ "fillAmount": 0.4,
"material": 0,
"enabled": true
}
diff --git a/sdk/src/ui/widgets/prefabs/Slider.esprefab b/sdk/src/ui/widgets/prefabs/Slider.esprefab
index c41850136..c87b79cfe 100644
--- a/sdk/src/ui/widgets/prefabs/Slider.esprefab
+++ b/sdk/src/ui/widgets/prefabs/Slider.esprefab
@@ -356,8 +356,8 @@
"data": {
"position": 1,
"width": {
- "value": 50,
- "unit": 1
+ "value": 0,
+ "unit": 2
},
"height": {
"value": 0,
@@ -412,7 +412,7 @@
},
"insetRight": {
"value": 0,
- "unit": 2
+ "unit": 0
},
"insetBottom": {
"value": 0,
@@ -423,7 +423,7 @@
{
"type": "UIVisual",
"data": {
- "visualType": 1,
+ "visualType": 5,
"texture": 0,
"color": {
"r": 0.25,
@@ -451,7 +451,7 @@
},
"fillMethod": 0,
"fillOrigin": 0,
- "fillAmount": 1,
+ "fillAmount": 0.5,
"material": 0,
"enabled": true
}
diff --git a/sdk/src/ui/widgets/prefabs/generated.ts b/sdk/src/ui/widgets/prefabs/generated.ts
index 87d611bcf..979c11c89 100644
--- a/sdk/src/ui/widgets/prefabs/generated.ts
+++ b/sdk/src/ui/widgets/prefabs/generated.ts
@@ -1106,8 +1106,8 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"data": {
"position": 1,
"width": {
- "value": 50,
- "unit": 1
+ "value": 0,
+ "unit": 2
},
"height": {
"value": 0,
@@ -1162,7 +1162,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
},
"insetRight": {
"value": 0,
- "unit": 2
+ "unit": 0
},
"insetBottom": {
"value": 0,
@@ -1173,7 +1173,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
{
"type": "UIVisual",
"data": {
- "visualType": 1,
+ "visualType": 5,
"texture": 0,
"color": {
"r": 0.25,
@@ -1201,7 +1201,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
},
"fillMethod": 0,
"fillOrigin": 0,
- "fillAmount": 1,
+ "fillAmount": 0.5,
"material": 0,
"enabled": true
}
@@ -1417,8 +1417,8 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"data": {
"position": 1,
"width": {
- "value": 40,
- "unit": 1
+ "value": 0,
+ "unit": 2
},
"height": {
"value": 0,
@@ -1473,7 +1473,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
},
"insetRight": {
"value": 0,
- "unit": 2
+ "unit": 0
},
"insetBottom": {
"value": 0,
@@ -1484,7 +1484,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
{
"type": "UIVisual",
"data": {
- "visualType": 1,
+ "visualType": 5,
"texture": 0,
"color": {
"r": 0.25,
@@ -1512,7 +1512,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
},
"fillMethod": 0,
"fillOrigin": 0,
- "fillAmount": 1,
+ "fillAmount": 0.4,
"material": 0,
"enabled": true
}
diff --git a/sdk/src/ui/widgets/progress.ts b/sdk/src/ui/widgets/progress.ts
index a1e6c2e26..02cea0875 100644
--- a/sdk/src/ui/widgets/progress.ts
+++ b/sdk/src/ui/widgets/progress.ts
@@ -3,8 +3,13 @@
import type { Color, Entity } from '../../types';
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 { spawnUIEntity, type UINodeInit, type UIVisualInit } from './helpers';
import { themeColors } from '../theme/tokens';
@@ -17,8 +22,14 @@ export interface ProgressOptions {
background?: UIVisualInit;
/** Fill renderer config (the filled bar). */
fill?: { color?: Color; sprite?: number };
- /** Direction the fill grows. Default: 'right'. */
+ /** Direction the fill grows (linear bars). Default: 'right'. */
direction?: 'right' | 'left' | 'up' | 'down';
+ /**
+ * Radial gauge instead of a linear bar: the fill is a clockwise wedge
+ * sweeping the full circle from 12 o'clock (cooldown / ring meter).
+ * When set, `direction` is ignored.
+ */
+ radial?: boolean;
/** Initial progress 0..1. Default 0. */
value?: number;
}
@@ -32,15 +43,20 @@ export interface ProgressHandle {
}
/**
- * Linear progress bar. Two entities: a track (background) and a fill
- * child whose rect anchors are rewritten each setValue to grow along
- * the configured direction.
+ * Linear progress bar. Two entities: a track (background) and a fill child
+ * that stretches over the track as a {@link UIVisualType.Filled} visual —
+ * `setValue` writes `fillAmount`, so the bar is a render-time crop with no
+ * per-frame layout pass, and a sprite fill reveals (not stretches). Direction
+ * selects the fill axis/origin.
*/
export function createProgress(opts: ProgressOptions): ProgressHandle {
const { world } = opts;
const direction = opts.direction ?? 'right';
let value = clamp01(opts.value ?? 0);
const c = themeColors();
+ const [fillMethod, fillOrigin] = opts.radial
+ ? ([FillMethod.Radial360, FillOrigin.Top] as const)
+ : FILL_AXIS[direction];
const track = spawnUIEntity({
world,
@@ -52,24 +68,24 @@ export function createProgress(opts: ProgressOptions): ProgressHandle {
const fill = spawnUIEntity({
world,
parent: track,
- node: nodeForProgress(direction, value),
+ node: { fill: true },
visual: {
+ visualType: UIVisualType.Filled,
color: opts.fill?.color ?? c.primary,
texture: opts.fill?.sprite ?? 0,
- visualType: opts.fill?.sprite ? 2 /* Image */ : 1 /* SolidColor */,
+ fillMethod,
+ fillOrigin,
+ fillAmount: value,
},
});
- const horizontal = direction === 'right' || direction === 'left';
-
function setValue(v: number): void {
const next = clamp01(v);
if (next === value) return;
value = next;
- const node = world.get(fill, UINode) as UINodeData;
- if (horizontal) node.width = percent(value * 100);
- else node.height = percent(value * 100);
- world.insert(fill, UINode, node);
+ const vis = world.get(fill, UIVisual) as UIVisualData;
+ vis.fillAmount = value;
+ world.insert(fill, UIVisual, vis);
}
return {
@@ -87,19 +103,10 @@ function clamp01(v: number): number {
return v < 0 ? 0 : v > 1 ? 1 : v;
}
-// Fill grows along `dir`: pinned to 3 edges, with width/height = value fraction.
-function nodeForProgress(
- dir: 'right' | 'left' | 'up' | 'down',
- t: number,
-): UINodeInit {
- switch (dir) {
- case 'right':
- return { position: 1, insetLeft: px(0), insetTop: px(0), insetBottom: px(0), width: percent(t * 100) };
- case 'left':
- return { position: 1, insetRight: px(0), insetTop: px(0), insetBottom: px(0), width: percent(t * 100) };
- case 'up':
- return { position: 1, insetLeft: px(0), insetRight: px(0), insetBottom: px(0), height: percent(t * 100) };
- case 'down':
- return { position: 1, insetLeft: px(0), insetRight: px(0), insetTop: px(0), height: percent(t * 100) };
- }
-}
+// 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 c1e9762c8..1724ae912 100644
--- a/sdk/src/ui/widgets/slider.ts
+++ b/sdk/src/ui/widgets/slider.ts
@@ -5,6 +5,7 @@ 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 { spawnUIEntity, type UINodeInit, type UIVisualInit } from './helpers';
import { themeColors } from '../theme/tokens';
@@ -71,8 +72,14 @@ export function createSlider(opts: SliderOptions): SliderHandle {
const fill = spawnUIEntity({
world: opts.world,
parent: track,
- node: fillNodeAt(fraction(value, min, max)),
- visual: opts.fillVisual ?? { color: c.primary },
+ node: { fill: true },
+ visual: {
+ visualType: UIVisualType.Filled,
+ fillMethod: FillMethod.Horizontal,
+ fillOrigin: FillOrigin.Left,
+ fillAmount: fraction(value, min, max),
+ ...(opts.fillVisual ?? { color: c.primary }),
+ },
});
const handle = spawnUIEntity({
@@ -82,13 +89,13 @@ export function createSlider(opts: SliderOptions): SliderHandle {
visual: opts.handleVisual ?? { color: c.onPrimary },
});
- // Value -> geometry: the fill's width is the value fraction; the handle's
- // left inset tracks it (centered via a -half-width margin). CSS-box version
- // of the old anchor mutation. (A driver system owns this in the F7 rework.)
+ // Value -> visuals: the fill's Filled amount is the value fraction (a
+ // render-time crop, no relayout); the handle's left inset tracks it,
+ // centered via a -half-width margin.
function writeVisuals(t: number): void {
- const fillNode = opts.world.get(fill, UINode) as UINodeData;
- fillNode.width = percent(t * 100);
- opts.world.insert(fill, UINode, fillNode);
+ const vis = opts.world.get(fill, UIVisual) as UIVisualData;
+ vis.fillAmount = t;
+ opts.world.insert(fill, UIVisual, vis);
const handleNode = opts.world.get(handle, UINode) as UINodeData;
handleNode.insetLeft = percent(t * 100);
@@ -128,17 +135,6 @@ function fraction(value: number, min: number, max: number): number {
return clamp((value - min) / (max - min), 0, 1);
}
-// Fill: absolute, pinned to the track's left/top/bottom, width = value fraction.
-function fillNodeAt(t: number): UINodeInit {
- return {
- position: 1, // Absolute
- insetLeft: px(0),
- insetTop: px(0),
- insetBottom: px(0),
- width: percent(t * 100),
- };
-}
-
// Handle: absolute, full height, fixed width, centered at the value fraction
// (left inset = t%, shifted left by half its width).
function handleNodeAt(t: number, width: number): UINodeInit {
diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.ts
index 1354317bf..641ffa515 100644
--- a/sdk/src/wasm.generated.ts
+++ b/sdk/src/wasm.generated.ts
@@ -134,6 +134,7 @@ export enum TextAlign {
export enum UIFillMethod {
Horizontal = 0,
Vertical = 1,
+ Radial360 = 2,
}
export enum UIFillOrigin {
diff --git a/sdk/tests/ui-slider-dropdown.test.ts b/sdk/tests/ui-slider-dropdown.test.ts
index 25d7f90c1..d39830120 100644
--- a/sdk/tests/ui-slider-dropdown.test.ts
+++ b/sdk/tests/ui-slider-dropdown.test.ts
@@ -8,6 +8,7 @@ import {
UIEventType,
UIRect,
UINode,
+ UIVisual,
DimensionUnit,
Text,
} from '../src/ui';
@@ -118,16 +119,14 @@ describe('createSlider', () => {
expect(onChange).not.toHaveBeenCalled();
});
- it('updates fill width (percent) on setValue', () => {
+ it('updates fill amount (Filled crop) on setValue', () => {
const slider = createSlider({
world: world as unknown as World,
min: 0, max: 1, value: 0,
});
slider.setValue(0.25);
- const node = world.get(slider.fillEntity, UINode) as {
- width: { value: number; unit: number };
- };
- expect(node.width).toEqual({ value: 25, unit: DimensionUnit.Percent });
+ const vis = world.get(slider.fillEntity, UIVisual) as { fillAmount: number };
+ expect(vis.fillAmount).toBe(0.25);
});
it('updates handle left inset (percent) to position it at t', () => {
diff --git a/sdk/tests/ui-widgets.test.ts b/sdk/tests/ui-widgets.test.ts
index 339a21a06..3c73b0a19 100644
--- a/sdk/tests/ui-widgets.test.ts
+++ b/sdk/tests/ui-widgets.test.ts
@@ -11,8 +11,10 @@ import {
StateMachine,
StateVisuals,
UINode,
- DimensionUnit,
UIVisual,
+ UIVisualType,
+ FillMethod,
+ FillOrigin,
UIEventQueue,
UIEventType,
TransitionFlag,
@@ -287,32 +289,63 @@ describe('createProgress', () => {
expect(q.value()).toBe(0);
});
- it('setValue updates fill width % (default "right", pinned left)', () => {
+ it('setValue writes fillAmount (default "right" = Filled from the left)', () => {
const p = createProgress({
world: world as unknown as World,
value: 0,
});
p.setValue(0.4);
- const node = world.get(p.fillEntity, UINode) as {
- width: { value: number; unit: number };
- insetLeft: { value: number; unit: number };
+ const vis = world.get(p.fillEntity, UIVisual) as {
+ visualType: number;
+ fillAmount: number;
+ fillMethod: number;
+ fillOrigin: number;
};
- expect(node.width).toEqual({ value: 40, unit: DimensionUnit.Percent });
- expect(node.insetLeft).toEqual({ value: 0, unit: DimensionUnit.Px });
+ expect(vis.visualType).toBe(UIVisualType.Filled);
+ expect(vis.fillAmount).toBeCloseTo(0.4);
+ expect(vis.fillMethod).toBe(FillMethod.Horizontal);
+ expect(vis.fillOrigin).toBe(FillOrigin.Left);
});
- it('pins the fill to the right when direction = "left"', () => {
+ it('anchors the fill to the right when direction = "left"', () => {
const p = createProgress({
world: world as unknown as World,
direction: 'left',
value: 0.25,
});
- const node = world.get(p.fillEntity, UINode) as {
- width: { value: number; unit: number };
- insetRight: { value: number; unit: number };
+ const vis = world.get(p.fillEntity, UIVisual) as {
+ fillAmount: number;
+ fillMethod: number;
+ fillOrigin: number;
};
- expect(node.width).toEqual({ value: 25, unit: DimensionUnit.Percent });
- expect(node.insetRight).toEqual({ value: 0, unit: DimensionUnit.Px });
+ expect(vis.fillAmount).toBeCloseTo(0.25);
+ expect(vis.fillMethod).toBe(FillMethod.Horizontal);
+ expect(vis.fillOrigin).toBe(FillOrigin.Right);
+ });
+
+ it('uses the vertical fill axis for "up" / "down"', () => {
+ const up = createProgress({ world: world as unknown as World, direction: 'up', value: 0.5 });
+ const down = createProgress({ world: world as unknown as World, direction: 'down', value: 0.5 });
+ const upVis = world.get(up.fillEntity, UIVisual) as { fillMethod: number; fillOrigin: number };
+ const downVis = world.get(down.fillEntity, UIVisual) as { fillMethod: number; fillOrigin: number };
+ expect(upVis.fillMethod).toBe(FillMethod.Vertical);
+ expect(upVis.fillOrigin).toBe(FillOrigin.Bottom);
+ expect(downVis.fillMethod).toBe(FillMethod.Vertical);
+ expect(downVis.fillOrigin).toBe(FillOrigin.Top);
+ });
+
+ it('radial gauges use Radial360 from the top', () => {
+ const p = createProgress({ world: world as unknown as World, radial: true, value: 0.25 });
+ const vis = world.get(p.fillEntity, UIVisual) as {
+ visualType: number;
+ fillMethod: number;
+ fillOrigin: number;
+ fillAmount: number;
+ };
+ expect(vis.visualType).toBe(UIVisualType.Filled);
+ expect(vis.fillMethod).toBe(FillMethod.Radial360);
+ expect(vis.fillOrigin).toBe(FillOrigin.Top);
+ expect(vis.fillAmount).toBeCloseTo(0.25);
});
it('dispose despawns the track', () => {
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 20bb23994..21b54a9f2 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -466,7 +466,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"sliceBorder.w","type":"float","group":"UIVisual"},
{"key":"tileSize.x","type":"float","group":"UIVisual"},
{"key":"tileSize.y","type":"float","group":"UIVisual"},
- {"key":"fillMethod","type":"enum","group":"UIVisual","values":["Horizontal","Vertical"]},
+ {"key":"fillMethod","type":"enum","group":"UIVisual","values":["Horizontal","Vertical","Radial360"]},
{"key":"fillOrigin","type":"enum","group":"UIVisual","values":["Left","Right","Bottom","Top"]},
{"key":"fillAmount","type":"float","group":"UIVisual"},
{"key":"material","type":"asset","group":"UIVisual"},
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 53411facc..35096fa70 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -187,7 +187,8 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {
enum_<esengine::ecs::UIFillMethod>("UIFillMethod")
.value("Horizontal", esengine::ecs::UIFillMethod::Horizontal)
- .value("Vertical", esengine::ecs::UIFillMethod::Vertical);
+ .value("Vertical", esengine::ecs::UIFillMethod::Vertical)
+ .value("Radial360", esengine::ecs::UIFillMethod::Radial360);
enum_<esengine::ecs::UIFillOrigin>("UIFillOrigin")
.value("Left", esengine::ecs::UIFillOrigin::Left)
@@ -1948,7 +1949,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "b5571b685cb3643f";
+static const char* kEsAbiLayoutHash = "d5ee06760541c1d8";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/UIVisual.hpp b/src/esengine/ecs/components/UIVisual.hpp
index 1cd1421fa..a59827d0f 100644
--- a/src/esengine/ecs/components/UIVisual.hpp
+++ b/src/esengine/ecs/components/UIVisual.hpp
@@ -30,10 +30,17 @@ enum class UIVisualType : u8 {
Filled
};
+/**
+ * @brief Fill mode for a Filled UIVisual. Horizontal/Vertical are linear crops
+ * along the axis; Radial360 is an angular clockwise sweep of the full
+ * circle (cooldown / ring gauge) starting from the fillOrigin edge
+ * (12/3/6/9 o'clock), growing by fillAmount.
+ */
ES_ENUM()
enum class UIFillMethod : u8 {
Horizontal,
- Vertical
+ Vertical,
+ Radial360
};
ES_ENUM()
diff --git a/src/esengine/renderer/plugins/BatchPlugin.cpp b/src/esengine/renderer/plugins/BatchPlugin.cpp
index 01a180ba5..680125376 100644
--- a/src/esengine/renderer/plugins/BatchPlugin.cpp
+++ b/src/esengine/renderer/plugins/BatchPlugin.cpp
@@ -12,6 +12,7 @@
*/
#include "BatchPlugin.hpp"
+#include <algorithm>
#include <cmath>
namespace esengine {
@@ -114,4 +115,73 @@ void BatchPlugin::emitNineSlice(
}
}
+void BatchPlugin::emitRadialFill(
+ TransientBufferPool& buffers, DrawList& draw_list, const ClipState& clips,
+ const glm::vec2& center, const glm::vec2& size, f32 angle,
+ f32 startAngle, f32 amount,
+ const glm::vec2& uvOffset, const glm::vec2& uvScale,
+ const glm::vec4& color, const BatchDrawKey& key
+) {
+ amount = std::clamp(amount, 0.0f, 1.0f);
+ f32 hx = size.x * 0.5f, hy = size.y * 0.5f;
+ if (amount <= 0.0001f || hx <= 0.0f || hy <= 0.0f) return;
+
+ constexpr f32 TWO_PI = 6.2831853071795864f;
+ const f32 sweep = amount * TWO_PI;
+
+ // Sample angles are the two endpoints plus any box corner the sweep crosses,
+ // measured as a clockwise distance from startAngle. Because the box edge
+ // between two corners is straight, a fan vertex at each corner reproduces the
+ // rectangle boundary exactly — no faceting.
+ f32 deltas[6];
+ u32 n = 0;
+ deltas[n++] = 0.0f;
+ const f32 cornerAngle[4] = {
+ std::atan2(hy, hx), std::atan2(hy, -hx),
+ std::atan2(-hy, -hx), std::atan2(-hy, hx),
+ };
+ for (u32 k = 0; k < 4; ++k) {
+ f32 d = startAngle - cornerAngle[k];
+ d -= TWO_PI * std::floor(d / TWO_PI); // wrap into [0, TWO_PI)
+ if (d > 0.0001f && d < sweep - 0.0001f) deltas[n++] = d;
+ }
+ deltas[n++] = sweep;
+ for (u32 i = 1; i < n; ++i) { // insertion sort (n <= 6)
+ f32 v = deltas[i];
+ i32 j = static_cast<i32>(i) - 1;
+ while (j >= 0 && deltas[j] > v) { deltas[j + 1] = deltas[j]; --j; }
+ deltas[j + 1] = v;
+ }
+
+ const f32 cosR = std::cos(angle), sinR = std::sin(angle);
+ const u32 pc = packColor(color);
+
+ BatchVertex verts[7];
+ verts[0] = { center, pc, uvOffset + glm::vec2(0.5f, 0.5f) * uvScale }; // fan hub = box center
+ for (u32 i = 0; i < n; ++i) {
+ f32 a = startAngle - deltas[i];
+ f32 ca = std::cos(a), sa = std::sin(a);
+ f32 aca = std::abs(ca), asa = std::abs(sa);
+ // Ray from center at angle a exits the centered box at the nearer axis wall.
+ f32 t = std::min(aca > 1e-6f ? hx / aca : 1e30f,
+ asa > 1e-6f ? hy / asa : 1e30f);
+ glm::vec2 p{ t * ca, t * sa }; // box-local, centered
+ verts[i + 1] = {
+ rotatePoint(center, center.x + p.x, center.y + p.y, cosR, sinR),
+ pc,
+ uvOffset + glm::vec2(p.x / size.x + 0.5f, p.y / size.y + 0.5f) * uvScale,
+ };
+ }
+
+ u32 indices[15];
+ u32 ic = 0;
+ for (u32 i = 1; i + 1 <= n; ++i) { // fan triangles (hub, i, i+1)
+ indices[ic++] = 0;
+ indices[ic++] = i;
+ indices[ic++] = i + 1;
+ }
+ if (ic == 0) return;
+ appendIndexedBatch(buffers, draw_list, clips, verts, n + 1, indices, ic, key);
+}
+
} // namespace esengine
diff --git a/src/esengine/renderer/plugins/BatchPlugin.hpp b/src/esengine/renderer/plugins/BatchPlugin.hpp
index 81e9dbc6e..967416dcd 100644
--- a/src/esengine/renderer/plugins/BatchPlugin.hpp
+++ b/src/esengine/renderer/plugins/BatchPlugin.hpp
@@ -53,6 +53,24 @@ protected:
const glm::vec2& uvOffset, const glm::vec2& uvScale,
const glm::vec4& color, const BatchDrawKey& key);
+ /**
+ * @brief Emits a centered angular wedge (Radial360 Filled): a triangle fan
+ * from the box center out to its perimeter, swept clockwise from
+ * @p startAngle by @p amount of the full circle.
+ * @details The wedge boundary follows the rectangle exactly — box corners
+ * crossed by the sweep become fan vertices, so edges stay straight
+ * and corners sharp (≤5 triangles, no per-frame tessellation).
+ * One BatchVertex stream, same shader as emitQuad — a radial gauge
+ * batches with every other UI quad.
+ * @param startAngle Sweep start in radians, box-local (before @p angle rotation).
+ * @param amount Filled fraction of the full circle, [0,1].
+ */
+ void emitRadialFill(TransientBufferPool& buffers, DrawList& draw_list, const ClipState& clips,
+ const glm::vec2& center, const glm::vec2& size, f32 angle,
+ f32 startAngle, f32 amount,
+ const glm::vec2& uvOffset, const glm::vec2& uvScale,
+ const glm::vec4& color, const BatchDrawKey& key);
+
u32 batch_shader_id_ = 0;
};
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cpp
index 3d1abe5fc..c8f5e8976 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp
@@ -13,6 +13,19 @@
namespace esengine {
+// Clockwise Radial360 start direction (box-local, +y = up), by origin edge:
+// Top = 12 o'clock, Right = 3, Bottom = 6, Left = 9.
+static f32 radialStartAngle(ecs::UIFillOrigin origin) {
+ constexpr f32 HALF_PI = 1.57079632679f;
+ switch (origin) {
+ case ecs::UIFillOrigin::Right: return 0.0f;
+ case ecs::UIFillOrigin::Bottom: return -HALF_PI;
+ case ecs::UIFillOrigin::Left: return 2.0f * HALF_PI;
+ case ecs::UIFillOrigin::Top: return HALF_PI;
+ }
+ return HALF_PI;
+}
+
void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
auto& registry = collect_ctx.registry;
auto& frustum = collect_ctx.frustum;
@@ -112,16 +125,53 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
if (renderer.fillOrigin == ecs::UIFillOrigin::Right) {
uvOffset.x = renderer.uvOffset.x + renderer.uvScale.x * (1.0f - amount);
}
- } else {
+ } else if (renderer.fillMethod == ecs::UIFillMethod::Vertical) {
uvScale.y = renderer.uvScale.y * amount;
if (renderer.fillOrigin == ecs::UIFillOrigin::Top) {
uvOffset.y = renderer.uvOffset.y + renderer.uvScale.y * (1.0f - amount);
}
}
+ // Radial360 samples the full base UV per fan vertex — no crop here.
}
glm::vec2 finalSize = glm::vec2(w, h) * glm::vec2(scale);
+ const bool isRadialFill = renderer.visualType == ecs::UIVisualType::Filled
+ && renderer.fillMethod == ecs::UIFillMethod::Radial360;
+
+ // Filled derives its own UV/geometry, so 9-slice never applies. Linear
+ // fills crop the box in lockstep with the UV crop above: the box shrinks
+ // to fillAmount along the axis, anchored at fillOrigin, its center shifting
+ // toward that edge by half the removed extent (rotated into world space to
+ // match the pivot bake). A UV-only crop would no-op on a solid colour and
+ // stretch a texture; cropping geometry too makes both reveal. Radial360
+ // is emitted as a wedge fan instead (below), so it skips the box crop.
+ if (renderer.visualType == ecs::UIVisualType::Filled) {
+ useNineSlice = false;
+ if (!isRadialFill) {
+ f32 amount = std::clamp(renderer.fillAmount, 0.0f, 1.0f);
+ f32 offX = 0.0f, offY = 0.0f;
+ if (renderer.fillMethod == ecs::UIFillMethod::Horizontal) {
+ f32 removed = finalSize.x * (1.0f - amount);
+ offX = (renderer.fillOrigin == ecs::UIFillOrigin::Right ? 0.5f : -0.5f) * removed;
+ finalSize.x *= amount;
+ } else {
+ f32 removed = finalSize.y * (1.0f - amount);
+ offY = (renderer.fillOrigin == ecs::UIFillOrigin::Top ? 0.5f : -0.5f) * removed;
+ finalSize.y *= amount;
+ }
+ if (std::abs(angle) > 0.001f) {
+ f32 cosA = std::cos(angle), sinA = std::sin(angle);
+ f32 rx = offX * cosA - offY * sinA;
+ f32 ry = offX * sinA + offY * cosA;
+ offX = rx;
+ offY = ry;
+ }
+ position.x += offX;
+ position.y += offY;
+ }
+ }
+
BatchDrawKey key{
.stage = ctx.current_stage,
.layer = layer,
@@ -135,7 +185,13 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
constexpr glm::vec2 CENTERED_PIVOT{0.5f, 0.5f};
- if (useNineSlice) {
+ if (isRadialFill) {
+ emitRadialFill(buffers, draw_list, clips,
+ glm::vec2(position), finalSize, angle,
+ radialStartAngle(renderer.fillOrigin),
+ std::clamp(renderer.fillAmount, 0.0f, 1.0f),
+ uvOffset, uvScale, renderer.color, key);
+ } else if (useNineSlice) {
emitNineSlice(buffers, draw_list, clips,
glm::vec2(position), finalSize, CENTERED_PIVOT,
angle, texSize, sliceBorder,