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): a scene can say that a node scrolls
yhhba04b0eeb09b
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdxindex e13011f09..0cac360f7 100644--- a/docs/astro/src/content/docs/guides/ui.mdx+++ b/docs/astro/src/content/docs/guides/ui.mdx@@ -22,6 +22,7 @@ detailed UI guides. Deep reference for each area lives in its own chapter.| `Text` | Text via a dynamic glyph atlas (content, font, color, align, stroke, shadow, rich text). | [UI Text](/docs/guides/ui-text/) || `UIVisual` | The fill — solid color, texture, 9-slice, tiled, or filled. | below || `UIMask` | Clips its children. | below |+| `UIScroll` | Makes a clipped node a scroll viewport: the wheel and drags move its content. | below || `Interactable` | Marks a node hit-testable so it can be hovered/clicked. | [UI Interaction](/docs/guides/ui-interaction/) || `UIInteraction` | Engine-written per-frame pointer state (read-only for your logic). | [UI Interaction](/docs/guides/ui-interaction/) |@@ -182,6 +183,41 @@ rather than compositing the subtree offscreen, the same trade every UI toolkit mworld.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvents.None });```+### Scrolling++`UIScroll` turns a clipped node into a **scroll viewport**: the wheel and drags move its+content, and the node's `UIMask` is what hides the part hanging outside. Content that fits+does not move, so the component is inert until there is something to scroll.++| Field | Default | Meaning |+|---|---|---|+| `content` | first child | The child that moves. |+| `horizontal` / `vertical` | `false` / `true` | Which axes scroll. |+| `movement` | `Clamped` | `Elastic` overshoots at the ends and springs back. |+| `wheelSpeed` | `1` | Multiplier on wheel deltas. |+| `dragScroll` | `true` | Drag/touch grabbing, with a kinetic fling. |+| `decelerationRate` | `0.135` | Fling velocity kept per second; `0` stops on release. |++```ts+// A list that scrolls vertically inside a fixed box.+const viewport = spawnUIEntity({ world, parent: panel, node: { width: px(400), height: px(300) } });+world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor, alphaCutoff: 0 });+world.insert(viewport, Interactable, { enabled: true, raycastTarget: true });++const content = spawnUIEntity({ world, parent: viewport, node: { width: px(400), height: px(1200) } });+world.insert(viewport, UIScroll, { vertical: true }); // content defaults to the first child+```++The component is what a **scene** can say. Scrolling used to be reachable only by building+the `ScrollView` widget in code, so a scroll area placed in the editor described all its+parts — the clipped box, the oversized child — without the one fact that it scrolled.+`UIScroll` is that fact, and the widget and the scene now drive the same container.++<Aside type="note">+ A viewport needs `UIMask` to clip and `Interactable` to receive the pointer. The editor's+ **Create → ScrollView** gives you all three already assembled.+</Aside>+## Editor or codediff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdxindex 2567af699..2a0983cfa 100644--- a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx@@ -20,6 +20,7 @@ flexbox,用 `px` / `percent` / `auto` 加 `Absolute` 内偏移(inset)来定尺| `Text` | 经动态字形图集渲染文本(内容、字体、颜色、对齐、描边、阴影、富文本)。 | [UI 文本](/docs/zh-cn/guides/ui-text/) || `UIVisual` | 填充——纯色、纹理、九宫格、平铺或填充。 | 见下文 || `UIMask` | 裁剪它的子项。 | 见下文 |+| `UIScroll` | 让被裁剪的节点成为滚动视口:滚轮与拖拽移动它的内容。 | 见下文 || `Interactable` | 标记节点可命中,从而能被悬停/点击。 | [UI 交互](/docs/zh-cn/guides/ui-interaction/) || `UIInteraction` | 引擎每帧写入的指针状态(对你的逻辑只读)。 | [UI 交互](/docs/zh-cn/guides/ui-interaction/) |@@ -166,6 +167,39 @@ CSS 语义——逐视觉相乘而不是把子树离屏合成,这是每个 UIworld.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvents.None });```+### 滚动++`UIScroll` 把一个被裁剪的节点变成**滚动视口**:滚轮和拖拽移动它的内容,而节点上的 `UIMask`+负责把露到外面的部分藏起来。内容装得下时不会动,所以在没有可滚内容之前这个组件是惰性的。++| 字段 | 默认 | 含义 |+|---|---|---|+| `content` | 第一个子节点 | 被移动的那个子节点。 |+| `horizontal` / `vertical` | `false` / `true` | 哪些轴可滚。 |+| `movement` | `Clamped` | `Elastic` 会在两端过冲再弹回。 |+| `wheelSpeed` | `1` | 滚轮增量的倍率。 |+| `dragScroll` | `true` | 拖拽/触摸抓取,带惯性甩动。 |+| `decelerationRate` | `0.135` | 甩动速度每秒保留的比例;`0` 表示松手即停。 |++```ts+// 一个在固定盒子里纵向滚动的列表。+const viewport = spawnUIEntity({ world, parent: panel, node: { width: px(400), height: px(300) } });+world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor, alphaCutoff: 0 });+world.insert(viewport, Interactable, { enabled: true, raycastTarget: true });++const content = spawnUIEntity({ world, parent: viewport, node: { width: px(400), height: px(1200) } });+world.insert(viewport, UIScroll, { vertical: true }); // content 缺省取第一个子节点+```++这个组件补的是**场景能说出口的话**。以前滚动只能靠在代码里构造 `ScrollView` widget,所以在+编辑器里摆出来的滚动区能描述自己的每个零件——被裁剪的盒子、超长的子节点——唯独说不出「它会滚」+这件事。`UIScroll` 就是这件事,现在 widget 和场景驱动的是同一个容器。++<Aside type="note">+ 视口需要 `UIMask` 来裁剪、`Interactable` 来接收指针。编辑器的 **Create → ScrollView**+ 已经把这三样装配好了。+</Aside>+## 编辑器还是代码diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7f48353e5..607efca11 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 1372 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```-"52526b76662ebd4a"+"638b897738f9c7db"```## ANCHOR_AXES — const@@ -1727,6 +1727,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -1760,6 +1761,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -1789,6 +1791,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -1818,6 +1821,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 78be57fe1..dc3f54739 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 1391 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```-"52526b76662ebd4a"+"638b897738f9c7db"```## ANCHOR_AXES — const@@ -1735,6 +1735,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -1768,6 +1769,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -1797,6 +1799,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -1826,6 +1829,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 175df4919..be4c816d2 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1722,6 +1722,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d3ad48a01..53e3bcce7 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1722,6 +1722,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 0e45d04ef..339bcee08 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -40,6 +40,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -73,6 +74,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -102,6 +104,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -131,6 +134,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 19af6df94..1865dfe78 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1722,6 +1722,7 @@ addTransform: (entity: Entity, component: Transform) => voidaddUIInteraction: (entity: Entity, component: UIInteraction) => voidaddUIMask: (entity: Entity, component: UIMask) => voidaddUINode: (entity: Entity, component: UINode) => void+addUIScroll: (entity: Entity, component: UIScroll) => voidaddUIVisual: (entity: Entity, component: UIVisual) => voidaddVelocity: (entity: Entity, component: Velocity) => voidcreate: () => Entity@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => TransformgetUIInteraction: (entity: Entity) => UIInteractiongetUIMask: (entity: Entity) => UIMaskgetUINode: (entity: Entity) => UINode+getUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => VelocityhasBitmapText: (entity: Entity) => boolean@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => booleanhasUIInteraction: (entity: Entity) => booleanhasUIMask: (entity: Entity) => booleanhasUINode: (entity: Entity) => boolean+hasUIScroll: (entity: Entity) => booleanhasUIVisual: (entity: Entity) => booleanhasVelocity: (entity: Entity) => booleanremoveBitmapText: (entity: Entity) => void@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => voidremoveUIInteraction: (entity: Entity) => voidremoveUIMask: (entity: Entity) => voidremoveUINode: (entity: Entity) => void+removeUIScroll: (entity: Entity) => voidremoveUIVisual: (entity: Entity) => voidremoveVelocity: (entity: Entity) => voidsetParent: (child: Entity, parent: Entity) => voiddiff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex af367bda1..7f0e9d984 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -1569,6 +1569,58 @@ export function createUINodeData(): UINodePtrData {};}+export interface UIScrollPtrData {+ enabled: boolean;+ content: number;+ horizontal: boolean;+ vertical: boolean;+ movement: number;+ wheelSpeed: number;+ dragScroll: boolean;+ decelerationRate: number;+}++export function fillUIScroll(+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,+ ptr: number, out: UIScrollPtrData,+): void {+ out.enabled = u8[ptr] !== 0;+ out.content = u32[(ptr + 4) >> 2];+ out.horizontal = u8[ptr + 8] !== 0;+ out.vertical = u8[ptr + 9] !== 0;+ out.movement = u8[ptr + 10];+ out.wheelSpeed = f32[(ptr + 12) >> 2];+ out.dragScroll = u8[ptr + 16] !== 0;+ out.decelerationRate = f32[(ptr + 20) >> 2];+}++export function writeUIScroll(+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,+ ptr: number, data: UIScrollPtrData,+): void {+ u8[ptr] = data.enabled ? 1 : 0;+ u32[(ptr + 4) >> 2] = data.content;+ u8[ptr + 8] = data.horizontal ? 1 : 0;+ u8[ptr + 9] = data.vertical ? 1 : 0;+ u8[ptr + 10] = data.movement;+ f32[(ptr + 12) >> 2] = data.wheelSpeed;+ u8[ptr + 16] = data.dragScroll ? 1 : 0;+ f32[(ptr + 20) >> 2] = data.decelerationRate;+}++export function createUIScrollData(): UIScrollPtrData {+ return {+ enabled: false,+ content: 0,+ horizontal: false,+ vertical: false,+ movement: 0,+ wheelSpeed: 0,+ dragScroll: false,+ decelerationRate: 0,+ };+}+export interface UIVisualPtrData {visualType: number;texture: number;@@ -1701,6 +1753,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {UIInteraction: { fill: fillUIInteraction, write: writeUIInteraction, create: createUIInteractionData },UIMask: { fill: fillUIMask, write: writeUIMask, create: createUIMaskData },UINode: { fill: fillUINode, write: writeUINode, create: createUINodeData },+ UIScroll: { fill: fillUIScroll, write: writeUIScroll, create: createUIScrollData },UIVisual: { fill: fillUIVisual, write: writeUIVisual, create: createUIVisualData },Velocity: { fill: fillVelocity, write: writeVelocity, create: createVelocityData },};diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 08774c4b0..7576edce5 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '52526b76662ebd4a';+export const ABI_LAYOUT_HASH = '638b897738f9c7db';export interface AssetFieldMeta {field: string;@@ -757,6 +757,28 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {alignSelf: { enum: [{ label: 'Auto', value: 0 }, { label: 'Start', value: 1 }, { label: 'Center', value: 2 }, { label: 'End', value: 3 }, { label: 'Stretch', value: 4 }] },},},+ UIScroll: {+ defaults: {+ enabled: true,+ content: 0,+ horizontal: false,+ vertical: true,+ movement: 0,+ wheelSpeed: 1,+ dragScroll: true,+ decelerationRate: 0.135,+ },+ assetFields: [],+ entityFields: ['content'],+ colorFields: [],+ animatableFields: [],+ fields: {+ content: { tooltip: "The child that scrolls inside this node. Leave empty to use the first child." },+ movement: { enum: [{ label: 'Clamped', value: 0 }, { label: 'Elastic', value: 1 }], tooltip: "Clamped stops at the ends; Elastic overshoots and springs back." },+ wheelSpeed: { min: 0 },+ decelerationRate: { min: 0, max: 1, tooltip: "Fraction of flick velocity kept per second. 0 stops on release." },+ },+ },UIVisual: {defaults: {visualType: 0,@@ -1158,6 +1180,17 @@ export interface UINodeData {insetBottom: Dimension;}+export interface UIScrollData {+ enabled: boolean;+ content: Entity;+ horizontal: boolean;+ vertical: boolean;+ movement: number;+ wheelSpeed: number;+ dragScroll: boolean;+ decelerationRate: number;+}+export interface UIVisualData {visualType: number;texture: number;diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.tsindex 37a62928c..7ee093d13 100644--- a/sdk/src/ui/behavior/plugin.ts+++ b/sdk/src/ui/behavior/plugin.ts@@ -13,6 +13,9 @@ import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';import { PluginName, SystemLabel } from '../../ecs/systemLabels';import { ListView, ListViewRegistry } from '../collection/list-view';import { ScrollContainer, ScrollContainerRegistry } from '../collection/scroll-container';+import { createScrollAdoptSystem } from './scroll';+import { engineApi } from '../../ecs/bridge/engineApi';+import type { CppRegistry } from '../../wasm';import { KineticScroll } from '../collection/kinetic-scroll';import { UIInteraction, type UIInteractionData } from '../input/interactable';import { getEntityDepth, walkParentChain } from '../util/helpers';@@ -124,6 +127,15 @@ export class UIBehaviorPlugin implements Plugin {{ runIf: playModeOnly },);+ // A scroll area authored in a scene becomes a live one here, so the+ // editor's ScrollView and a hand-built UIScroll node scroll for the same+ // reason the widget does — one input path, one container registry.+ app.addSystemToSchedule(+ Schedule.Update,+ createScrollAdoptSystem(world, engineApi(app), world.getCppRegistry() as CppRegistry, this),+ { runIf: playModeOnly },+ );+app.addSystemToSchedule(Schedule.Update,createScrollbarSystem(world, scrollContainers),diff --git a/sdk/src/ui/behavior/scroll.ts b/sdk/src/ui/behavior/scroll.tsnew file mode 100644index 000000000..71c792acd--- /dev/null+++ b/sdk/src/ui/behavior/scroll.ts@@ -0,0 +1,145 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scroll.ts+ * @brief Adopt scene-authored UIScroll nodes into live ScrollContainers.+ *+ * The ScrollView widget builds its parts and its behaviour together, in code.+ * A scene can only describe the parts — a clipped box with an oversized child —+ * so until now the behaviour had no way in, and a ScrollView placed in the+ * editor scrolled only if game code went looking for it. This system is the way+ * in: every entity carrying UIScroll gets a ScrollContainer wired to the same+ * input path the widget uses, and loses it when the component goes away.+ */+import { Schedule, defineSystem } from '../../ecs/system';+import { Query } from '../../ecs/query';+import type { Entity } from '../../types';+import type { World } from '../../ecs/world';+import type { CppRegistry } from '../../wasm';+import type { EngineApi } from '../../ecs/bridge/engineApi';+import { UINode, UIPositionType, type UINodeData } from '../core/ui-node';+import { UIScroll, ScrollMovement, type UIScrollData } from '../core/ui-scroll';+import { ScrollContainer } from '../collection/scroll-container';+import type { Vec2 } from '../../types';++/** What the plugin hands this system: the same registry the widget attaches to. */+export interface ScrollHost {+ attachScrollContainer(entity: Entity, container: ScrollContainer): void;+ detachScrollContainer(entity: Entity): void;+}++interface Attached {+ container: ScrollContainer;+ content: Entity;+ unsubscribe: () => void;+}++const px = (v: number) => ({ value: v, unit: 0 } as const);++function directionOf(scroll: UIScrollData): 'both' | 'vertical' | 'horizontal' {+ if (scroll.horizontal && scroll.vertical) return 'both';+ return scroll.horizontal ? 'horizontal' : 'vertical';+}++export function createScrollAdoptSystem(+ world: World,+ engine: EngineApi | null,+ registry: CppRegistry,+ host: ScrollHost,+) {+ const attached = new Map<Entity, Attached>();++ /** The resolved box the layout pass produced, not the authored dimension. */+ const size = (entity: Entity): Vec2 => ({+ x: engine?.uiNode_computedWidth?.(registry, entity) ?? 0,+ y: engine?.uiNode_computedHeight?.(registry, entity) ?? 0,+ });++ /**+ * The child that moves: the one named, else the first.+ *+ * The children list is a wasm vector, so it is read through its accessors+ * and then freed — one left alive leaks module memory, and this would be+ * asking every frame.+ */+ const contentOf = (entity: Entity, scroll: UIScrollData): Entity | null => {+ if (scroll.content) return scroll.content as Entity;+ if (!registry?.hasChildren?.(entity)) return null;+ const vec = registry.getChildren(entity).entities;+ try {+ return vec.size() > 0 ? (vec.get(0) as Entity) : null;+ } finally {+ vec.delete();+ }+ };++ const detach = (entity: Entity): void => {+ const a = attached.get(entity);+ if (!a) return;+ a.unsubscribe();+ host.detachScrollContainer(entity);+ attached.delete(entity);+ };++ const attach = (entity: Entity, scroll: UIScrollData): void => {+ const content = contentOf(entity, scroll);+ if (content == null) return; // nothing to move yet — try again next tick++ const container = new ScrollContainer({+ viewportSize: size(entity),+ contentSize: size(content),+ direction: directionOf(scroll),+ wheelSpeed: scroll.wheelSpeed,+ dragScroll: scroll.dragScroll,+ decelerationRate: scroll.movement === ScrollMovement.Elastic ? scroll.decelerationRate : 0,+ });+ // The offset moves the content by its insets, exactly as the widget does,+ // so both paths leave the same thing in the scene.+ const unsubscribe = container.onScroll((offset) => {+ const node = world.get(content, UINode) as UINodeData | undefined;+ if (!node) return;+ node.position = UIPositionType.Absolute;+ node.insetLeft = px(-offset.x);+ node.insetTop = px(-offset.y);+ world.insert(content, UINode, node);+ });+ host.attachScrollContainer(entity, container);+ attached.set(entity, { container, content, unsubscribe });+ };++ return defineSystem([Query(UIScroll)], (query) => {+ const live = new Set<Entity>();++ for (const [entity, scroll] of query) {+ const data = scroll as UIScrollData;+ if (!data.enabled) continue;+ live.add(entity);++ const a = attached.get(entity);+ if (!a) {+ attach(entity, data);+ continue;+ }+ // A content swap is a different container, not a resize. Only an+ // explicit ref is re-read each frame; the implicit "first child" is+ // trusted while it lives, so the steady state costs no wasm calls.+ const swapped = data.content+ ? (data.content as Entity) !== a.content+ : !world.valid(a.content);+ if (swapped) {+ detach(entity);+ attach(entity, data);+ continue;+ }+ const content = a.content;+ // Layout is free to change under us (a window resize, a list that+ // grew), and both setters early-out when nothing moved.+ a.container.setViewportSize(size(entity));+ a.container.setContentSize(size(content));+ }++ for (const entity of [...attached.keys()]) {+ if (!live.has(entity)) detach(entity);+ }+ }, { name: 'UIScrollAdoptSystem' });+}diff --git a/sdk/src/ui/core/ui-scroll.ts b/sdk/src/ui/core/ui-scroll.tsnew file mode 100644index 000000000..c7595758f--- /dev/null+++ b/sdk/src/ui/core/ui-scroll.ts@@ -0,0 +1,39 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { defineBuiltin } from '../../ecs/component';++export const ScrollMovement = {+ /** Stop dead at the ends. */+ Clamped: 0,+ /** Overshoot and spring back — the touch-UI feel. */+ Elastic: 1,+} as const;+export type ScrollMovement = (typeof ScrollMovement)[keyof typeof ScrollMovement];++/**+ * A scrollable viewport, authored in the scene rather than constructed in code.+ * `uiBehaviorPlugin` attaches a ScrollContainer to every entity carrying one.+ */+export interface UIScrollData {+ enabled: boolean;+ /** The child that moves; 0 ⇒ this node's first child. */+ content: number;+ horizontal: boolean;+ vertical: boolean;+ movement: ScrollMovement;+ wheelSpeed: number;+ dragScroll: boolean;+ /** Fraction of flick velocity kept per second; 0 stops on release. */+ decelerationRate: number;+}++export const UIScroll = defineBuiltin<UIScrollData>('UIScroll', {+ enabled: true,+ content: 0,+ horizontal: false,+ vertical: true,+ movement: ScrollMovement.Clamped,+ wheelSpeed: 1,+ dragScroll: true,+ decelerationRate: 0.135,+});diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex b5a7409c9..39ba6cbe9 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -56,6 +56,7 @@ export {} from './core/ui-visual';export { UIMask, MaskMode, type UIMaskData } from './core/ui-mask';+export { UIScroll, ScrollMovement, type UIScrollData } from './core/ui-scroll';export {Text,diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex c05896d11..517a355ae 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -417,6 +417,19 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'insetBottom', type: 'struct', offset: 136, members: [{ name: 'value', type: 'f32', offset: 0 }, { name: 'unit', type: 'u8', offset: 4 }] },],},+ UIScroll: {+ ptrFn: 'getUIScrollPtr',+ fields: [+ { name: 'enabled', type: 'bool', offset: 0 },+ { name: 'content', type: 'u32', offset: 4 },+ { name: 'horizontal', type: 'bool', offset: 8 },+ { name: 'vertical', type: 'bool', offset: 9 },+ { name: 'movement', type: 'u8', offset: 10 },+ { name: 'wheelSpeed', type: 'f32', offset: 12 },+ { name: 'dragScroll', type: 'bool', offset: 16 },+ { name: 'decelerationRate', type: 'f32', offset: 20 },+ ],+ },UIVisual: {ptrFn: 'getUIVisualPtr',fields: [diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex 4f7b6b06c..a67343fa7 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -127,6 +127,11 @@ export enum ProjectionType {Orthographic = 1,}+export enum ScrollMovement {+ Clamped = 0,+ Elastic = 1,+}+export enum ShapeType {Circle = 0,Capsule = 1,@@ -570,6 +575,17 @@ export interface UINode {insetBottom: Dimension;}+export interface UIScroll {+ enabled: boolean;+ content: number;+ horizontal: boolean;+ vertical: boolean;+ movement: number;+ wheelSpeed: number;+ dragScroll: boolean;+ decelerationRate: number;+}+export interface UIVisual {visualType: number;texture: number;@@ -706,6 +722,10 @@ export interface Registry {getUINode(entity: Entity): UINode;addUINode(entity: Entity, component: UINode): void;removeUINode(entity: Entity): void;+ hasUIScroll(entity: Entity): boolean;+ getUIScroll(entity: Entity): UIScroll;+ addUIScroll(entity: Entity, component: UIScroll): void;+ removeUIScroll(entity: Entity): void;hasUIVisual(entity: Entity): boolean;getUIVisual(entity: Entity): UIVisual;addUIVisual(entity: Entity, component: UIVisual): void;@@ -755,6 +775,7 @@ export interface ESEngineModule {UIInteraction: new () => UIInteraction;UIMask: new () => UIMask;UINode: new () => UINode;+ UIScroll: new () => UIScroll;UIVisual: new () => UIVisual;Velocity: new () => Velocity;}diff --git a/sdk/tests/ui-scroll-adopt.test.ts b/sdk/tests/ui-scroll-adopt.test.tsnew file mode 100644index 000000000..e660803e9--- /dev/null+++ b/sdk/tests/ui-scroll-adopt.test.ts@@ -0,0 +1,131 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ui-scroll-adopt.test.ts+ * @brief A scene-authored UIScroll becomes a live ScrollContainer.+ *+ * The widget path (createScrollView) always built its container itself. What is+ * new is the scene path: a node carrying UIScroll gets one attached without any+ * code naming it, which is what makes a scroll area placed in the editor+ * actually scroll.+ *+ * Engine-coupled, because UIScroll and Children are C++ components and a World+ * without the module simply drops them. The resolved box normally comes from+ * the layout pass; here the two size queries are faked, so what is under test is+ * the adoption and not Yoga.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import { App } from '../src/app/app';+import { Schedule } from '../src/ecs/system';+import { UINode, UIScroll, ScrollMovement, type UINodeData, type UIScrollData } from '../src/ui';+import type { ESEngineModule, CppRegistry } from '../src/wasm';+import type { ScrollContainer } from '../src/ui/collection/scroll-container';+import { createScrollAdoptSystem } from '../src/ui/behavior/scroll';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';++const px = (v: number) => ({ value: v, unit: 0 });+const auto = () => ({ value: 0, unit: 2 });++/** embind wants every member present. */+function fullNode(): UINodeData {+ return {+ position: 0, display: 0, opacity: 1, pointerEvents: 0,+ width: auto(), height: auto(),+ minWidth: auto(), minHeight: auto(), maxWidth: auto(), maxHeight: auto(),+ flexGrow: 0, flexShrink: 1, flexBasis: auto(), alignSelf: 0,+ marginLeft: px(0), marginTop: px(0), marginRight: px(0), marginBottom: px(0),+ insetLeft: auto(), insetTop: auto(), insetRight: auto(), insetBottom: auto(),+ } as UINodeData;+}++function fullScroll(over: Partial<UIScrollData> = {}): UIScrollData {+ return {+ enabled: true, content: 0, horizontal: false, vertical: true,+ movement: ScrollMovement.Clamped, wheelSpeed: 1, dragScroll: true,+ decelerationRate: 0.135, ...over,+ };+}++describe.skipIf(!HAS_WASM)('UIScroll adoption', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ function setup(scroll: Partial<UIScrollData> = {}, contentSize = { w: 400, h: 1200 }) {+ const app = App.new();+ const registry = new module.Registry() as unknown as CppRegistry;+ app.connectCpp(registry, module);+ const world = app.world;++ const viewport = world.spawn('viewport');+ const content = world.spawn('content');+ world.insert(viewport, UINode, fullNode());+ world.insert(content, UINode, fullNode());+ world.setParent(content, viewport);+ world.insert(viewport, UIScroll, fullScroll(scroll));++ const sizes = new Map<number, { w: number; h: number }>([+ [viewport as number, { w: 400, h: 300 }],+ [content as number, contentSize],+ ]);+ const attached = new Map<number, ScrollContainer>();++ app.addSystemToSchedule(Schedule.Update, createScrollAdoptSystem(+ world,+ {+ uiNode_computedWidth: (_r: unknown, e: number) => sizes.get(e)?.w ?? 0,+ uiNode_computedHeight: (_r: unknown, e: number) => sizes.get(e)?.h ?? 0,+ } as never,+ registry,+ {+ attachScrollContainer: (e, c) => { attached.set(e as number, c); },+ detachScrollContainer: (e) => { attached.delete(e as number); },+ },+ ));+ return { app, world, viewport, content, attached };+ }++ it('attaches a container sized from the resolved layout', async () => {+ const { app, viewport, attached } = setup();+ await app.tick(1 / 60);++ const container = attached.get(viewport as number);+ expect(container).toBeDefined();+ // 1200 of content in a 300 box leaves 900 to travel.+ expect(container!.getMaxOffset()).toEqual({ x: 0, y: 900 });+ });++ it('scrolling moves the content by its inset, the way the widget does', async () => {+ const { app, world, viewport, content, attached } = setup();+ await app.tick(1 / 60);++ attached.get(viewport as number)!.scrollBy({ x: 0, y: 120 });+ const node = world.get(content, UINode) as UINodeData;+ expect(node.insetTop.value).toBeCloseTo(-120, 3);+ expect(node.insetTop.unit).toBe(0);+ });++ it('clamps to the content, so a short list cannot be dragged off', async () => {+ const { app, viewport, attached } = setup({}, { w: 400, h: 100 });+ await app.tick(1 / 60);++ const container = attached.get(viewport as number)!;+ container.scrollBy({ x: 0, y: 500 });+ expect(container.getOffset()).toEqual({ x: 0, y: 0 });+ });++ it('detaches when the component goes away', async () => {+ const { app, world, viewport, attached } = setup();+ await app.tick(1 / 60);+ expect(attached.has(viewport as number)).toBe(true);++ world.remove(viewport, UIScroll);+ await app.tick(1 / 60);+ expect(attached.has(viewport as number)).toBe(false);+ });++ it('does not attach while disabled', async () => {+ const { app, viewport, attached } = setup({ enabled: false });+ await app.tick(1 / 60);+ expect(attached.has(viewport as number)).toBe(false);+ });+});diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex b3417fdfb..d43c1d901 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash ddbf982e6824a31b+ * @schema_hash 4876a54a8e08f631*/-#define ES_EDITOR_API_SCHEMA_HASH "ddbf982e6824a31b"+#define ES_EDITOR_API_SCHEMA_HASH "4876a54a8e08f631"#include <emscripten/bind.h>#include <string>@@ -34,6 +34,7 @@#include "../ecs/components/UIInteraction.hpp"#include "../ecs/components/UIMask.hpp"#include "../ecs/components/UINode.hpp"+#include "../ecs/components/UIScroll.hpp"#include "../ecs/components/UIVisual.hpp"#include "../ecs/components/Velocity.hpp"#include <glm/gtc/quaternion.hpp>@@ -82,6 +83,7 @@ std::vector<std::string> editor_getComponentNames() {"UIInteraction","UIMask","UINode",+ "UIScroll","UIVisual","Velocity",};@@ -537,6 +539,17 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"insetBottom.value","type":"float","group":"UINode"},{"key":"insetBottom.unit","type":"float","group":"UINode"}])JSON";+ } else if (name == "UIScroll") {+ return R"JSON([+ {"key":"enabled","type":"bool","group":"UIScroll"},+ {"key":"content","type":"entity","group":"UIScroll"},+ {"key":"horizontal","type":"bool","group":"UIScroll"},+ {"key":"vertical","type":"bool","group":"UIScroll"},+ {"key":"movement","type":"enum","group":"UIScroll","values":["Clamped","Elastic"]},+ {"key":"wheelSpeed","type":"float","group":"UIScroll"},+ {"key":"dragScroll","type":"bool","group":"UIScroll"},+ {"key":"decelerationRate","type":"float","group":"UIScroll"}+ ])JSON";} else if (name == "UIVisual") {return R"JSON([{"key":"visualType","type":"enum","group":"UIVisual","values":["None","SolidColor","Image","NineSlice","Tiled","Filled"]},@@ -661,6 +674,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {} else if (name == "UINode") {if (!reg.has<esengine::ecs::UINode>(entity)) reg.emplace<esengine::ecs::UINode>(entity);return true;+ } else if (name == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) reg.emplace<esengine::ecs::UIScroll>(entity);+ return true;} else if (name == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) reg.emplace<esengine::ecs::UIVisual>(entity);return true;@@ -728,6 +744,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {if (reg.has<esengine::ecs::UIMask>(entity)) { reg.remove<esengine::ecs::UIMask>(entity); return true; }} else if (name == "UINode") {if (reg.has<esengine::ecs::UINode>(entity)) { reg.remove<esengine::ecs::UINode>(entity); return true; }+ } else if (name == "UIScroll") {+ if (reg.has<esengine::ecs::UIScroll>(entity)) { reg.remove<esengine::ecs::UIScroll>(entity); return true; }} else if (name == "UIVisual") {if (reg.has<esengine::ecs::UIVisual>(entity)) { reg.remove<esengine::ecs::UIVisual>(entity); return true; }} else if (name == "Velocity") {@@ -766,6 +784,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {if (name == "UIInteraction") return reg.has<esengine::ecs::UIInteraction>(entity);if (name == "UIMask") return reg.has<esengine::ecs::UIMask>(entity);if (name == "UINode") return reg.has<esengine::ecs::UINode>(entity);+ if (name == "UIScroll") return reg.has<esengine::ecs::UIScroll>(entity);if (name == "UIVisual") return reg.has<esengine::ecs::UIVisual>(entity);if (name == "Velocity") return reg.has<esengine::ecs::Velocity>(entity);return false;@@ -804,6 +823,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {if (reg.has<esengine::ecs::UIInteraction>(entity)) result.push_back("UIInteraction");if (reg.has<esengine::ecs::UIMask>(entity)) result.push_back("UIMask");if (reg.has<esengine::ecs::UINode>(entity)) result.push_back("UINode");+ if (reg.has<esengine::ecs::UIScroll>(entity)) result.push_back("UIScroll");if (reg.has<esengine::ecs::UIVisual>(entity)) result.push_back("UIVisual");if (reg.has<esengine::ecs::Velocity>(entity)) result.push_back("Velocity");return result;@@ -1175,6 +1195,13 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "insetBottom.unit") { c.insetBottom.unit = value; }else { return false; }return true;+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return false;+ auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "wheelSpeed") { c.wheelSpeed = value; }+ else if (field == "decelerationRate") { c.decelerationRate = value; }+ else { return false; }+ return true;} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return false;auto& c = reg.get<esengine::ecs::UIVisual>(entity);@@ -1518,6 +1545,11 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "insetRight.unit") { return c.insetRight.unit; }else if (field == "insetBottom.value") { return c.insetBottom.value; }else if (field == "insetBottom.unit") { return c.insetBottom.unit; }+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return 0.0f;+ const auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "wheelSpeed") { return c.wheelSpeed; }+ else if (field == "decelerationRate") { return c.decelerationRate; }} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return 0.0f;const auto& c = reg.get<esengine::ecs::UIVisual>(entity);@@ -1732,6 +1764,13 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::strelse if (field == "alignSelf") { c.alignSelf = static_cast<AlignSelf>(value); }else { return false; }return true;+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return false;+ auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "content") { c.content = static_cast<u32>(value); }+ else if (field == "movement") { c.movement = static_cast<ScrollMovement>(value); }+ else { return false; }+ return true;} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return false;auto& c = reg.get<esengine::ecs::UIVisual>(entity);@@ -1886,6 +1925,11 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::strielse if (field == "display") { return static_cast<i32>(c.display); }else if (field == "pointerEvents") { return static_cast<i32>(c.pointerEvents); }else if (field == "alignSelf") { return static_cast<i32>(c.alignSelf); }+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return 0;+ const auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "content") { return static_cast<i32>(c.content); }+ else if (field == "movement") { return static_cast<i32>(c.movement); }} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return 0;const auto& c = reg.get<esengine::ecs::UIVisual>(entity);@@ -2061,6 +2105,15 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::stif (field == "enabled") { c.enabled = value; }else { return false; }return true;+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return false;+ auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "enabled") { c.enabled = value; }+ else if (field == "horizontal") { c.horizontal = value; }+ else if (field == "vertical") { c.vertical = value; }+ else if (field == "dragScroll") { c.dragScroll = value; }+ else { return false; }+ return true;} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return false;auto& c = reg.get<esengine::ecs::UIVisual>(entity);@@ -2191,6 +2244,13 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::stif (!reg.has<esengine::ecs::UIMask>(entity)) return false;const auto& c = reg.get<esengine::ecs::UIMask>(entity);if (field == "enabled") { return c.enabled; }+ } else if (comp == "UIScroll") {+ if (!reg.has<esengine::ecs::UIScroll>(entity)) return false;+ const auto& c = reg.get<esengine::ecs::UIScroll>(entity);+ if (field == "enabled") { return c.enabled; }+ else if (field == "horizontal") { return c.horizontal; }+ else if (field == "vertical") { return c.vertical; }+ else if (field == "dragScroll") { return c.dragScroll; }} else if (comp == "UIVisual") {if (!reg.has<esengine::ecs::UIVisual>(entity)) return false;const auto& c = reg.get<esengine::ecs::UIVisual>(entity);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex d9915d12c..d06dea88b 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -34,6 +34,7 @@#include "../ecs/components/UIInteraction.hpp"#include "../ecs/components/UIMask.hpp"#include "../ecs/components/UINode.hpp"+#include "../ecs/components/UIScroll.hpp"#include "../ecs/components/UIVisual.hpp"#include "../ecs/components/Velocity.hpp"@@ -176,6 +177,10 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {.value("Perspective", esengine::ecs::ProjectionType::Perspective).value("Orthographic", esengine::ecs::ProjectionType::Orthographic);+ enum_<esengine::ecs::ScrollMovement>("ScrollMovement")+ .value("Clamped", esengine::ecs::ScrollMovement::Clamped)+ .value("Elastic", esengine::ecs::ScrollMovement::Elastic);+enum_<esengine::ecs::ShapeType>("ShapeType").value("Circle", esengine::ecs::ShapeType::Circle).value("Capsule", esengine::ecs::ShapeType::Capsule)@@ -952,6 +957,43 @@ UINodeJS uinodeToJS(const esengine::ecs::UINode& c) {return js;}+struct UIScrollJS {+ bool enabled;+ u32 content;+ bool horizontal;+ bool vertical;+ i32 movement;+ f32 wheelSpeed;+ bool dragScroll;+ f32 decelerationRate;+};++esengine::ecs::UIScroll uiscrollFromJS(const UIScrollJS& js) {+ esengine::ecs::UIScroll c;+ c.enabled = js.enabled;+ c.content = js.content;+ c.horizontal = js.horizontal;+ c.vertical = js.vertical;+ c.movement = static_cast<ScrollMovement>(js.movement);+ c.wheelSpeed = js.wheelSpeed;+ c.dragScroll = js.dragScroll;+ c.decelerationRate = js.decelerationRate;+ return c;+}++UIScrollJS uiscrollToJS(const esengine::ecs::UIScroll& c) {+ UIScrollJS js;+ js.enabled = c.enabled;+ js.content = c.content;+ js.horizontal = c.horizontal;+ js.vertical = c.vertical;+ js.movement = static_cast<i32>(c.movement);+ js.wheelSpeed = c.wheelSpeed;+ js.dragScroll = c.dragScroll;+ js.decelerationRate = c.decelerationRate;+ return js;+}+struct UIVisualJS {i32 visualType;u32 texture;@@ -1337,6 +1379,16 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("insetRight", &UINodeJS::insetRight).field("insetBottom", &UINodeJS::insetBottom);+ value_object<UIScrollJS>("UIScroll")+ .field("enabled", &UIScrollJS::enabled)+ .field("content", &UIScrollJS::content)+ .field("horizontal", &UIScrollJS::horizontal)+ .field("vertical", &UIScrollJS::vertical)+ .field("movement", &UIScrollJS::movement)+ .field("wheelSpeed", &UIScrollJS::wheelSpeed)+ .field("dragScroll", &UIScrollJS::dragScroll)+ .field("decelerationRate", &UIScrollJS::decelerationRate);+value_object<UIVisualJS>("UIVisual").field("visualType", &UIVisualJS::visualType).field("texture", &UIVisualJS::texture)@@ -1931,6 +1983,26 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {r.remove<esengine::ecs::UINode>(entity);}))+ // UIScroll+ .function("hasUIScroll", optional_override([](Registry& r, u32 e) {+ return r.has<esengine::ecs::UIScroll>(static_cast<Entity>(e));+ }))+ .function("getUIScroll", optional_override([](Registry& r, u32 e) {+ auto entity = static_cast<Entity>(e);+ if (!r.valid(entity) || !r.has<esengine::ecs::UIScroll>(entity)) return UIScrollJS{};+ return uiscrollToJS(r.get<esengine::ecs::UIScroll>(entity));+ }))+ .function("addUIScroll", optional_override([](Registry& r, u32 e, const UIScrollJS& js) {+ auto entity = static_cast<Entity>(e);+ if (!r.valid(entity)) return;+ r.emplaceOrReplace<esengine::ecs::UIScroll>(entity, uiscrollFromJS(js));+ }))+ .function("removeUIScroll", optional_override([](Registry& r, u32 e) {+ auto entity = static_cast<Entity>(e);+ if (!r.valid(entity) || !r.has<esengine::ecs::UIScroll>(entity)) return;+ r.remove<esengine::ecs::UIScroll>(entity);+ }))+// UIVisual.function("hasUIVisual", optional_override([](Registry& r, u32 e) {return r.has<esengine::ecs::UIVisual>(static_cast<Entity>(e));@@ -2015,6 +2087,7 @@ emscripten::val esengineGetBuiltinComponentNames() {arr.set(i++, val(std::string("UIInteraction")));arr.set(i++, val(std::string("UIMask")));arr.set(i++, val(std::string("UINode")));+ arr.set(i++, val(std::string("UIScroll")));arr.set(i++, val(std::string("UIVisual")));arr.set(i++, val(std::string("Velocity")));return arr;@@ -2296,6 +2369,14 @@ static_assert(offsetof(esengine::ecs::UINode, insetLeft) == 112, "ABI offset dristatic_assert(offsetof(esengine::ecs::UINode, insetTop) == 120, "ABI offset drift: esengine::ecs::UINode.insetTop (EHT expected 120)");static_assert(offsetof(esengine::ecs::UINode, insetRight) == 128, "ABI offset drift: esengine::ecs::UINode.insetRight (EHT expected 128)");static_assert(offsetof(esengine::ecs::UINode, insetBottom) == 136, "ABI offset drift: esengine::ecs::UINode.insetBottom (EHT expected 136)");+static_assert(offsetof(esengine::ecs::UIScroll, enabled) == 0, "ABI offset drift: esengine::ecs::UIScroll.enabled (EHT expected 0)");+static_assert(offsetof(esengine::ecs::UIScroll, content) == 4, "ABI offset drift: esengine::ecs::UIScroll.content (EHT expected 4)");+static_assert(offsetof(esengine::ecs::UIScroll, horizontal) == 8, "ABI offset drift: esengine::ecs::UIScroll.horizontal (EHT expected 8)");+static_assert(offsetof(esengine::ecs::UIScroll, vertical) == 9, "ABI offset drift: esengine::ecs::UIScroll.vertical (EHT expected 9)");+static_assert(offsetof(esengine::ecs::UIScroll, movement) == 10, "ABI offset drift: esengine::ecs::UIScroll.movement (EHT expected 10)");+static_assert(offsetof(esengine::ecs::UIScroll, wheelSpeed) == 12, "ABI offset drift: esengine::ecs::UIScroll.wheelSpeed (EHT expected 12)");+static_assert(offsetof(esengine::ecs::UIScroll, dragScroll) == 16, "ABI offset drift: esengine::ecs::UIScroll.dragScroll (EHT expected 16)");+static_assert(offsetof(esengine::ecs::UIScroll, decelerationRate) == 20, "ABI offset drift: esengine::ecs::UIScroll.decelerationRate (EHT expected 20)");static_assert(offsetof(esengine::ecs::UIVisual, visualType) == 0, "ABI offset drift: esengine::ecs::UIVisual.visualType (EHT expected 0)");static_assert(offsetof(esengine::ecs::UIVisual, texture) == 4, "ABI offset drift: esengine::ecs::UIVisual.texture (EHT expected 4)");static_assert(offsetof(esengine::ecs::UIVisual, color) == 8, "ABI offset drift: esengine::ecs::UIVisual.color (EHT expected 8)");@@ -2317,7 +2398,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "52526b76662ebd4a";+static const char* kEsAbiLayoutHash = "638b897738f9c7db";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/UIScroll.hpp b/src/esengine/ecs/components/UIScroll.hppnew file mode 100644index 000000000..1f7431c65--- /dev/null+++ b/src/esengine/ecs/components/UIScroll.hpp@@ -0,0 +1,62 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+#pragma once++#include "../../core/Types.hpp"+#include "../../core/Reflection.hpp"++namespace esengine::ecs {++ES_ENUM()+enum class ScrollMovement : u8 {+ /** Stop dead at the ends. */+ Clamped,+ /** Overshoot and spring back — the touch-UI feel. */+ Elastic+};++/**+ * A scrollable viewport, authored in the scene.+ *+ * The behaviour lives in the SDK's UI behaviour plugin, which attaches a+ * ScrollContainer to any entity carrying this component: wheel and drag move+ * `content` inside this node's box, which clips it (pair with a UIMask — the+ * ScrollView template does).+ *+ * It exists because scrolling used to be reachable only by CONSTRUCTING the+ * ScrollView widget from game code. A scene could describe the parts of a+ * scroll area — the clipped box, the oversized child — but not the fact that it+ * scrolls, so a ScrollView dropped from the editor's Create menu sat there.+ */+ES_COMPONENT()+struct UIScroll {+ ES_PROPERTY()+ bool enabled{true};++ /** The child that moves. Unset ⇒ this node's first child. */+ ES_PROPERTY(entity_ref, tooltip="The child that scrolls inside this node. Leave empty to use the first child.")+ u32 content{0};++ ES_PROPERTY()+ bool horizontal{false};+ ES_PROPERTY()+ bool vertical{true};++ ES_PROPERTY(tooltip="Clamped stops at the ends; Elastic overshoots and springs back.")+ ScrollMovement movement{ScrollMovement::Clamped};++ /** Wheel notches → pixels, and whether a drag inside the box scrolls it. */+ ES_PROPERTY(min=0)+ f32 wheelSpeed{1.0f};+ ES_PROPERTY()+ bool dragScroll{true};++ /**+ * How fast a flick decays, as the fraction of velocity kept per second.+ * 0 ends the flick on release; the default is the usual touch-UI glide.+ */+ ES_PROPERTY(min=0, max=1, tooltip="Fraction of flick velocity kept per second. 0 stops on release.")+ f32 decelerationRate{0.135f};+};++} // namespace esengine::ecsdiff --git a/tools/eht/parser.py b/tools/eht/parser.pyindex 2bd4052c3..e8b9cc947 100644--- a/tools/eht/parser.py+++ b/tools/eht/parser.py@@ -83,6 +83,13 @@ class CppParser:self._parse_enums(content, namespace)self._parse_components(content, namespace, filepath)+ RE_COMMENT = re.compile(r'/\*.*?\*/|//[^\n]*', re.DOTALL)++ @classmethod+ def _strip_comments(cls, text: str) -> str:+ """Blank out C and C++ comments, keeping the text's length and lines."""+ return cls.RE_COMMENT.sub(lambda m: re.sub(r'[^\n]', ' ', m.group(0)), text)+def _parse_enums(self, content: str, namespace: str) -> None:for match in self.RE_ENUM.finditer(content):enum_name = match.group(1)@@ -95,7 +102,12 @@ class CppParser:if brace_end == -1:continue- enum_body = content[brace_start + 1:brace_end]+ # Comments first: the value pattern is "a word, optionally = N", which+ # every word of a doc comment also matches. A member documented in+ # place ("/** Overshoot and spring back. */") otherwise contributes+ # `Overshoot`, `and`, `spring`… as enum values, and the generated C+++ # then names members that do not exist.+ enum_body = self._strip_comments(content[brace_start + 1:brace_end])values = [m.group(1) for m in self.RE_ENUM_VALUE.finditer(enum_body) if m.group(1)]self.enums.append(Enum(