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
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.essceneindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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) => {