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): createListView — ergonomic virtualized list/grid widget
esenginec10bf1f334ed
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.tsindex 7494949ac..6011f4a1e 100644--- a/sdk/src/core-ui.ts+++ b/sdk/src/core-ui.ts@@ -141,6 +141,22 @@ export {createDropdown,type DropdownOptions,type DropdownHandle,+ // Data-driven virtualized list / grid (REARCH_UI_LIST): the ergonomic factory+ // plus the collection primitives it composes, as escape hatches.+ createListView,+ type CreateListViewOptions,+ type ListViewHandle,+ type ListItemTemplate,+ type ListLayoutSpec,+ ListView,+ type ListViewOptions,+ ScrollContainer,+ ArrayDataSource,+ arrayDataSource,+ type DataSource,+ LinearLayoutProvider,+ GridLayoutProvider,+ type LayoutProvider,widgetToPrefab,BUILTIN_UI_PREFABS,BUILTIN_UI_WIDGET_NAMES,diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex c09cada6c..ac17f7a28 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -229,6 +229,14 @@ export {type DropdownHandle,} from './widgets/dropdown';+export {+ createListView,+ type CreateListViewOptions,+ type ListViewHandle,+ type ListItemTemplate,+ type ListLayoutSpec,+} from './widgets/list-view';+export { widgetToPrefab } from './widgets/toPrefab';export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/generated';diff --git a/sdk/src/ui/widgets/list-view.ts b/sdk/src/ui/widgets/list-view.tsnew file mode 100644index 000000000..c7a0b413e--- /dev/null+++ b/sdk/src/ui/widgets/list-view.ts@@ -0,0 +1,255 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file list-view.ts+ * @brief createListView — the ergonomic widget factory over the collection core.+ *+ * A one-call, data-driven, virtualized list/grid that composes the existing+ * primitives (DataSource + LayoutProvider + ViewPool + ListView + ScrollContainer+ * + UIMask) — matching the createButton/createDialog factory-and-handle shape.+ *+ * Layout integration (REARCH_UI_LIST §3): items are positioned by UINode+ * Absolute inset (not Transform, which the UI layout owns); the content frame is+ * translated by the scroll offset; a Scissor UIMask on the viewport clips. Mouse+ * wheel is handled by the behavior plugin's ScrollWheelSystem once the viewport is+ * a hovered raycast target — drag/touch scrolling is not wired here (v1).+ */+import { Transform } from '../../component';+import type { Entity, Vec2 } from '../../types';+import type { World } from '../../world';++import { UINode, UIPositionType, type UINodeData } from '../core/ui-node';+import { px, auto } from '../core/dimension';+import { UIMask, MaskMode } from '../core/ui-mask';+import { Interactable, UIInteraction } from '../input/interactable';+import { uiPlugin } from '../ui-plugin';++import { spawnUIEntity, setUIVisible, type UINodeInit, type UIVisualInit } from './helpers';++import {+ type DataSource,+ ArrayDataSource,+} from '../collection/data-source';+import {+ type LayoutProvider,+ type Rect,+ LinearLayoutProvider,+ GridLayoutProvider,+} from '../collection/layout-provider';+import { ListView } from '../collection/list-view';+import { ScrollContainer } from '../collection/scroll-container';++/** A single item type: how to build the entity and how to bind data to it. */+export interface ListItemTemplate<T> {+ /** Create one item entity (use `spawnUIEntity` so it carries a UINode). */+ create: (world: World, parent: Entity) => Entity;+ /** Apply data to an item; called on every (re)bind, so keep it idempotent. */+ bind: (entity: Entity, data: T, index: number) => void;+}++/** Layout sugar. A column list, a row list, or a grid (`columns`). */+export type ListLayoutSpec =+ | { itemHeight: number; spacing?: number; direction?: 'column' }+ | { itemWidth: number; spacing?: number; direction: 'row' }+ | { columns: number; itemSize: Vec2; spacing?: Vec2 };++export interface CreateListViewOptions<T> {+ world: World;+ parent?: Entity;+ /** Pixel size of the visible window. Required — scroll math needs it up front. */+ viewportSize: Vec2;+ /** Extra viewport UINode props (its size defaults to `viewportSize`). */+ node?: UINodeInit;+ /** Viewport background. Default: a transparent hit-target (so the wheel works). */+ background?: UIVisualInit;+ /** Backing data — a `DataSource<T>` or a raw array (wrapped in an ArrayDataSource). */+ data: DataSource<T> | readonly T[];+ /** Layout sugar (`itemHeight` / `columns` …) or a full `LayoutProvider`. */+ layout: ListLayoutSpec | LayoutProvider;+ /** One template, or a map of item type → template for heterogeneous rows. */+ item: ListItemTemplate<T> | Record<string, ListItemTemplate<T>>;+ /** Scroll axis. Defaults from the layout (column→vertical, row→horizontal). */+ direction?: 'vertical' | 'horizontal' | 'both';+ /** Extra indices kept mounted on each side of the visible range. Default 2. */+ recycleBuffer?: number;+ /** Wheel delta multiplier. Default 1. */+ wheelSpeed?: number;+ /** Called after each item bind. */+ onItemBound?: (entity: Entity, data: T, index: number) => void;+}++export interface ListViewHandle<T> {+ /** The viewport entity (the clipped window; add it to your UI tree). */+ readonly entity: Entity;+ /** The scrolling content frame that items are parented to. */+ readonly content: Entity;+ /** The data source — mutate an `ArrayDataSource` here to update the list. */+ readonly data: DataSource<T>;+ /** The scroll model (escape hatch: `scroll.scrollBy`, `onScroll`, …). */+ readonly scroll: ScrollContainer;+ /** The virtualization driver (escape hatch). */+ readonly view: ListView<T>;+ /** Force a re-sync of mounted items on the next frame. */+ refresh(): void;+ /** Scroll so item `index` is at the top-left of the viewport. */+ scrollToIndex(index: number): void;+ /** Number of item entities currently mounted (for virtualization checks). */+ mountedCount(): number;+ /** Tear down: unregister, release items, drop scroll/data subscriptions. */+ dispose(): void;+}++function isDataSource<T>(d: DataSource<T> | readonly T[]): d is DataSource<T> {+ return !Array.isArray(d) && typeof (d as DataSource<T>).getCount === 'function';+}++function isLayoutProvider(l: ListLayoutSpec | LayoutProvider): l is LayoutProvider {+ return typeof (l as LayoutProvider).getItemRect === 'function';+}++function buildLayout(spec: ListLayoutSpec, viewport: Vec2): { layout: LayoutProvider; axis: 'vertical' | 'horizontal' } {+ if ('columns' in spec) {+ return {+ layout: new GridLayoutProvider({ columns: spec.columns, itemSize: spec.itemSize, spacing: spec.spacing }),+ axis: 'vertical',+ };+ }+ if ('itemWidth' in spec) {+ return {+ layout: new LinearLayoutProvider({ direction: 'row', itemSize: { x: spec.itemWidth, y: viewport.y }, spacing: spec.spacing }),+ axis: 'horizontal',+ };+ }+ return {+ layout: new LinearLayoutProvider({ direction: 'column', itemSize: { x: viewport.x, y: spec.itemHeight }, spacing: spec.spacing }),+ axis: 'vertical',+ };+}++/** Position an item within the content by its computed rect (Absolute inset). */+function placeByInset(world: World, entity: Entity, rect: Rect): void {+ if (!world.has(entity, UINode)) return;+ const n = world.get(entity, UINode) as UINodeData;+ n.position = UIPositionType.Absolute;+ n.insetLeft = px(rect.x);+ n.insetTop = px(rect.y);+ n.insetRight = auto();+ n.insetBottom = auto();+ n.width = px(rect.width);+ n.height = px(rect.height);+ world.insert(entity, UINode, n);+}++/**+ * Build a virtualized list (or grid) in one call. See REARCH_UI_LIST.md.+ *+ * @example+ * const list = createListView<Player>({+ * world, parent, viewportSize: { x: 320, y: 480 },+ * data: arrayDataSource(players),+ * layout: { itemHeight: 56 },+ * item: {+ * create: (w, parent) => spawnUIEntity({ world: w, parent, node: { height: px(56) } }),+ * bind: (e, p) => setText(e, p.name),+ * },+ * });+ * list.data.append([newPlayer]); // auto-refreshes+ */+export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandle<T> {+ const { world, viewportSize } = opts;++ // 1) Viewport: sized box + Scissor mask + a hovered hit-target (for the wheel).+ const viewport = spawnUIEntity({+ world,+ parent: opts.parent,+ node: { width: px(viewportSize.x), height: px(viewportSize.y), ...opts.node },+ visual: opts.background ?? { color: { r: 0, g: 0, b: 0, a: 0 } },+ });+ 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 });++ // 2) Content: an Absolute frame translated by the scroll offset; items live here.+ const content = spawnUIEntity({+ world,+ parent: viewport,+ node: { position: UIPositionType.Absolute, insetLeft: px(0), insetTop: px(0), width: px(viewportSize.x), height: px(viewportSize.y) },+ });++ // 3) Resolve data + layout.+ const data: DataSource<T> = isDataSource(opts.data) ? opts.data : new ArrayDataSource<T>(opts.data);+ const { layout, axis } = isLayoutProvider(opts.layout)+ ? { layout: opts.layout, axis: 'vertical' as const }+ : buildLayout(opts.layout, viewportSize);++ // 4) Item templates → ViewPool template shape ({ factory, binder }).+ const single = 'create' in opts.item && 'bind' in opts.item;+ const templateMap = (single ? { default: opts.item as ListItemTemplate<T> } : opts.item as Record<string, ListItemTemplate<T>>);+ const templates: Record<string, { factory: (w: World, p: Entity) => Entity; binder: (e: Entity, d: T, i: number) => void }> = {};+ for (const [type, tpl] of Object.entries(templateMap)) {+ templates[type] = { factory: tpl.create, binder: tpl.bind };+ }++ // 5) The virtualization driver, parented to the content frame.+ const view = new ListView<T>({+ world,+ parent: content,+ dataSource: data,+ layout,+ viewportSize,+ templates,+ recycleBuffer: opts.recycleBuffer,+ placeItem: (w, e, rect) => placeByInset(w, e, rect),+ setVisible: (w, e, v) => setUIVisible(w, e, v),+ onItemBound: opts.onItemBound,+ });+ uiPlugin.registerListView(view as ListView<unknown>);++ // 6) Scroll model: wheel-driven by the plugin; onScroll translates the content+ // frame and pushes the offset into the driver.+ const scroll = new ScrollContainer({+ viewportSize,+ contentSize: layout.getContentSize(data.getCount()),+ direction: opts.direction ?? axis,+ wheelSpeed: opts.wheelSpeed,+ });+ const offScroll = scroll.onScroll((offset) => {+ const n = world.get(content, UINode) as UINodeData;+ n.insetLeft = px(-offset.x);+ n.insetTop = px(-offset.y);+ world.insert(content, UINode, n);+ view.setScrollOffset(offset);+ });+ uiPlugin.attachScrollContainer(viewport, scroll);++ // 7) Keep the scroll range in step with the data count.+ const offData = data.subscribe?.(() => {+ scroll.setContentSize(layout.getContentSize(data.getCount()));+ });++ let disposed = false;+ return {+ entity: viewport,+ content,+ data,+ scroll,+ view,+ refresh: () => view.refresh(),+ scrollToIndex: (index) => {+ const rect = layout.getItemRect(index);+ scroll.setOffset({ x: rect.x, y: rect.y });+ },+ mountedCount: () => view.getMountedCount(),+ dispose: () => {+ if (disposed) return;+ disposed = true;+ offScroll();+ offData?.();+ uiPlugin.unregisterListView(view as ListView<unknown>);+ uiPlugin.detachScrollContainer(viewport);+ scroll.dispose();+ view.dispose();+ if (world.valid(viewport)) world.despawn(viewport);+ },+ };+}diff --git a/sdk/tests/ui-list-view-widget.test.ts b/sdk/tests/ui-list-view-widget.test.tsnew file mode 100644index 000000000..9d901bcf4--- /dev/null+++ b/sdk/tests/ui-list-view-widget.test.ts@@ -0,0 +1,143 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ui-list-view-widget.test.ts+ * @brief Integration tests for the createListView widget factory over the real+ * WASM module + full uiPlugin — virtualization, scroll re-mount, dispose.+ *+ * Requires pre-built WASM at desktop/public/wasm/esengine.wasm.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import { App } from '../src/app';+import { UICameraInfo } from '../src/ui/core/ui-camera-info';+import { uiPlugin } from '../src/ui/ui-plugin';+import { createListView } from '../src/ui/widgets/list-view';+import { spawnUIEntity } from '../src/ui/widgets/helpers';+import { arrayDataSource } from '../src/ui/collection/data-source';+import { px } from '../src/ui/core/dimension';+import type { ESEngineModule, CppRegistry } from '../src/wasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';++describe.skipIf(!HAS_WASM)('createListView (WASM integration)', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ function createApp(): { app: App; registry: CppRegistry } {+ const app = App.new();+ const registry = new module.Registry() as unknown as CppRegistry;+ app.connectCpp(registry, module);+ app.insertResource(UICameraInfo, {+ viewProjection: new Float32Array(16),+ vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,+ worldLeft: 0, worldBottom: 0, worldRight: 800, worldTop: 600,+ worldMouseX: 0, worldMouseY: 0, valid: true,+ });+ // No inputPlugin: it binds platform input (unavailable in tests). The Input+ // resource has a default InputState, so the ScrollWheelSystem still resolves.+ app.addPlugin(uiPlugin);+ return { app, registry };+ }++ function disposeApp(app: App, registry: CppRegistry): void {+ const world = app.world;+ for (const e of world.getAllEntities()) { try { world.despawn(e); } catch (_) {} }+ world.disconnectCpp();+ (registry as unknown as { delete(): void }).delete();+ }++ const bigList = (n: number) =>+ arrayDataSource(Array.from({ length: n }, (_, i) => i));++ const numberRow = {+ create: (w: import('../src/world').World, parent: import('../src/types').Entity) =>+ spawnUIEntity({ world: w, parent, node: { height: px(40) } }),+ bind: () => {},+ };++ it('virtualizes: a 1000-item list mounts only items near the viewport', async () => {+ const { app, registry } = createApp();+ const list = createListView<number>({+ world: app.world,+ viewportSize: { x: 200, y: 200 }, // 5 rows visible @ 40px+ data: bigList(1000),+ layout: { itemHeight: 40 },+ item: numberRow,+ });++ await app.tick(1 / 60);++ const mounted = list.mountedCount();+ expect(mounted).toBeGreaterThan(0);+ expect(mounted).toBeLessThanOrEqual(12); // ~5 visible + buffer, NEVER 1000++ list.dispose();+ disposeApp(app, registry);+ });++ it('re-mounts a new window on scroll without growing the mount set', async () => {+ const { app, registry } = createApp();+ const list = createListView<number>({+ world: app.world,+ viewportSize: { x: 200, y: 200 },+ data: bigList(1000),+ layout: { itemHeight: 40 },+ item: numberRow,+ });++ await app.tick(1 / 60);+ const before = list.mountedCount();++ list.scroll.setOffset({ x: 0, y: 4000 }); // jump ~100 rows down+ await app.tick(1 / 60);++ expect(list.mountedCount()).toBeGreaterThan(0);+ expect(list.mountedCount()).toBeLessThanOrEqual(before + 4); // stable, not accumulating++ list.dispose();+ disposeApp(app, registry);+ });++ it('grows the mount set when the data source grows, and dispose clears it', async () => {+ const { app, registry } = createApp();+ const data = bigList(3);+ const list = createListView<number>({+ world: app.world,+ viewportSize: { x: 200, y: 400 }, // fits ~10 rows → all 3 visible+ data,+ layout: { itemHeight: 40 },+ item: numberRow,+ });++ await app.tick(1 / 60);+ expect(list.mountedCount()).toBe(3);++ (data as ReturnType<typeof bigList>).append([3, 4, 5, 6]);+ await app.tick(1 / 60);+ expect(list.mountedCount()).toBe(7);++ list.dispose();+ expect(list.mountedCount()).toBe(0);+ disposeApp(app, registry);+ });++ it('grid layout mounts a virtualized subset of a large tile set', async () => {+ const { app, registry } = createApp();+ const list = createListView<number>({+ world: app.world,+ viewportSize: { x: 300, y: 200 },+ data: bigList(1000),+ layout: { columns: 3, itemSize: { x: 96, y: 96 } },+ item: {+ create: (w, parent) => spawnUIEntity({ world: w, parent, node: { width: px(96), height: px(96) } }),+ bind: () => {},+ },+ });++ await app.tick(1 / 60);+ expect(list.mountedCount()).toBeGreaterThan(0);+ expect(list.mountedCount()).toBeLessThan(60); // a few rows of 3, not 1000++ list.dispose();+ disposeApp(app, registry);+ });+});