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): 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.mdx
index 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 m
world.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 code
![A UI Canvas laid out in the editor viewport](../../../assets/guides/en/ui-screen.png)
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
index 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 语义——逐视觉相乘而不是把子树离屏合成,这是每个 UI
world.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>
+
## 编辑器还是代码
![在编辑器视口里排好的一个 UI Canvas](../../../../assets/guides/zh/ui-screen.png)
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -1760,6 +1761,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -1789,6 +1791,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -1818,6 +1821,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -1768,6 +1769,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -1797,6 +1799,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -1826,6 +1829,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d3ad48a01..53e3bcce7 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1722,6 +1722,7 @@ addTransform: (entity: Entity, component: Transform) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 0e45d04ef..339bcee08 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -40,6 +40,7 @@ addTransform: (entity: Entity, component: Transform) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -73,6 +74,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -102,6 +104,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -131,6 +134,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 19af6df94..1865dfe78 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1722,6 +1722,7 @@ addTransform: (entity: Entity, component: Transform) => void
addUIInteraction: (entity: Entity, component: UIInteraction) => void
addUIMask: (entity: Entity, component: UIMask) => void
addUINode: (entity: Entity, component: UINode) => void
+addUIScroll: (entity: Entity, component: UIScroll) => void
addUIVisual: (entity: Entity, component: UIVisual) => void
addVelocity: (entity: Entity, component: Velocity) => void
create: () => Entity
@@ -1755,6 +1756,7 @@ getTransform: (entity: Entity) => Transform
getUIInteraction: (entity: Entity) => UIInteraction
getUIMask: (entity: Entity) => UIMask
getUINode: (entity: Entity) => UINode
+getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
hasBitmapText: (entity: Entity) => boolean
@@ -1784,6 +1786,7 @@ hasTransform: (entity: Entity) => boolean
hasUIInteraction: (entity: Entity) => boolean
hasUIMask: (entity: Entity) => boolean
hasUINode: (entity: Entity) => boolean
+hasUIScroll: (entity: Entity) => boolean
hasUIVisual: (entity: Entity) => boolean
hasVelocity: (entity: Entity) => boolean
removeBitmapText: (entity: Entity) => void
@@ -1813,6 +1816,7 @@ removeTransform: (entity: Entity) => void
removeUIInteraction: (entity: Entity) => void
removeUIMask: (entity: Entity) => void
removeUINode: (entity: Entity) => void
+removeUIScroll: (entity: Entity) => void
removeUIVisual: (entity: Entity) => void
removeVelocity: (entity: Entity) => void
setParent: (child: Entity, parent: Entity) => void
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.cpp
index 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::s
else 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::st
else 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::str
else 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::stri
else 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::st
if (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::st
if (!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.cpp
index 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 dri
static_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.hpp
new file mode 100644
index 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::ecs
diff --git a/tools/eht/parser.py b/tools/eht/parser.py
index 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(