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): rebuild on the imperative widget API + theme tokens

yhhbf50fa249544
diff --git a/examples/ui-controls/assets/scenes/main.esscene b/examples/ui-controls/assets/scenes/main.esscene
index b8efe5758..ff7cb1d74 100644
--- a/examples/ui-controls/assets/scenes/main.esscene
+++ b/examples/ui-controls/assets/scenes/main.esscene
@@ -34,22 +34,7 @@
"id": 1,
"name": "Canvas",
"parent": null,
- "children": [
- 2,
- 3,
- 5,
- 7,
- 9,
- 10,
- 11,
- 12,
- 13,
- 14,
- 15,
- 18,
- 21,
- 24
- ],
+ "children": [],
"components": [
{
"type": "Transform",
@@ -71,1296 +56,6 @@
}
],
"visible": true
- },
- {
- "id": 2,
- "name": "Title",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 400.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -200.0,
- "unit": 0
- },
- "height": {
- "value": 50.0,
- "unit": 0
- },
- "insetTop": {
- "value": 0.0,
- "unit": 1
- },
- "marginTop": {
- "value": 50.0,
- "unit": 0
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "UI Controls Gallery",
- "fontSize": 32,
- "color": {
- "r": 1,
- "g": 1,
- "b": 1,
- "a": 1
- },
- "align": 1,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 3,
- "name": "PrimaryBtn",
- "parent": 1,
- "children": [
- 4
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 140.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -340.0,
- "unit": 0
- },
- "height": {
- "value": 45.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -122.5,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.6,
- "b": 1,
- "a": 1
- }
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 4,
- "name": "PrimaryLabel",
- "parent": 3,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "insetRight": {
- "value": 0.0,
- "unit": 1
- },
- "insetBottom": {
- "value": 0.0,
- "unit": 1
- },
- "insetTop": {
- "value": 0.0,
- "unit": 1
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Primary",
- "fontSize": 20,
- "color": {
- "r": 1,
- "g": 1,
- "b": 1,
- "a": 1
- },
- "align": 1,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 5,
- "name": "SuccessBtn",
- "parent": 1,
- "children": [
- 6
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 140.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -140.0,
- "unit": 0
- },
- "height": {
- "value": 45.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -122.5,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.8,
- "b": 0.4,
- "a": 1
- }
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 6,
- "name": "SuccessLabel",
- "parent": 5,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "insetRight": {
- "value": 0.0,
- "unit": 1
- },
- "insetBottom": {
- "value": 0.0,
- "unit": 1
- },
- "insetTop": {
- "value": 0.0,
- "unit": 1
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Success",
- "fontSize": 20,
- "color": {
- "r": 1,
- "g": 1,
- "b": 1,
- "a": 1
- },
- "align": 1,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 7,
- "name": "DangerBtn",
- "parent": 1,
- "children": [
- 8
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 140.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": 60.0,
- "unit": 0
- },
- "height": {
- "value": 45.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -122.5,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.9,
- "g": 0.3,
- "b": 0.3,
- "a": 1
- }
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 8,
- "name": "DangerLabel",
- "parent": 7,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "insetRight": {
- "value": 0.0,
- "unit": 1
- },
- "insetBottom": {
- "value": 0.0,
- "unit": 1
- },
- "insetTop": {
- "value": 0.0,
- "unit": 1
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Danger",
- "fontSize": 20,
- "color": {
- "r": 1,
- "g": 1,
- "b": 1,
- "a": 1
- },
- "align": 1,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 9,
- "name": "Toggle1",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 30.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -230.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1
- }
- },
- {
- "type": "Toggle",
- "data": {
- "isOn": true
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 10,
- "name": "Toggle1Label",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 100.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -175.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Option 1",
- "fontSize": 18,
- "color": {
- "r": 0.8,
- "g": 0.8,
- "b": 0.8,
- "a": 1
- },
- "align": 0,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 11,
- "name": "Toggle2",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 30.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -30.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1
- }
- },
- {
- "type": "Toggle",
- "data": {
- "isOn": false
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 12,
- "name": "Toggle2Label",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 100.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": 25.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Option 2",
- "fontSize": 18,
- "color": {
- "r": 0.8,
- "g": 0.8,
- "b": 0.8,
- "a": 1
- },
- "align": 0,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 13,
- "name": "Toggle3",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 30.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": 170.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1
- }
- },
- {
- "type": "Toggle",
- "data": {
- "isOn": false
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 14,
- "name": "Toggle3Label",
- "parent": 1,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 100.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": 225.0,
- "unit": 0
- },
- "height": {
- "value": 30.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -35.0,
- "unit": 0
- }
- }
- },
- {
- "type": "Text",
- "data": {
- "content": "Option 3",
- "fontSize": 18,
- "color": {
- "r": 0.8,
- "g": 0.8,
- "b": 0.8,
- "a": 1
- },
- "align": 0,
- "verticalAlign": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 15,
- "name": "Slider",
- "parent": 1,
- "children": [
- 16,
- 17
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 400.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -400.0,
- "unit": 0
- },
- "height": {
- "value": 8.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": 56.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.3,
- "g": 0.3,
- "b": 0.3,
- "a": 1
- }
- }
- },
- {
- "type": "Slider",
- "data": {
- "value": 0.5,
- "minValue": 0,
- "maxValue": 1,
- "direction": 0,
- "fillEntity": 16,
- "handleEntity": 17
- }
- },
- {
- "type": "Interactable",
- "data": {}
- }
- ],
- "visible": true
- },
- {
- "id": 16,
- "name": "SliderFill",
- "parent": 15,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 200.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "height": {
- "value": 8.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -4.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.6,
- "b": 1,
- "a": 1
- }
- }
- }
- ],
- "visible": true
- },
- {
- "id": 17,
- "name": "SliderHandle",
- "parent": 15,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 20.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -10.0,
- "unit": 0
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -10.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 1,
- "g": 1,
- "b": 1,
- "a": 1
- }
- }
- }
- ],
- "visible": true
- },
- {
- "id": 18,
- "name": "ProgressBar1",
- "parent": 1,
- "children": [
- 19
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 400.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -400.0,
- "unit": 0
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": 110.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.2,
- "b": 0.2,
- "a": 1
- }
- }
- },
- {
- "type": "ProgressBar",
- "data": {
- "value": 0.3,
- "fillEntity": 19,
- "direction": 0
- }
- },
- {
- "type": "ProgressAnimator",
- "data": {
- "speed": 0.2,
- "direction": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 19,
- "name": "ProgressFill1",
- "parent": 18,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 120.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -10.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.8,
- "b": 0.4,
- "a": 1
- }
- }
- }
- ],
- "visible": true
- },
- {
- "id": 21,
- "name": "ProgressBar2",
- "parent": 1,
- "children": [
- 22
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 400.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -400.0,
- "unit": 0
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": 150.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.2,
- "b": 0.2,
- "a": 1
- }
- }
- },
- {
- "type": "ProgressBar",
- "data": {
- "value": 0.55,
- "fillEntity": 22,
- "direction": 0
- }
- },
- {
- "type": "ProgressAnimator",
- "data": {
- "speed": 0.3,
- "direction": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 22,
- "name": "ProgressFill2",
- "parent": 21,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 220.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -10.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 1,
- "g": 0.7,
- "b": 0.1,
- "a": 1
- }
- }
- }
- ],
- "visible": true
- },
- {
- "id": 24,
- "name": "ProgressBar3",
- "parent": 1,
- "children": [
- 25
- ],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 400.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 50.0,
- "unit": 1
- },
- "marginLeft": {
- "value": -400.0,
- "unit": 0
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": 190.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.2,
- "g": 0.2,
- "b": 0.2,
- "a": 1
- }
- }
- },
- {
- "type": "ProgressBar",
- "data": {
- "value": 0.8,
- "fillEntity": 25,
- "direction": 0
- }
- },
- {
- "type": "ProgressAnimator",
- "data": {
- "speed": 0.4,
- "direction": 1
- }
- }
- ],
- "visible": true
- },
- {
- "id": 25,
- "name": "ProgressFill3",
- "parent": 24,
- "children": [],
- "components": [
- {
- "type": "Transform",
- "data": {}
- },
- {
- "type": "UINode",
- "data": {
- "position": 1,
- "width": {
- "value": 320.0,
- "unit": 0
- },
- "insetLeft": {
- "value": 0.0,
- "unit": 1
- },
- "height": {
- "value": 20.0,
- "unit": 0
- },
- "insetTop": {
- "value": 50.0,
- "unit": 1
- },
- "marginTop": {
- "value": -10.0,
- "unit": 0
- }
- }
- },
- {
- "type": "UIVisual",
- "data": {
- "visualType": 1,
- "color": {
- "r": 0.9,
- "g": 0.3,
- "b": 0.3,
- "a": 1
- }
- }
- }
- ],
- "visible": true
}
]
}
diff --git a/examples/ui-controls/src/components.ts b/examples/ui-controls/src/components.ts
deleted file mode 100644
index 307361055..000000000
--- a/examples/ui-controls/src/components.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { defineComponent, defineTag } from 'esengine';
-
-export const ProgressAnimator = defineComponent('ProgressAnimator', {
- speed: 0.3,
- direction: 1,
-});
-
-export const SliderLabel = defineTag('SliderLabel');
-export const ToggleLabel = defineTag('ToggleLabel');
diff --git a/examples/ui-controls/src/config.ts b/examples/ui-controls/src/config.ts
new file mode 100644
index 000000000..2b5e8293e
--- /dev/null
+++ b/examples/ui-controls/src/config.ts
@@ -0,0 +1,38 @@
+import type { Color } from 'esengine';
+
+// Panel + row geometry. The panel is a fixed box centred on the canvas (the
+// dialog-widget centring trick: 50% inset shifted back by half its size), laid
+// out internally with a flex column. Rows are fixed-height flex items; inside a
+// row the label and the widget slot are placed 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;
+export const SLIDER_H = 18;
+export const PROGRESS_H = 14;
+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.
+export interface Accent {
+ name: string;
+ color: Color;
+}
+
+export const ACCENTS: Accent[] = [
+ { name: 'Azure', color: { r: 0.25, g: 0.56, b: 0.96, a: 1 } },
+ { name: 'Emerald', color: { r: 0.20, g: 0.78, b: 0.52, a: 1 } },
+ { name: 'Amber', color: { r: 0.98, g: 0.72, b: 0.22, a: 1 } },
+ { name: 'Rose', color: { r: 0.96, g: 0.36, b: 0.52, a: 1 } },
+];
diff --git a/examples/ui-controls/src/main.ts b/examples/ui-controls/src/main.ts
index e2d4123c7..bb691a5d9 100644
--- a/examples/ui-controls/src/main.ts
+++ b/examples/ui-controls/src/main.ts
@@ -1,5 +1,21 @@
-// The progress bars in this scene are declarative (defined in the .esscene).
-// The old per-frame ProgressBar-component animation was removed: the SDK no
-// longer exposes a queryable ProgressBar component — progress is now an
-// imperative widget (createProgress -> ProgressHandle).
-import './components';
+// UI Controls — a gallery of the SDK's imperative UI widget factories, built in
+// code and styled entirely from the design-token theme (no literal RGBA):
+//
+// • Button — increments a click counter
+// • Toggle — pauses / resumes the progress animation
+// • Slider — 0..100 volume, drag the track (wired in systems/controls.ts)
+// • Progress — auto-animating ping-pong bar
+// • Dropdown — re-tints the slider + progress fills (a live theme accent)
+// • Dialog — a modal opened by a button
+//
+// The scene carries only a Camera + Canvas; everything else is spawned by the
+// startup buildSystem via createButton/createSlider/… + themeColors(). This is
+// the modern, ECS-native path — widgets are factory functions that compose the
+// same primitives you'd otherwise author in a scene.
+import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
+
+import { buildSystem } from './systems/build';
+import { controlsSystem } from './systems/controls';
+
+addStartupSystem(buildSystem);
+addSystemToSchedule(Schedule.Update, controlsSystem);
diff --git a/examples/ui-controls/src/state.ts b/examples/ui-controls/src/state.ts
new file mode 100644
index 000000000..bd72cfe31
--- /dev/null
+++ b/examples/ui-controls/src/state.ts
@@ -0,0 +1,20 @@
+import type { Entity, SliderHandle, ProgressHandle } from 'esengine';
+
+// Handles the build system hands to the per-frame controls system. Widget
+// callbacks (button/toggle/dropdown/dialog) are self-wired at build time and
+// need nothing here; only the slider (pointer drag) and the progress bar
+// (time-driven animation) are ticked each frame.
+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
new file mode 100644
index 000000000..554ac9ed8
--- /dev/null
+++ b/examples/ui-controls/src/systems/build.ts
@@ -0,0 +1,238 @@
+import {
+ defineSystem, Query, Res, GetWorld,
+ Canvas, UIEvents,
+ Text, UIVisual, FlexContainer,
+ Interactable, UIInteraction,
+ spawnUIEntity,
+ createButton, createToggle, createSlider, createProgress, createDropdown, createDialog,
+ themeColors, px, percent,
+ UIPositionType, FlexDirection, JustifyContent, AlignItems, TextAlign, 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 { state } from '../state';
+
+// One startup system builds the whole screen imperatively from the widget
+// factories (createButton/…/createDialog), styled entirely from the design
+// tokens (themeColors) — no literal RGBA. Each widget wires its own interaction;
+// only the slider (pointer) and progress bar (time) are ticked per-frame by
+// systems/controls.ts.
+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
+
+ let canvas: Entity | null = null;
+ for (const [entity] of canvases) { canvas = entity; break; }
+ if (canvas === null) return;
+
+ const c = themeColors();
+
+ // Centered panel (dialog-centring trick), 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: an overlay on the canvas, hidden until "Open…". Populated
+ // with its own title/body/Close children.
+ const dialog = createDialog({
+ world, parent: canvas, startHidden: true,
+ panelNode: {
+ position: UIPositionType.Absolute,
+ width: px(360), height: px(190),
+ insetLeft: percent(50), insetTop: percent(50),
+ marginLeft: px(-180), marginTop: px(-95),
+ },
+ 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(),
+ });
+
+ // ── Button — increments a click counter shown in the row label. ───────
+ {
+ const { row, label } = makeRow(world, panel, c, 'Clicks: 0');
+ let clicks = 0;
+ createButton({
+ world, events, parent: row,
+ node: slotNode(140, CONTROL_H),
+ states: primaryStates(c),
+ text: { content: 'Click me', color: c.onPrimary, fontSize: 14 },
+ onClick: () => { clicks += 1; setText(world, label, `Clicks: ${clicks}`); },
+ });
+ }
+
+ // ── Toggle — pauses / resumes the progress animation. ─────────────────
+ {
+ const { row } = makeRow(world, panel, c, 'Animate');
+ createToggle({
+ world, events, parent: row,
+ node: slotNode(28, 28),
+ background: { color: c.control },
+ interactionStates: controlStates(c),
+ check: { node: { fill: true, marginLeft: px(6), marginTop: px(6),
+ marginRight: px(6), marginBottom: px(6) }, color: c.primary },
+ isOn: true,
+ onChange: (isOn) => { state.paused = !isOn; },
+ });
+ }
+
+ // ── Slider — 0..100 volume, live in the row label; dragged in controls. ─
+ {
+ const { row, label } = makeRow(world, panel, c, 'Volume 60%');
+ state.volumeLabel = label;
+ const slider = createSlider({
+ world, parent: row,
+ node: slotNode(SLIDER_W, SLIDER_H),
+ min: 0, max: 100, step: 1, value: 60, handleWidth: 14,
+ onChange: (v) => setText(world, label, `Volume ${Math.round(v)}%`),
+ });
+ // createSlider ships no input; make the track hit-testable so the
+ // controls system can read hover + drag it.
+ 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-animates (ping-pong) in the controls system. ──────
+ {
+ const { row } = makeRow(world, panel, c, 'Loading');
+ state.progress = createProgress({
+ world, parent: row,
+ node: slotNode(SLIDER_W, PROGRESS_H),
+ fill: { color: ACCENTS[0]!.color },
+ value: 0,
+ });
+ }
+
+ // ── Dialog opener. ────────────────────────────────────────────────────
+ {
+ const { row } = makeRow(world, panel, c, 'Modal');
+ createButton({
+ world, events, parent: row,
+ node: slotNode(140, CONTROL_H),
+ states: controlStates(c),
+ text: { content: 'Open…', color: c.onPrimary, fontSize: 14 },
+ onClick: () => dialog.open(),
+ });
+ }
+
+ // ── Dropdown — re-tints the slider + progress fills. Last row so its
+ // popup opens into the space below the panel. ─────────────────────
+ {
+ const { row } = makeRow(world, panel, c, 'Accent');
+ createDropdown<Accent>({
+ world, events, parent: row,
+ node: slotNode(150, CONTROL_H),
+ options: ACCENTS,
+ optionToLabel: (a) => a.name,
+ optionHeight: 30,
+ onSelect: (_i, accent) => {
+ if (state.slider) setColor(world, state.slider.fillEntity, accent.color);
+ if (state.progress) setColor(world, state.progress.fillEntity, accent.color);
+ },
+ });
+ }
+ },
+ { name: 'BuildSystem' },
+);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+interface RowRefs { row: Entity; label: Entity; }
+
+// A row is a fixed-height flex item (its width stretches to the panel content
+// box); inside it the descriptor label sits at the left and the widget slot is
+// pinned to the right by absolute insets.
+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 };
+}
+
+// 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 controlStates(c: ThemeColors): Record<string, { color: Color }> {
+ return { normal: { color: c.control }, hover: { color: c.controlHover }, pressed: { color: c.controlActive } };
+}
+
+function primaryStates(c: ThemeColors): Record<string, { color: Color }> {
+ return { normal: { color: c.primary }, hover: { color: c.primaryHover }, pressed: { color: c.primaryActive } };
+}
+
+function setText(world: World, entity: Entity, content: string): void {
+ if (!world.valid(entity) || !world.has(entity, Text)) return;
+ const t = world.get(entity, Text) as TextData;
+ t.content = content;
+ world.insert(entity, Text, t);
+}
+
+function setColor(world: World, entity: Entity, color: Color): void {
+ if (!world.valid(entity) || !world.has(entity, UIVisual)) return;
+ const v = world.get(entity, UIVisual) as UIVisualData;
+ v.color = { ...color };
+ world.insert(entity, UIVisual, v);
+}
diff --git a/examples/ui-controls/src/systems/controls.ts b/examples/ui-controls/src/systems/controls.ts
new file mode 100644
index 000000000..1785a49bf
--- /dev/null
+++ b/examples/ui-controls/src/systems/controls.ts
@@ -0,0 +1,42 @@
+import {
+ defineSystem, Res, GetWorld,
+ Time, Input, UICameraInfo, Transform, UIInteraction,
+} from 'esengine';
+import type { TransformData, UIInteractionData } from 'esengine';
+
+import { SLIDER_W, PROGRESS_SPEED } from '../config';
+import { state } from '../state';
+
+// Per-frame wiring for the two widgets the factories don't self-drive:
+// • Slider — createSlider ships no input, so we drag it here. The engine's
+// hit-test already sets UIInteraction.hovered on the track; we only map the
+// pointer's world x (same space as the track's laid-out worldPosition) back
+// to a 0..100 value.
+// • Progress — a simple time-driven ping-pong, pausable via the toggle.
+export const controlsSystem = defineSystem(
+ [Res(Time), Res(Input), Res(UICameraInfo), GetWorld()],
+ (time, input, camera, world) => {
+ const slider = state.slider;
+ if (slider && camera.valid && world.valid(slider.trackEntity)) {
+ const inter = world.get(slider.trackEntity, UIInteraction) as UIInteractionData;
+ if (input.isMouseButtonPressed(0) && inter.hovered) state.dragging = true;
+ if (!input.isMouseButtonDown(0)) state.dragging = false;
+
+ if (state.dragging) {
+ const wt = world.get(slider.trackEntity, Transform) as TransformData;
+ const width = SLIDER_W * wt.worldScale.x; // px == world units, times canvas scale
+ const left = wt.worldPosition.x - width / 2;
+ slider.setValue(slider.valueAtLocalX(camera.worldMouseX - left, width));
+ }
+ }
+
+ const progress = state.progress;
+ if (progress && !state.paused) {
+ state.progressT += time.delta * PROGRESS_SPEED * state.progressDir;
+ if (state.progressT >= 1) { state.progressT = 1; state.progressDir = -1; }
+ else if (state.progressT <= 0) { state.progressT = 0; state.progressDir = 1; }
+ progress.setValue(state.progressT);
+ }
+ },
+ { name: 'ControlsSystem' },
+);