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): bound scrollbar geometry for empty viewports

yhhf73d11243bab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 309c5b3b3..a3b469df0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Empty and collapsed scroll views keep finite scrollbar geometry.** Thumb sizing handles zero content without dividing by zero and clamps the minimum thumb length to the available track. Clearing a list or collapsing its viewport no longer writes Infinity or NaN into native UI nodes, and tiny viewports keep their thumbs inside the track before normal sizing resumes on restore.
+
- **Idle scrollbars stop forcing UI layout work.** Overlay thumbs write their node geometry only when position, length or units change, including during fade-out and after becoming invisible. Comparisons use the native float precision so fractional thumb sizes settle instead of dirtying layout every frame; scrolling and viewport/content resizing still refresh their geometry.
- **Running tilemaps follow published tileset updates.** Tileset publication versions invalidate each app's cached render table, animations and collision model after a successful replacement, without requiring a reference edit or scene reload. Failed replacements keep the working version; unchanged frames read only a version counter and avoid rebuilding the table or resolving resource paths again.
diff --git a/sdk/src/ui/behavior/scrollbar.ts b/sdk/src/ui/behavior/scrollbar.ts
index ef50c4435..a18fd7047 100644
--- a/sdk/src/ui/behavior/scrollbar.ts
+++ b/sdk/src/ui/behavior/scrollbar.ts
@@ -70,8 +70,10 @@ function layoutThumb(
alpha: number,
): void {
if (!world.valid(thumb)) return;
- const len = Math.max(THUMB_MIN_LENGTH, (viewportLen / contentLen) * viewportLen);
- const range = Math.max(0, viewportLen - len);
+ const track = Math.max(0, viewportLen);
+ const proportional = contentLen > 0 ? (track / contentLen) * track : track;
+ const len = Math.min(track, Math.max(THUMB_MIN_LENGTH, proportional));
+ const range = Math.max(0, track - len);
const along = maxOffset > 0 ? (offset / maxOffset) * range : 0;
const n = world.get(thumb, UINode) as UINodeData;
diff --git a/sdk/tests/ui-scroll-motion-wasm.test.ts b/sdk/tests/ui-scroll-motion-wasm.test.ts
index 78245400f..b7e9811a6 100644
--- a/sdk/tests/ui-scroll-motion-wasm.test.ts
+++ b/sdk/tests/ui-scroll-motion-wasm.test.ts
@@ -60,6 +60,31 @@ describe.skipIf(!HAS_WASM)('scroll motion ownership on real WASM', () => {
} finally { insert.mockRestore(); }
});
+ it('keeps native scrollbar dimensions finite when content and viewport become empty', async () => {
+ const scroll = new ScrollContainer({ viewportSize: { x: 100, y: 100 },
+ contentSize: { x: 300, y: 300 }, direction: 'both' });
+ plugin.attachScrollContainer(entity, scroll); await step(0);
+ scroll.scrollBy({ x: 50, y: 50 }); await step(0);
+ const { UINode } = await import('../src/ui/core/ui-node');
+ const thumbs = app.world.getEntitiesWithComponents([UINode]);
+ expect(thumbs).toHaveLength(2);
+ for (const size of [100, 0, 10]) {
+ scroll.setSizes({ x: size, y: size }, { x: 0, y: 0 }); await step(0);
+ for (const thumb of thumbs) {
+ const n = app.world.get(thumb, UINode);
+ for (const dimension of [n.width, n.height, n.insetTop, n.insetLeft]) {
+ expect(Number.isFinite(dimension.value)).toBe(true);
+ }
+ }
+ }
+ scroll.setSizes({ x: 100, y: 100 }, { x: 300, y: 300 });
+ scroll.scrollBy({ x: 50, y: 50 }); await step(0);
+ for (const thumb of thumbs) {
+ const n = app.world.get(thumb, UINode);
+ expect(Math.max(n.width.value, n.height.value)).toBeCloseTo(100 / 3);
+ }
+ });
+
it('a replaced container does not inherit an active pointer drag', async () => {
const old = container(); plugin.attachScrollContainer(entity, old); await drag();
expect(old.getOffset().y).toBe(80);
diff --git a/sdk/tests/ui-scrollbar.test.ts b/sdk/tests/ui-scrollbar.test.ts
index 9254a3e74..31ba91803 100644
--- a/sdk/tests/ui-scrollbar.test.ts
+++ b/sdk/tests/ui-scrollbar.test.ts
@@ -134,6 +134,24 @@ describe('UIScrollbarSystem', () => {
expect(writes.mock.calls.filter(([, component]) => component === UINode)).toHaveLength(1);
});
+ it.each([
+ [{ x: 100, y: 100 }, { x: 100, y: 0 }],
+ [{ x: 100, y: 0 }, { x: 100, y: 0 }],
+ [{ x: 100, y: 10 }, { x: 100, y: 300 }],
+ ])('keeps resized thumb geometry finite and within its viewport (%j, %j)', (viewportSize, contentSize) => {
+ tick(); scroll.scrollBy({ x: 0, y: 50 }); tick();
+ const thumb = thumbs()[0];
+ scroll.setSizes(viewportSize, contentSize); tick();
+ const n = world.get(thumb, UINode) as { height: { value: number }; insetTop: { value: number } };
+ expect(Number.isFinite(n.height.value)).toBe(true);
+ expect(Number.isFinite(n.insetTop.value)).toBe(true);
+ expect(n.height.value).toBeGreaterThanOrEqual(0);
+ expect(n.height.value).toBeLessThanOrEqual(viewportSize.y);
+ scroll.setSizes({ x: 100, y: 100 }, { x: 100, y: 300 });
+ scroll.scrollBy({ x: 0, y: 50 }); tick();
+ expect((world.get(thumb, UINode) as { height: { value: number } }).height.value).toBeCloseTo(100 / 3);
+ });
+
it('a horizontal-only container never grows a vertical thumb', () => {
registry.detach(viewport as number);
const h = new ScrollContainer({
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 226480f19..3d730ac18 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): bound scrollbar geometry for empty viewports':
+ { note: 'Empty and collapsed scroll views keep finite scrollbar geometry.' },
'perf(ui): avoid geometry writes for idle scrollbar thumbs':
{ note: 'Idle scrollbars stop forcing UI layout work.' },
'fix(tilemap): refresh layers after tileset publication changes':