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.

examples(ui-controls): author the panel shell in the scene; flex rows; lazy modal

yhhd6d50166d05e
diff --git a/examples/ui-controls/assets/scenes/main.esscene b/examples/ui-controls/assets/scenes/main.esscene
index ff7cb1d74..15d42b69c 100644
--- a/examples/ui-controls/assets/scenes/main.esscene
+++ b/examples/ui-controls/assets/scenes/main.esscene
@@ -34,7 +34,9 @@
"id": 1,
"name": "Canvas",
"parent": null,
- "children": [],
+ "children": [
+ 2
+ ],
"components": [
{
"type": "Transform",
@@ -56,6 +58,346 @@
}
],
"visible": true
+ },
+ {
+ "id": 2,
+ "name": "Panel",
+ "parent": 1,
+ "children": [
+ 3,
+ 4,
+ 6,
+ 8,
+ 10,
+ 12,
+ 14
+ ],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": { "value": 460, "unit": 0 },
+ "height": { "value": 414, "unit": 0 },
+ "insetLeft": { "value": 50, "unit": 1 },
+ "insetTop": { "value": 50, "unit": 1 },
+ "marginLeft": { "value": -230, "unit": 0 },
+ "marginTop": { "value": -207, "unit": 0 }
+ }
+ },
+ {
+ "type": "FlexContainer",
+ "data": {
+ "direction": 1,
+ "justifyContent": 0,
+ "alignItems": 3,
+ "gap": { "x": 0, "y": 16 },
+ "padding": { "left": 24, "top": 24, "right": 24, "bottom": 24 }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": { "r": 0.16, "g": 0.16, "b": 0.18, "a": 1 },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Title",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 30, "unit": 0 } }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "UI Controls",
+ "fontSize": 20,
+ "bold": true,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "ClicksRow",
+ "parent": 2,
+ "children": [
+ 5
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "ClicksLabel",
+ "parent": 4,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Clicks: 0",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 6,
+ "name": "AnimateRow",
+ "parent": 2,
+ "children": [
+ 7
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 7,
+ "name": "AnimateLabel",
+ "parent": 6,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Animate",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 8,
+ "name": "VolumeRow",
+ "parent": 2,
+ "children": [
+ 9
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 9,
+ "name": "VolumeLabel",
+ "parent": 8,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Volume 60%",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 10,
+ "name": "LoadingRow",
+ "parent": 2,
+ "children": [
+ 11
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 11,
+ "name": "LoadingLabel",
+ "parent": 10,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Loading",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 12,
+ "name": "ModalRow",
+ "parent": 2,
+ "children": [
+ 13
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 13,
+ "name": "ModalLabel",
+ "parent": 12,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Modal",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 14,
+ "name": "AccentRow",
+ "parent": 2,
+ "children": [
+ 15
+ ],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "height": { "value": 40, "unit": 0 } }
+ },
+ {
+ "type": "FlexContainer",
+ "data": { "direction": 0, "justifyContent": 3, "alignItems": 1 }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 15,
+ "name": "AccentLabel",
+ "parent": 14,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": { "flexGrow": 1, "alignSelf": 4 }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Accent",
+ "fontSize": 14,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 1
+ }
+ }
+ ],
+ "visible": true
}
]
}
diff --git a/examples/ui-controls/src/config.ts b/examples/ui-controls/src/config.ts
index deac8c715..e20b42cfe 100644
--- a/examples/ui-controls/src/config.ts
+++ b/examples/ui-controls/src/config.ts
@@ -1,19 +1,8 @@
import type { Color } from 'esengine';
-// Panel + row geometry (a canvas-centred panel laid out as a flex column; each
-// row places its label + widget slot by absolute insets).
-export const PANEL_W = 460;
-export const PANEL_H = 452;
-export const PANEL_PAD = 24;
-export const ROW_GAP = 16;
-export const TITLE_H = 30;
-export const ROW_H = 40;
-export const LABEL_W = 132;
-export const SLOT_W = 244;
-
-// Slider track width in px (== world units at canvas scale 1). The drag system
-// reuses this to map the pointer's world x back to a 0..100 value.
-export const SLIDER_W = SLOT_W;
+// Widget sizes for the code-instantiated factories (px == world units at canvas
+// scale 1); the panel + row geometry lives in the scene.
+export const SLIDER_W = 244;
export const SLIDER_H = 18;
export const PROGRESS_H = 14;
export const CONTROL_H = 34;
@@ -21,8 +10,7 @@ export const CONTROL_H = 34;
// Progress bar auto-animation speed, in progress-fraction per second.
export const PROGRESS_SPEED = 0.5;
-// Dropdown accent choices — selecting one re-tints the slider fill + progress
-// fill, showing a dropdown driving live theme state.
+// Dropdown accent choices — selecting one re-tints the slider + progress fill.
export interface Accent {
name: string;
color: Color;
diff --git a/examples/ui-controls/src/main.ts b/examples/ui-controls/src/main.ts
index bad007a5c..e117cef41 100644
--- a/examples/ui-controls/src/main.ts
+++ b/examples/ui-controls/src/main.ts
@@ -1,7 +1,5 @@
-// UI Controls — a gallery of the imperative widget factories (createButton,
-// createSlider, createToggle, createProgress, createDropdown, createDialog) styled
-// from the design-token theme. The scene is just a Camera + Canvas; buildSystem
-// spawns everything, and controls.ts ticks the slider drag + progress animation.
+// UI Controls — widget factories (button/slider/toggle/progress/dropdown/dialog)
+// slotted into a scene-authored FlexContainer panel.
import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import { buildSystem } from './systems/build';
diff --git a/examples/ui-controls/src/state.ts b/examples/ui-controls/src/state.ts
index 9629159fe..264a6f5ff 100644
--- a/examples/ui-controls/src/state.ts
+++ b/examples/ui-controls/src/state.ts
@@ -1,18 +1,10 @@
-import type { Entity, SliderHandle, ProgressHandle } from 'esengine';
+import type { SliderHandle, ProgressHandle } from 'esengine';
-// What buildSystem hands to the per-frame controls system (only the slider and
-// progress bar are ticked; the other widgets self-wire their callbacks).
export const state = {
slider: null as SliderHandle | null,
progress: null as ProgressHandle | null,
- /** Left label of the slider row — updated with the live "Volume N%". */
- volumeLabel: 0 as Entity,
-
- /** True while the pointer is dragging the slider track. */
dragging: false,
- /** Progress animation phase 0..1 and its ping-pong direction. */
progressT: 0,
progressDir: 1,
- /** Toggle-controlled pause for the progress animation. */
paused: false,
};
diff --git a/examples/ui-controls/src/systems/build.ts b/examples/ui-controls/src/systems/build.ts
index ae80f3a08..957d119db 100644
--- a/examples/ui-controls/src/systems/build.ts
+++ b/examples/ui-controls/src/systems/build.ts
@@ -1,64 +1,30 @@
import {
- defineSystem, Query, Res, GetWorld,
- Canvas, UIEvents,
- Text, UIVisual, FlexContainer,
+ defineSystem, Res, GetWorld,
+ UIEvents,
+ Text, UIVisual,
Interactable, UIInteraction,
spawnUIEntity,
createButton, createToggle, createSlider, createProgress, createDropdown, createDialog,
themeColors, px, percent,
- UIPositionType, FlexDirection, JustifyContent, AlignItems, TextAlign, TextVerticalAlign,
+ UIPositionType, TextVerticalAlign,
} from 'esengine';
import type {
Entity, World, Color, ThemeColors, UIEventQueue, TextData, UIVisualData,
} from 'esengine';
-import {
- PANEL_W, PANEL_H, PANEL_PAD, ROW_GAP, TITLE_H, ROW_H, LABEL_W,
- SLIDER_W, SLIDER_H, PROGRESS_H, CONTROL_H, ACCENTS, type Accent,
-} from '../config';
+import { SLIDER_W, SLIDER_H, PROGRESS_H, CONTROL_H, ACCENTS, type Accent } from '../config';
import { state } from '../state';
-// Builds the panel and every widget once, at startup, from the widget factories + theme.
export const buildSystem = defineSystem(
- [Query(Canvas), Res(UIEvents), GetWorld()],
- (canvases: Iterable<[Entity, unknown]>, events: UIEventQueue, world: World) => {
- if (state.slider) return; // startup runs once, but stay idempotent
+ [Res(UIEvents), GetWorld()],
+ (events: UIEventQueue, world: World) => {
+ if (state.slider) return;
- let canvas: Entity | null = null;
- for (const [entity] of canvases) { canvas = entity; break; }
+ const canvas = world.findEntityByName('Canvas');
if (canvas === null) return;
const c = themeColors();
- // Centred panel, laid out as a flex column.
- const panel = spawnUIEntity({
- world, parent: canvas,
- node: {
- position: UIPositionType.Absolute,
- width: px(PANEL_W), height: px(PANEL_H),
- insetLeft: percent(50), insetTop: percent(50),
- marginLeft: px(-PANEL_W / 2), marginTop: px(-PANEL_H / 2),
- },
- visual: { color: c.surface },
- });
- world.insert(panel, FlexContainer, {
- direction: FlexDirection.Column,
- wrap: 0,
- justifyContent: JustifyContent.Start,
- alignItems: AlignItems.Stretch,
- alignContent: 0,
- gap: { x: 0, y: ROW_GAP },
- padding: { left: PANEL_PAD, top: PANEL_PAD, right: PANEL_PAD, bottom: PANEL_PAD },
- });
-
- spawnUIEntity({
- world, parent: panel,
- node: { height: px(TITLE_H) },
- text: { content: 'UI Controls', fontSize: 20, bold: true, color: c.onPrimary,
- align: TextAlign.Left, verticalAlign: TextVerticalAlign.Middle },
- });
-
- // Modal dialog overlay (hidden until "Open…"), populated with its own children.
const dialog = createDialog({
world, parent: canvas, startHidden: true,
panelNode: {
@@ -69,48 +35,58 @@ export const buildSystem = defineSystem(
},
panelVisual: { color: c.surfaceElevated },
});
- spawnUIEntity({
- world, parent: dialog.panelEntity,
- node: { position: UIPositionType.Absolute, insetLeft: px(0), insetRight: px(0),
- insetTop: px(26), height: px(26) },
- text: { content: 'Hello from a modal', fontSize: 18, bold: true, color: c.onPrimary },
- });
- spawnUIEntity({
- world, parent: dialog.panelEntity,
- node: { position: UIPositionType.Absolute, insetLeft: px(28), insetRight: px(28),
- insetTop: px(66), height: px(48) },
- text: { content: 'A dialog is just a backdrop plus a panel you fill with children.',
- fontSize: 13, color: c.onPrimary, wordWrap: true,
- verticalAlign: TextVerticalAlign.Top },
- });
- createButton({
- world, events, parent: dialog.panelEntity,
- node: { position: UIPositionType.Absolute, width: px(120), height: px(CONTROL_H),
- insetLeft: percent(50), marginLeft: px(-60), insetBottom: px(22) },
- states: controlStates(c),
- text: { content: 'Close', color: c.onPrimary, fontSize: 14 },
- onClick: () => dialog.close(),
- });
+ // Materialize the modal's content only while open — hiding a UI subtree does not hide child Text.
+ let dialogContent: Entity[] = [];
+ function closeDialog(): void {
+ dialog.close();
+ for (const e of dialogContent) if (world.valid(e)) world.despawn(e);
+ dialogContent = [];
+ }
+ function openDialog(): void {
+ if (dialogContent.length) return;
+ dialog.open();
+ dialogContent = [
+ spawnUIEntity({
+ world, parent: dialog.panelEntity,
+ node: { position: UIPositionType.Absolute, insetLeft: px(0), insetRight: px(0),
+ insetTop: px(26), height: px(26) },
+ text: { content: 'Hello from a modal', fontSize: 18, bold: true, color: c.onPrimary },
+ }),
+ spawnUIEntity({
+ world, parent: dialog.panelEntity,
+ node: { position: UIPositionType.Absolute, insetLeft: px(28), insetRight: px(28),
+ insetTop: px(66), height: px(48) },
+ text: { content: 'A dialog is just a backdrop plus a panel you fill with children.',
+ fontSize: 13, color: c.onPrimary, wordWrap: true,
+ verticalAlign: TextVerticalAlign.Top },
+ }),
+ createButton({
+ world, events, parent: dialog.panelEntity,
+ node: { position: UIPositionType.Absolute, width: px(120), height: px(CONTROL_H),
+ insetLeft: percent(50), marginLeft: px(-60), insetBottom: px(22) },
+ states: controlStates(c),
+ text: { content: 'Close', color: c.onPrimary, fontSize: 14 },
+ onClick: closeDialog,
+ }),
+ ];
+ }
- // Button: a click counter in the row label.
- {
- const { row, label } = makeRow(world, panel, c, 'Clicks: 0');
+ withRow(world, 'ClicksRow', (row) => {
+ const label = world.findEntityByName('ClicksLabel');
let clicks = 0;
createButton({
world, events, parent: row,
- node: slotNode(140, CONTROL_H),
+ node: slot(140, CONTROL_H),
states: primaryStates(c),
text: { content: 'Click me', color: c.onPrimary, fontSize: 14 },
- onClick: () => { clicks += 1; setText(world, label, `Clicks: ${clicks}`); },
+ onClick: () => { clicks += 1; if (label !== null) setText(world, label, `Clicks: ${clicks}`); },
});
- }
+ });
- // Toggle: pause/resume the progress animation.
- {
- const { row } = makeRow(world, panel, c, 'Animate');
+ withRow(world, 'AnimateRow', (row) => {
createToggle({
world, events, parent: row,
- node: slotNode(28, 28),
+ node: slot(28, 28),
background: { color: c.control },
interactionStates: controlStates(c),
check: { node: { fill: true, marginLeft: px(6), marginTop: px(6),
@@ -118,55 +94,47 @@ export const buildSystem = defineSystem(
isOn: true,
onChange: (isOn) => { state.paused = !isOn; },
});
- }
+ });
- // Slider: 0..100 volume; drag handled in controls.ts.
- {
- const { row, label } = makeRow(world, panel, c, 'Volume 60%');
- state.volumeLabel = label;
+ withRow(world, 'VolumeRow', (row) => {
+ const label = world.findEntityByName('VolumeLabel');
const slider = createSlider({
world, parent: row,
- node: slotNode(SLIDER_W, SLIDER_H),
+ node: slot(SLIDER_W, SLIDER_H),
min: 0, max: 100, step: 1, value: 60, handleWidth: 14,
- onChange: (v) => setText(world, label, `Volume ${Math.round(v)}%`),
+ onChange: (v) => { if (label !== null) setText(world, label, `Volume ${Math.round(v)}%`); },
});
- // createSlider ships no input — make the track hit-testable for controls.ts.
+ // createSlider ships no input; make the track hit-testable for controls.ts.
world.insert(slider.trackEntity, Interactable,
{ enabled: true, blockRaycast: true, raycastTarget: true });
world.insert(slider.trackEntity, UIInteraction,
{ hovered: false, pressed: false, justPressed: false, justReleased: false });
state.slider = slider;
- }
+ });
- // Progress: auto-animated in controls.ts.
- {
- const { row } = makeRow(world, panel, c, 'Loading');
+ withRow(world, 'LoadingRow', (row) => {
state.progress = createProgress({
world, parent: row,
- node: slotNode(SLIDER_W, PROGRESS_H),
+ node: slot(SLIDER_W, PROGRESS_H),
fill: { color: ACCENTS[0]!.color },
value: 0,
});
- }
+ });
- // Dialog opener.
- {
- const { row } = makeRow(world, panel, c, 'Modal');
+ withRow(world, 'ModalRow', (row) => {
createButton({
world, events, parent: row,
- node: slotNode(140, CONTROL_H),
+ node: slot(140, CONTROL_H),
states: controlStates(c),
text: { content: 'Open…', color: c.onPrimary, fontSize: 14 },
- onClick: () => dialog.open(),
+ onClick: openDialog,
});
- }
+ });
- // Dropdown: re-tints the fills. Last row so its popup opens below the panel.
- {
- const { row } = makeRow(world, panel, c, 'Accent');
+ withRow(world, 'AccentRow', (row) => {
createDropdown<Accent>({
world, events, parent: row,
- node: slotNode(150, CONTROL_H),
+ node: slot(150, CONTROL_H),
options: ACCENTS,
optionToLabel: (a) => a.name,
optionHeight: 30,
@@ -175,35 +143,18 @@ export const buildSystem = defineSystem(
if (state.progress) setColor(world, state.progress.fillEntity, accent.color);
},
});
- }
+ });
},
{ name: 'BuildSystem' },
);
-// helpers
-
-interface RowRefs { row: Entity; label: Entity; }
-
-// A row: fixed-height flex item; label pinned left, widget slot pinned right.
-function makeRow(world: World, panel: Entity, c: ThemeColors, labelText: string): RowRefs {
- const row = spawnUIEntity({ world, parent: panel, node: { height: px(ROW_H) } });
- const label = spawnUIEntity({
- world, parent: row,
- node: { position: UIPositionType.Absolute, insetLeft: px(0), insetTop: px(0),
- insetBottom: px(0), width: px(LABEL_W) },
- text: { content: labelText, fontSize: 14, color: c.onPrimary,
- align: TextAlign.Left, verticalAlign: TextVerticalAlign.Middle },
- });
- return { row, label };
+function withRow(world: World, name: string, fill: (row: Entity) => void): void {
+ const row = world.findEntityByName(name);
+ if (row !== null) fill(row);
}
-// Widget slot: fixed w×h, pinned to the row's right edge and vertically centred.
-function slotNode(w: number, h: number) {
- return {
- position: UIPositionType.Absolute,
- insetRight: px(0), insetTop: px((ROW_H - h) / 2),
- width: px(w), height: px(h),
- };
+function slot(w: number, h: number) {
+ return { width: px(w), height: px(h) };
}
function controlStates(c: ThemeColors): Record<string, { color: Color }> {
diff --git a/examples/ui-controls/src/systems/controls.ts b/examples/ui-controls/src/systems/controls.ts
index 7a5437af0..696483d6d 100644
--- a/examples/ui-controls/src/systems/controls.ts
+++ b/examples/ui-controls/src/systems/controls.ts
@@ -7,8 +7,6 @@ import type { TransformData, UIInteractionData } from 'esengine';
import { SLIDER_W, PROGRESS_SPEED } from '../config';
import { state } from '../state';
-// Per-frame wiring the factories don't self-drive: drag the slider (mapping the
-// pointer's world x onto the track) and animate the progress bar (pausable).
export const controlsSystem = defineSystem(
[Res(Time), Res(Input), Res(UICameraInfo), GetWorld()],
(time, input, camera, world) => {