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): ScrollView joins the widget palette

yhha243106c1332
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index e81640b70..d4e31d5cc 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -11,7 +11,7 @@
* UI. (REARCH_ENTITY_CREATION E2.)
*/
import type { LucideIcon } from 'lucide-react';
-import { CircleDot, LayoutPanelTop, ToggleLeft, SlidersHorizontal, List, ChevronDown, SquareMousePointer, RectangleHorizontal, Box, Type, Image as ImageIcon, SquareDashed } from 'lucide-react';
+import { CircleDot, LayoutPanelTop, ToggleLeft, SlidersHorizontal, List, ChevronDown, SquareMousePointer, RectangleHorizontal, Box, Type, Image as ImageIcon, SquareDashed, ScrollText } from 'lucide-react';
import { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES, PREFAB_FORMAT_VERSION, getUserComponents, type PrefabData } from 'esengine';
import type { EntityId } from '@/types';
import { componentByName, componentDefaults, prettyLabel, componentCategory } from './schema';
@@ -164,6 +164,7 @@ const UI_WIDGET_ICON: Record<string, LucideIcon> = {
Progress: RectangleHorizontal,
Dropdown: ChevronDown,
ListView: List,
+ ScrollView: ScrollText,
};
// UI primitives — the raw building blocks the widget prefabs are composed from: a
diff --git a/sdk/src/ui/widgets/prefabs/ScrollView.esprefab b/sdk/src/ui/widgets/prefabs/ScrollView.esprefab
new file mode 100644
index 000000000..6803a68ea
--- /dev/null
+++ b/sdk/src/ui/widgets/prefabs/ScrollView.esprefab
@@ -0,0 +1,298 @@
+{
+ "version": "2",
+ "name": "ScrollView",
+ "rootEntityId": "0",
+ "entities": [
+ {
+ "prefabEntityId": "0",
+ "name": "ScrollView",
+ "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,
+ "display": 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": "ThemeStyle",
+ "data": {
+ "visual": "control"
+ }
+ },
+ {
+ "type": "UIMask",
+ "data": {
+ "enabled": true,
+ "mode": 0
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "prefabEntityId": "1",
+ "name": "Node",
+ "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,
+ "display": 0,
+ "width": {
+ "value": 240,
+ "unit": 0
+ },
+ "height": {
+ "value": 640,
+ "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": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 2
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 2
+ }
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/sdk/src/ui/widgets/prefabs/generated.ts b/sdk/src/ui/widgets/prefabs/generated.ts
index 5e3055868..601377e08 100644
--- a/sdk/src/ui/widgets/prefabs/generated.ts
+++ b/sdk/src/ui/widgets/prefabs/generated.ts
@@ -2951,7 +2951,305 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"visible": true
}
]
+ },
+ "ScrollView": {
+ "version": "2",
+ "name": "ScrollView",
+ "rootEntityId": "0",
+ "entities": [
+ {
+ "prefabEntityId": "0",
+ "name": "ScrollView",
+ "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,
+ "display": 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": "ThemeStyle",
+ "data": {
+ "visual": "control"
+ }
+ },
+ {
+ "type": "UIMask",
+ "data": {
+ "enabled": true,
+ "mode": 0
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "prefabEntityId": "1",
+ "name": "Node",
+ "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,
+ "display": 0,
+ "width": {
+ "value": 240,
+ "unit": 0
+ },
+ "height": {
+ "value": 640,
+ "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": 0
+ },
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 2
+ },
+ "insetBottom": {
+ "value": 0,
+ "unit": 2
+ }
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
}
};
-export const BUILTIN_UI_WIDGET_NAMES = ["Button","Toggle","Slider","Dialog","TextInput","Progress","Dropdown","ListView"] as const;
+export const BUILTIN_UI_WIDGET_NAMES = ["Button","Toggle","Slider","Dialog","TextInput","Progress","Dropdown","ListView","ScrollView"] as const;
diff --git a/sdk/tests/ui-widget-prefabs.gen.test.ts b/sdk/tests/ui-widget-prefabs.gen.test.ts
index 6826f88d8..a42f0db32 100644
--- a/sdk/tests/ui-widget-prefabs.gen.test.ts
+++ b/sdk/tests/ui-widget-prefabs.gen.test.ts
@@ -20,6 +20,7 @@ import { UIDropdown } from '../src/ui/behavior/dropdown';
import { registerComponent } from '../src/component';
import { spawnUIEntity } from '../src/ui/core/compose';
import { UIMask, MaskMode } from '../src/ui/core/ui-mask';
+import { UIPositionType } from '../src/ui/core/ui-node';
import { Interactable } from '../src/ui/input/interactable';
import { themeColors } from '../src/ui/theme/tokens';
import { markThemed } from '../src/ui/theme/theme-style';
@@ -201,4 +202,33 @@ describe('UI widget prefab codegen', () => {
]));
expect(entityById(prefab, prefab.rootEntityId).children.length).toBe(1);
});
+
+ it('ScrollView: a clipped scroll viewport shell (scroll model wired by createScrollView)', () => {
+ const prefab = generate('ScrollView', (world) => {
+ // The serializable half of createScrollView: a Scissor-masked viewport
+ // + a hit-target + an absolutely-placed content frame (taller than the
+ // window so there is something to scroll). The scroll model — wheel /
+ // drag / kinetic fling — is runtime-only; wire it with createScrollView.
+ const viewport = spawnUIEntity({
+ world,
+ node: { width: px(240), height: px(320) },
+ visual: { color: c.control },
+ });
+ markThemed(world, viewport, { visual: 'control' });
+ world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor });
+ world.insert(viewport, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });
+ spawnUIEntity({
+ world, parent: viewport,
+ node: {
+ position: UIPositionType.Absolute,
+ insetLeft: px(0), insetTop: px(0), width: px(240), height: px(640),
+ },
+ });
+ 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);
+ });
});