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
feat(ui): ListView editor prefab + UIMask clipping render verification
esengine67aa0bac7522
diff --git a/desktop/package.json b/desktop/package.jsonindex 00c232497..0d9e20ef3 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -29,6 +29,7 @@"verify:render:text": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-sdf.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs","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: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-list-mask.esscene b/desktop/public/scenes/ui-list-mask.esscenenew file mode 100644index 000000000..d18d75faf--- /dev/null+++ b/desktop/public/scenes/ui-list-mask.esscene@@ -0,0 +1,92 @@+{+ "version": "1.0",+ "name": "UIMask (Scissor) clips overflowing content to the viewport — the primitive createListView relies on",+ "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, 3],+ "components": [+ { "type": "Transform", "data": {} },+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },+ { "type": "UINode", "data": {} }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "Background",+ "parent": 1,+ "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": 1, "color": { "r": 0, "g": 0, "b": 1, "a": 1 }, "enabled": true } }+ ],+ "visible": true+ },+ {+ "id": 3,+ "name": "Viewport",+ "parent": 1,+ "children": [4],+ "components": [+ { "type": "Transform", "data": {} },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "insetLeft": { "value": 200, "unit": 0 },+ "insetTop": { "value": 200, "unit": 0 },+ "width": { "value": 400, "unit": 0 },+ "height": { "value": 200, "unit": 0 }+ }+ },+ { "type": "UIMask", "data": { "enabled": true, "mode": 0, "maskTexture": 0, "inverted": false } }+ ],+ "visible": true+ },+ {+ "id": 4,+ "name": "Item",+ "parent": 3,+ "children": [],+ "components": [+ { "type": "Transform", "data": {} },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "insetLeft": { "value": 0, "unit": 0 },+ "insetTop": { "value": 0, "unit": 0 },+ "width": { "value": 600, "unit": 0 },+ "height": { "value": 400, "unit": 0 }+ }+ },+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 1, "g": 0, "b": 0, "a": 1 }, "enabled": true } }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/ui-list-mask.textures.json b/desktop/public/scenes/ui-list-mask.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/ui-list-mask.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/src/ui/widgets/prefabs/ListView.esprefab b/sdk/src/ui/widgets/prefabs/ListView.esprefabnew file mode 100644index 000000000..8c38ee176--- /dev/null+++ b/sdk/src/ui/widgets/prefabs/ListView.esprefab@@ -0,0 +1,339 @@+{+ "version": "2",+ "name": "ListView",+ "rootEntityId": "0",+ "entities": [+ {+ "prefabEntityId": "0",+ "name": "ListView",+ "parent": null,+ "children": [+ "1"+ ],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1,+ "y": 1,+ "z": 1+ },+ "worldPosition": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldRotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldScale": {+ "x": 1,+ "y": 1,+ "z": 1+ }+ }+ },+ {+ "type": "UINode",+ "data": {+ "position": 0,+ "width": {+ "value": 240,+ "unit": 0+ },+ "height": {+ "value": 320,+ "unit": 0+ },+ "minWidth": {+ "value": 0,+ "unit": 2+ },+ "minHeight": {+ "value": 0,+ "unit": 2+ },+ "maxWidth": {+ "value": 0,+ "unit": 2+ },+ "maxHeight": {+ "value": 0,+ "unit": 2+ },+ "flexGrow": 0,+ "flexShrink": 1,+ "flexBasis": {+ "value": 0,+ "unit": 2+ },+ "alignSelf": 0,+ "marginLeft": {+ "value": 0,+ "unit": 0+ },+ "marginTop": {+ "value": 0,+ "unit": 0+ },+ "marginRight": {+ "value": 0,+ "unit": 0+ },+ "marginBottom": {+ "value": 0,+ "unit": 0+ },+ "insetLeft": {+ "value": 0,+ "unit": 2+ },+ "insetTop": {+ "value": 0,+ "unit": 2+ },+ "insetRight": {+ "value": 0,+ "unit": 2+ },+ "insetBottom": {+ "value": 0,+ "unit": 2+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "visualType": 1,+ "texture": 0,+ "color": {+ "r": 0.22,+ "g": 0.22,+ "b": 0.26,+ "a": 1+ },+ "uvOffset": {+ "x": 0,+ "y": 0+ },+ "uvScale": {+ "x": 1,+ "y": 1+ },+ "sliceBorder": {+ "x": 0,+ "y": 0,+ "z": 0,+ "w": 0+ },+ "tileSize": {+ "x": 32,+ "y": 32+ },+ "fillMethod": 0,+ "fillOrigin": 0,+ "fillAmount": 1,+ "material": 0,+ "enabled": true+ }+ },+ {+ "type": "UIMask",+ "data": {+ "enabled": true,+ "mode": 0,+ "maskTexture": 0,+ "inverted": false+ }+ },+ {+ "type": "Interactable",+ "data": {+ "enabled": true,+ "blockRaycast": true,+ "raycastTarget": true+ }+ },+ {+ "type": "UIInteraction",+ "data": {+ "hovered": false,+ "pressed": false,+ "justPressed": false,+ "justReleased": false+ }+ }+ ],+ "visible": true+ },+ {+ "prefabEntityId": "1",+ "name": "Label",+ "parent": "0",+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1,+ "y": 1,+ "z": 1+ },+ "worldPosition": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldRotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldScale": {+ "x": 1,+ "y": 1,+ "z": 1+ }+ }+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 0,+ "unit": 2+ },+ "height": {+ "value": 0,+ "unit": 2+ },+ "minWidth": {+ "value": 0,+ "unit": 2+ },+ "minHeight": {+ "value": 0,+ "unit": 2+ },+ "maxWidth": {+ "value": 0,+ "unit": 2+ },+ "maxHeight": {+ "value": 0,+ "unit": 2+ },+ "flexGrow": 0,+ "flexShrink": 1,+ "flexBasis": {+ "value": 0,+ "unit": 2+ },+ "alignSelf": 0,+ "marginLeft": {+ "value": 0,+ "unit": 0+ },+ "marginTop": {+ "value": 0,+ "unit": 0+ },+ "marginRight": {+ "value": 0,+ "unit": 0+ },+ "marginBottom": {+ "value": 0,+ "unit": 0+ },+ "insetLeft": {+ "value": 0,+ "unit": 0+ },+ "insetTop": {+ "value": 0,+ "unit": 0+ },+ "insetRight": {+ "value": 0,+ "unit": 0+ },+ "insetBottom": {+ "value": 0,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "List View",+ "fontFamily": "Arial",+ "fontSize": 14,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "align": 1,+ "verticalAlign": 1,+ "wordWrap": false,+ "overflow": 0,+ "lineHeight": 1.2,+ "bold": false,+ "italic": false,+ "strokeColor": {+ "r": 0,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "strokeWidth": 0,+ "shadowColor": {+ "r": 0,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "shadowBlur": 0,+ "shadowOffsetX": 0,+ "shadowOffsetY": 0,+ "richText": false+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/sdk/src/ui/widgets/prefabs/generated.ts b/sdk/src/ui/widgets/prefabs/generated.tsindex cd792b452..87d611bcf 100644--- a/sdk/src/ui/widgets/prefabs/generated.ts+++ b/sdk/src/ui/widgets/prefabs/generated.ts@@ -1895,7 +1895,346 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {"visible": true}]+ },+ "ListView": {+ "version": "2",+ "name": "ListView",+ "rootEntityId": "0",+ "entities": [+ {+ "prefabEntityId": "0",+ "name": "ListView",+ "parent": null,+ "children": [+ "1"+ ],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1,+ "y": 1,+ "z": 1+ },+ "worldPosition": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldRotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldScale": {+ "x": 1,+ "y": 1,+ "z": 1+ }+ }+ },+ {+ "type": "UINode",+ "data": {+ "position": 0,+ "width": {+ "value": 240,+ "unit": 0+ },+ "height": {+ "value": 320,+ "unit": 0+ },+ "minWidth": {+ "value": 0,+ "unit": 2+ },+ "minHeight": {+ "value": 0,+ "unit": 2+ },+ "maxWidth": {+ "value": 0,+ "unit": 2+ },+ "maxHeight": {+ "value": 0,+ "unit": 2+ },+ "flexGrow": 0,+ "flexShrink": 1,+ "flexBasis": {+ "value": 0,+ "unit": 2+ },+ "alignSelf": 0,+ "marginLeft": {+ "value": 0,+ "unit": 0+ },+ "marginTop": {+ "value": 0,+ "unit": 0+ },+ "marginRight": {+ "value": 0,+ "unit": 0+ },+ "marginBottom": {+ "value": 0,+ "unit": 0+ },+ "insetLeft": {+ "value": 0,+ "unit": 2+ },+ "insetTop": {+ "value": 0,+ "unit": 2+ },+ "insetRight": {+ "value": 0,+ "unit": 2+ },+ "insetBottom": {+ "value": 0,+ "unit": 2+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "visualType": 1,+ "texture": 0,+ "color": {+ "r": 0.22,+ "g": 0.22,+ "b": 0.26,+ "a": 1+ },+ "uvOffset": {+ "x": 0,+ "y": 0+ },+ "uvScale": {+ "x": 1,+ "y": 1+ },+ "sliceBorder": {+ "x": 0,+ "y": 0,+ "z": 0,+ "w": 0+ },+ "tileSize": {+ "x": 32,+ "y": 32+ },+ "fillMethod": 0,+ "fillOrigin": 0,+ "fillAmount": 1,+ "material": 0,+ "enabled": true+ }+ },+ {+ "type": "UIMask",+ "data": {+ "enabled": true,+ "mode": 0,+ "maskTexture": 0,+ "inverted": false+ }+ },+ {+ "type": "Interactable",+ "data": {+ "enabled": true,+ "blockRaycast": true,+ "raycastTarget": true+ }+ },+ {+ "type": "UIInteraction",+ "data": {+ "hovered": false,+ "pressed": false,+ "justPressed": false,+ "justReleased": false+ }+ }+ ],+ "visible": true+ },+ {+ "prefabEntityId": "1",+ "name": "Label",+ "parent": "0",+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 1,+ "y": 1,+ "z": 1+ },+ "worldPosition": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldRotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ },+ "worldScale": {+ "x": 1,+ "y": 1,+ "z": 1+ }+ }+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 0,+ "unit": 2+ },+ "height": {+ "value": 0,+ "unit": 2+ },+ "minWidth": {+ "value": 0,+ "unit": 2+ },+ "minHeight": {+ "value": 0,+ "unit": 2+ },+ "maxWidth": {+ "value": 0,+ "unit": 2+ },+ "maxHeight": {+ "value": 0,+ "unit": 2+ },+ "flexGrow": 0,+ "flexShrink": 1,+ "flexBasis": {+ "value": 0,+ "unit": 2+ },+ "alignSelf": 0,+ "marginLeft": {+ "value": 0,+ "unit": 0+ },+ "marginTop": {+ "value": 0,+ "unit": 0+ },+ "marginRight": {+ "value": 0,+ "unit": 0+ },+ "marginBottom": {+ "value": 0,+ "unit": 0+ },+ "insetLeft": {+ "value": 0,+ "unit": 0+ },+ "insetTop": {+ "value": 0,+ "unit": 0+ },+ "insetRight": {+ "value": 0,+ "unit": 0+ },+ "insetBottom": {+ "value": 0,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "List View",+ "fontFamily": "Arial",+ "fontSize": 14,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "align": 1,+ "verticalAlign": 1,+ "wordWrap": false,+ "overflow": 0,+ "lineHeight": 1.2,+ "bold": false,+ "italic": false,+ "strokeColor": {+ "r": 0,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "strokeWidth": 0,+ "shadowColor": {+ "r": 0,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "shadowBlur": 0,+ "shadowOffsetX": 0,+ "shadowOffsetY": 0,+ "richText": false+ }+ }+ ],+ "visible": true+ }+ ]}};-export const BUILTIN_UI_WIDGET_NAMES = ["Button","Toggle","Slider","Progress","Dropdown"] as const;+export const BUILTIN_UI_WIDGET_NAMES = ["Button","Toggle","Slider","Progress","Dropdown","ListView"] as const;diff --git a/sdk/tests/ui-widget-prefabs.gen.test.ts b/sdk/tests/ui-widget-prefabs.gen.test.tsindex 54145f67a..c08009045 100644--- a/sdk/tests/ui-widget-prefabs.gen.test.ts+++ b/sdk/tests/ui-widget-prefabs.gen.test.ts@@ -12,6 +12,9 @@ import { createToggle } from '../src/ui/widgets/toggle';import { createSlider } from '../src/ui/widgets/slider';import { createProgress } from '../src/ui/widgets/progress';import { createDropdown } from '../src/ui/widgets/dropdown';+import { spawnUIEntity } from '../src/ui/widgets/helpers';+import { UIMask, MaskMode } from '../src/ui/core/ui-mask';+import { Interactable, UIInteraction } from '../src/ui/input/interactable';import { themeColors } from '../src/ui/theme/tokens';import { px } from '../src/ui/core/dimension';@@ -120,4 +123,30 @@ describe('UI widget prefab codegen', () => {);expect(typesOf(prefab, prefab.rootEntityId)).toEqual(expect.arrayContaining(['UINode', 'Interactable']));});++ it('ListView: a clipped viewport shell (items are populated by createListView in code)', () => {+ const prefab = generate('ListView', (world) => {+ // The serializable half of createListView: a sized viewport with a+ // Scissor mask + a hover hit-target, plus a placeholder label. Data and+ // item rows are runtime-only — wire them with createListView in code.+ const viewport = spawnUIEntity({+ world,+ node: { width: px(240), height: px(320) },+ visual: { color: c.control },+ });+ world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor, maskTexture: 0, inverted: false });+ world.insert(viewport, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });+ world.insert(viewport, UIInteraction, { hovered: false, pressed: false, justPressed: false, justReleased: false });+ spawnUIEntity({+ world, parent: viewport,+ node: { fill: true },+ text: { content: 'List View', color: c.onPrimary, fontSize: 14 },+ });+ return viewport as unknown as number;+ });+ expect(typesOf(prefab, prefab.rootEntityId)).toEqual(expect.arrayContaining([+ 'UINode', 'UIVisual', 'UIMask', 'Interactable',+ ]));+ expect(entityById(prefab, prefab.rootEntityId).children.length).toBe(1);+ });});