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
fix(ui): apply live scroll settings and isolate replaced motion
yhh38d39f8f9347
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c62b3f3ad..6760d6058 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Scene scroll settings update while the game is running.** Changes to axes, wheel speed, drag enablement and movement settings rebuild the adopted container while preserving legal offsets. Disabling both axes suspends scrolling, reactivation restores the content position, and replaced containers cannot inherit an old pointer drag or fling.+- **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.diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.tsindex df4ab8e22..cf04e4e29 100644--- a/sdk/src/ui/behavior/plugin.ts+++ b/sdk/src/ui/behavior/plugin.ts@@ -153,14 +153,14 @@ export class UIBehaviorPlugin implements Plugin {);// Fling state per scroll entity, shared between the wheel and drag// systems so either input source interrupts a coast.- const dynamics = new Map<Entity, KineticScroll>();+ const dynamics = new Map<Entity, { container: ScrollContainer; motion: KineticScroll }>();const dynamicsFor = (entity: Entity, container: ScrollContainer): KineticScroll => {let d = dynamics.get(entity);- if (!d) {- d = new KineticScroll({ decelerationRate: container.getDecelerationRate() });+ if (!d || d.container !== container) {+ d = { container, motion: new KineticScroll({ decelerationRate: container.getDecelerationRate() }) };dynamics.set(entity, d);}- return d;+ return d.motion;};app.world.onDespawn((entity) => dynamics.delete(entity));@@ -209,7 +209,7 @@ export class UIBehaviorPlugin implements Plugin {const best = hoveredScrollTarget(false);if (best !== null) {const container = scrollContainers.get(best)!;- dynamics.get(best)?.stop(); // wheel takes over from a fling+ dynamics.get(best)?.motion.stop(); // wheel takes over from a flingconst speed = container.getWheelSpeed();container.scrollBy({ x: dx * speed, y: dy * speed });}@@ -221,6 +221,7 @@ export class UIBehaviorPlugin implements Plugin {// capture shape as DragSystem.let pendingEntity: Entity | null = null;let activeEntity: Entity | null = null;+ let capturedContainer: ScrollContainer | null = null;let grabStartWorld: Vec2 = { x: 0, y: 0 };let grabStartOffset: Vec2 = { x: 0, y: 0 };let lastOffset: Vec2 = { x: 0, y: 0 };@@ -230,6 +231,12 @@ export class UIBehaviorPlugin implements Plugin {(input: InputState, camera: UICameraData, time: TimeData, layout: ScreenLayoutData,overlay: ScreenOverlayData) => {if (!camera.valid && !overlay.active) return;+ const captured = activeEntity ?? pendingEntity;+ if (captured !== null && scrollContainers.get(captured) !== capturedContainer) {+ dynamics.get(captured)?.motion.stop();+ activeEntity = pendingEntity = null;+ capturedContainer = null;+ }// In the domain the grabbed container is laid out in — a scroll// subtracts a pointer from a transform, like a drag does.const pointerFor = (entity: Entity): { x: number; y: number } =>@@ -242,6 +249,7 @@ export class UIBehaviorPlugin implements Plugin {const best = hoveredScrollTarget(true);if (best !== null) {const container = scrollContainers.get(best)!;+ capturedContainer = container;dynamicsFor(best, container).stop();pendingEntity = best;grabStartWorld = pointerFor(best);@@ -309,13 +317,14 @@ export class UIBehaviorPlugin implements Plugin {}// Coast: tick flung containers; an axis the clamp stops is dead.- for (const [entity, dyn] of dynamics) {- if (!dyn.isCoasting()) continue;+ for (const [entity, state] of dynamics) {const container = scrollContainers.get(entity);- if (!container) {+ if (container !== state.container) {dynamics.delete(entity);continue;}+ const dyn = state.motion;+ if (!dyn.isCoasting()) continue;const delta = dyn.tick(time.delta);const before = container.getOffset();container.scrollBy(delta);diff --git a/sdk/src/ui/behavior/scroll.ts b/sdk/src/ui/behavior/scroll.tsindex e5d6b8abe..34d131e59 100644--- a/sdk/src/ui/behavior/scroll.ts+++ b/sdk/src/ui/behavior/scroll.ts@@ -32,6 +32,7 @@ interface Attached {container: ScrollContainer;content: Entity;contentRef: number;+ settings: UIScrollData;unsubscribe: () => void;}@@ -42,6 +43,12 @@ function directionOf(scroll: UIScrollData): 'both' | 'vertical' | 'horizontal' {return scroll.horizontal ? 'horizontal' : 'vertical';}+function sameSettings(a: UIScrollData, b: UIScrollData): boolean {+ return a.horizontal === b.horizontal && a.vertical === b.vertical+ && a.wheelSpeed === b.wheelSpeed && a.dragScroll === b.dragScroll+ && a.movement === b.movement && a.decelerationRate === b.decelerationRate;+}+export function createScrollAdoptSystem(world: World,engine: EngineApi | null,@@ -83,9 +90,13 @@ export function createScrollAdoptSystem(attached.delete(entity);};- const attach = (entity: Entity, scroll: UIScrollData, content = contentOf(entity, scroll)): void => {+ const attach = (entity: Entity, scroll: UIScrollData, content = contentOf(entity, scroll), initialOffset?: Vec2): void => {if (content == null || !world.valid(content) || !world.has(content, UINode)) return;-+ const node = world.get(content, UINode);+ const offset = initialOffset ?? {+ x: node.insetLeft.unit === 0 ? Math.max(0, -node.insetLeft.value) : 0,+ y: node.insetTop.unit === 0 ? Math.max(0, -node.insetTop.value) : 0,+ };const container = new ScrollContainer({viewportSize: size(entity),contentSize: size(content),@@ -93,19 +104,23 @@ export function createScrollAdoptSystem(wheelSpeed: scroll.wheelSpeed,dragScroll: scroll.dragScroll,decelerationRate: scroll.movement === ScrollMovement.Elastic ? scroll.decelerationRate : 0,+ initialOffset: offset,});// 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 applyOffset = (offset: Vec2): void => {const node = world.tryGet(content, UINode);if (!node) return;node.position = UIPositionType.Absolute;node.insetLeft = px(-offset.x);node.insetTop = px(-offset.y);world.insert(content, UINode, node);- });+ };+ const unsubscribe = container.onScroll(applyOffset);+ const clamped = container.getOffset();+ if (clamped.x !== offset.x || clamped.y !== offset.y) applyOffset(clamped);host.attachScrollContainer(entity, container);- attached.set(entity, { container, content, contentRef: scroll.content, unsubscribe });+ attached.set(entity, { container, content, contentRef: scroll.content, settings: { ...scroll }, unsubscribe });};return defineSystem([Query(UIScroll)], (query) => {@@ -116,7 +131,7 @@ export function createScrollAdoptSystem(for (const [entity, scroll] of query) {const data = scroll as UIScrollData;- if (!data.enabled) continue;+ if (!data.enabled || (!data.horizontal && !data.vertical)) continue;live.add(entity);const a = attached.get(entity);@@ -134,6 +149,12 @@ export function createScrollAdoptSystem(attach(entity, data, resolved);continue;}+ if (!sameSettings(a.settings, data)) {+ const offset = a.container.getOffset();+ detach(entity);+ attach(entity, data, resolved, offset);+ continue;+ }a.contentRef = data.content;const content = a.content;// Clamp against one complete layout, never mixed old/new extents.diff --git a/sdk/tests/ui-scroll-adopt.test.ts b/sdk/tests/ui-scroll-adopt.test.tsindex f970ade7b..06a48f3d2 100644--- a/sdk/tests/ui-scroll-adopt.test.ts+++ b/sdk/tests/ui-scroll-adopt.test.ts@@ -213,4 +213,50 @@ describe.skipIf(!HAS_WASM)('UIScroll adoption', () => {expect(read).not.toHaveBeenCalled();} finally { read.mockRestore(); }});++ it('applies live wheel and drag settings without losing the scroll position', async () => {+ const { app, world, viewport, content, attached } = setup();+ await app.tick(1 / 60);+ attached.get(viewport)!.setOffset({ x: 0, y: 120 });+ world.update(viewport, UIScroll, s => { s.wheelSpeed = 3; s.dragScroll = false; });+ await app.tick(1 / 60);+ expect(attached.get(viewport)!.getWheelSpeed()).toBe(3);+ expect(attached.get(viewport)!.getDragScroll()).toBe(false);+ expect(attached.get(viewport)!.getOffset().y).toBe(120);+ expect(world.get(content, UINode).insetTop.value).toBe(-120);+ });++ it('changes scroll axes and removes offsets on the locked axis', async () => {+ const { app, world, viewport, content, attached } = setup({}, { w: 800, h: 1200 });+ await app.tick(1 / 60);+ attached.get(viewport)!.setOffset({ x: 0, y: 120 });+ world.update(viewport, UIScroll, s => { s.horizontal = true; s.vertical = false; });+ await app.tick(1 / 60);+ attached.get(viewport)!.scrollBy({ x: 50, y: 50 });+ expect(attached.get(viewport)!.getOffset()).toEqual({ x: 50, y: 0 });+ expect(world.get(content, UINode).insetTop.value).toBeCloseTo(0);+ });++ it('disabling both axes suspends scrolling and reenabling preserves the position', async () => {+ const { app, world, viewport, attached } = setup();+ await app.tick(1 / 60);+ attached.get(viewport)!.setOffset({ x: 0, y: 120 });+ world.update(viewport, UIScroll, s => { s.vertical = false; });+ await app.tick(1 / 60);+ expect(attached.has(viewport)).toBe(false);+ world.update(viewport, UIScroll, s => { s.vertical = true; });+ await app.tick(1 / 60);+ expect(attached.get(viewport)!.getOffset().y).toBe(120);+ });++ it('applies changed movement decay to the next drag model', async () => {+ const { app, world, viewport, attached } = setup();+ await app.tick(1 / 60);+ world.update(viewport, UIScroll, s => { s.movement = ScrollMovement.Elastic; s.decelerationRate = .8; });+ await app.tick(1 / 60);+ expect(attached.get(viewport)!.getDecelerationRate()).toBeCloseTo(.8);+ world.update(viewport, UIScroll, s => { s.movement = ScrollMovement.Clamped; });+ await app.tick(1 / 60);+ expect(attached.get(viewport)!.getDecelerationRate()).toBe(0);+ });});diff --git a/sdk/tests/ui-scroll-motion-wasm.test.ts b/sdk/tests/ui-scroll-motion-wasm.test.tsnew file mode 100644index 000000000..f19540467--- /dev/null+++ b/sdk/tests/ui-scroll-motion-wasm.test.ts@@ -0,0 +1,56 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';+import { App, flushPendingRegistrations } from '../src/app/app';+import { AppContext, setDefaultContext } from '../src/ecs/context';+import { Input, InputState } from '../src/input/input';+import { UICameraInfo } from '../src/ui/core/ui-camera-info';+import { UIEvents, UIEventQueue } from '../src/ui/core/events';+import { UIInteraction } from '../src/ui/input/interactable';+import { UIBehaviorPlugin } from '../src/ui/behavior/plugin';+import { ScrollContainer } from '../src/ui/collection/scroll-container';+import type { CppRegistry, ESEngineModule } from '../src/wasm';+import type { Entity } from '../src/types';+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';++describe.skipIf(!HAS_WASM)('scroll motion ownership on real WASM', () => {+ let engine: ESEngineModule, registry: CppRegistry, app: App, plugin: UIBehaviorPlugin;+ let entity: Entity, input: InputState;+ const container = () => new ScrollContainer({ viewportSize: { x: 100, y: 100 },+ contentSize: { x: 100, y: 2000 }, decelerationRate: .135 });+ beforeAll(async () => { engine = await loadWasmModule(); });+ beforeEach(() => {+ setDefaultContext(new AppContext());+ registry = new engine.Registry(); app = App.new(); app.connectCpp(registry, engine);+ input = new InputState(); app.insertResource(Input, input);+ app.insertResource(UIEvents, new UIEventQueue());+ app.insertResource(UICameraInfo, { ...UICameraInfo._default, valid: true,+ vpW: 100, vpH: 100, screenW: 100, screenH: 100 });+ plugin = new UIBehaviorPlugin(); plugin.build(app); flushPendingRegistrations(app);+ entity = app.world.spawn(); app.world.insert(entity, UIInteraction, { hovered: true });+ });+ afterEach(() => { app.quit({ keepRenderer: true }); registry.delete(); });+ async function step(y: number) {+ app.getResource(UICameraInfo).worldMouseY = y;+ await app.tick(1 / 60); input.clearFrameState();+ }+ async function drag() {+ input.noteMouseDown(0); await step(0); await step(40); await step(80);+ }+ 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);+ const next = container(); plugin.attachScrollContainer(entity, next);+ await step(120);+ expect(next.getOffset().y).toBe(0);+ expect(old.getOffset().y).toBe(80);+ });+ it('a replaced container does not inherit the previous content fling', async () => {+ const old = container(); plugin.attachScrollContainer(entity, old); await drag();+ input.noteMouseUp(0); await step(100); await step(100);+ expect(old.getOffset().y).toBeGreaterThan(100);+ const next = container(); plugin.attachScrollContainer(entity, next);+ for (let i = 0; i < 10; i++) await step(100);+ expect(next.getOffset().y).toBe(0);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 264d51945..78e0bcfe5 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): apply live scroll settings and isolate replaced motion':+ { note: 'Scene scroll settings update while the game is running.' },'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':