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.

fix(ui): follow scroll content hierarchy and reference changes

yhh0057e0b02cbd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01c66507e..c62b3f3ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Scroll views follow content hierarchy edits.** Reparenting a live content node switches an implicit scroll view to its new first child, and clearing an explicit content reference restores first-child selection. Retired containers stop moving the previous content; unchanged hierarchies do not reread native child vectors every frame.
+
- **Scroll views retain valid offsets across simultaneous resizes.** Viewport and content dimensions update together before clamping, avoiding position jumps and duplicate scroll notifications. Destroyed content references detach their containers instead of leaving stale scroll targets.
- **Scene-authored scroll views receive hover and wheel input.** Hit testing no longer inserts hidden interaction components outside the SDK's component index. The interaction system owns creation and query invalidation, so wheel scrolling and per-frame hover/press state work for controls placed in the editor.
diff --git a/sdk/src/ui/behavior/scroll.ts b/sdk/src/ui/behavior/scroll.ts
index 4e70aca00..e5d6b8abe 100644
--- a/sdk/src/ui/behavior/scroll.ts
+++ b/sdk/src/ui/behavior/scroll.ts
@@ -31,6 +31,7 @@ export interface ScrollHost {
interface Attached {
container: ScrollContainer;
content: Entity;
+ contentRef: number;
unsubscribe: () => void;
}
@@ -48,6 +49,7 @@ export function createScrollAdoptSystem(
host: ScrollHost,
) {
const attached = new Map<Entity, Attached>();
+ let lastWorldVersion = -1;
/** The resolved box the layout pass produced, not the authored dimension. */
const size = (entity: Entity): Vec2 => ({
@@ -81,8 +83,7 @@ export function createScrollAdoptSystem(
attached.delete(entity);
};
- const attach = (entity: Entity, scroll: UIScrollData): void => {
- const content = contentOf(entity, scroll);
+ const attach = (entity: Entity, scroll: UIScrollData, content = contentOf(entity, scroll)): void => {
if (content == null || !world.valid(content) || !world.has(content, UINode)) return;
const container = new ScrollContainer({
@@ -104,10 +105,13 @@ export function createScrollAdoptSystem(
world.insert(content, UINode, node);
});
host.attachScrollContainer(entity, container);
- attached.set(entity, { container, content, unsubscribe });
+ attached.set(entity, { container, content, contentRef: scroll.content, unsubscribe });
};
return defineSystem([Query(UIScroll)], (query) => {
+ const version = world.getWorldVersion();
+ const topologyChanged = version !== lastWorldVersion;
+ lastWorldVersion = version;
const live = new Set<Entity>();
for (const [entity, scroll] of query) {
@@ -120,16 +124,17 @@ export function createScrollAdoptSystem(
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 = !world.valid(a.content) || !world.has(a.content, UINode)
- || (data.content !== 0 && (data.content as Entity) !== a.content);
+ const usable = world.valid(a.content) && world.has(a.content, UINode);
+ // Re-read implicit children only after structural edits or reference changes.
+ const resolved = data.content !== 0 ? data.content as Entity
+ : (topologyChanged || a.contentRef !== 0 || !usable) ? contentOf(entity, data) : a.content;
+ const swapped = !usable || resolved !== a.content;
if (swapped) {
detach(entity);
- attach(entity, data);
+ attach(entity, data, resolved);
continue;
}
+ a.contentRef = data.content;
const content = a.content;
// Clamp against one complete layout, never mixed old/new extents.
a.container.setSizes(size(entity), size(content));
diff --git a/sdk/tests/ui-scroll-adopt.test.ts b/sdk/tests/ui-scroll-adopt.test.ts
index ea4e7ac8f..f970ade7b 100644
--- a/sdk/tests/ui-scroll-adopt.test.ts
+++ b/sdk/tests/ui-scroll-adopt.test.ts
@@ -174,4 +174,43 @@ describe.skipIf(!HAS_WASM)('UIScroll adoption', () => {
await app.tick(1 / 60);
expect(attached.has(viewport)).toBe(false);
});
+
+ it('follows a new first child when the previous content is reparented alive', async () => {
+ const { app, world, viewport, content, attached, sizes } = setup();
+ await app.tick(1 / 60);
+ const old = attached.get(viewport)!;
+ const replacement = world.spawn(); world.insert(replacement, UINode, fullNode());
+ sizes.set(replacement, { w: 400, h: 800 });
+ world.removeParent(content); world.setParent(replacement, viewport);
+ await app.tick(1 / 60);
+ const current = attached.get(viewport)!;
+ expect(current).not.toBe(old);
+ current.scrollBy({ x: 0, y: 120 });
+ expect(world.get(replacement, UINode).insetTop.value).toBe(-120);
+ old.scrollBy({ x: 0, y: 120 });
+ expect(world.get(content, UINode).insetTop).toEqual(auto());
+ });
+
+ it('switches from an explicit reference back to the current first child', async () => {
+ const { app, world, viewport, content, attached, sizes } = setup();
+ const other = world.spawn(); world.insert(other, UINode, fullNode());
+ sizes.set(other, { w: 400, h: 800 }); world.setParent(other, viewport);
+ world.update(viewport, UIScroll, scroll => { scroll.content = other; });
+ await app.tick(1 / 60);
+ world.update(viewport, UIScroll, scroll => { scroll.content = 0; });
+ await app.tick(1 / 60);
+ attached.get(viewport)!.scrollBy({ x: 0, y: 120 });
+ expect(world.get(content, UINode).insetTop.value).toBe(-120);
+ expect(world.get(other, UINode).insetTop).toEqual(auto());
+ });
+
+ it('does not fetch native child vectors again while the hierarchy stays unchanged', async () => {
+ const { app, world } = setup();
+ await app.tick(1 / 60);
+ const read = vi.spyOn(world.getCppRegistry()!, 'getChildren');
+ try {
+ for (let i = 0; i < 100; i++) await app.tick(1 / 60);
+ expect(read).not.toHaveBeenCalled();
+ } finally { read.mockRestore(); }
+ });
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2c82a63b8..264d51945 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(ui): follow scroll content hierarchy and reference changes':
+ { note: 'Scroll views follow content hierarchy edits.' },
'fix(ui): resize scroll extents together and retire missing content':
{ note: 'Scroll views retain valid offsets across simultaneous resizes.' },
'fix(ui): keep hit testing from bypassing interaction membership':