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
// 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, vi } 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>();
const hidden = new Set<number>();
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,
getUINodeHiddenInTree: (_r: unknown, e: number) => hidden.has(e),
} 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, sizes, hidden };
}
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);
});
it('resizing both boxes preserves a still-valid scroll offset', async () => {
const { app, world, viewport, content, attached, sizes } = setup();
await app.tick(1 / 60);
const container = attached.get(viewport)!;
container.setOffset({ x: 0, y: 900 });
const changed = vi.fn(); container.onScroll(changed);
sizes.set(viewport, { w: 400, h: 600 });
sizes.set(content, { w: 400, h: 1500 });
await app.tick(1 / 60);
expect(container.getOffset().y).toBe(900);
expect(world.get(content, UINode).insetTop.value).toBe(-900);
expect(changed).not.toHaveBeenCalled();
});
it('shrinking both boxes emits only the final clamped offset', async () => {
const { app, viewport, content, attached, sizes } = setup();
await app.tick(1 / 60);
const container = attached.get(viewport)!;
container.setOffset({ x: 0, y: 900 });
const changed = vi.fn(); container.onScroll(changed);
sizes.set(viewport, { w: 400, h: 600 });
sizes.set(content, { w: 400, h: 800 });
await app.tick(1 / 60);
expect(changed.mock.calls).toEqual([[{ x: 0, y: 200 }]]);
});
it('retires an explicit content reference when its entity is destroyed', async () => {
const { app, world, viewport, content, attached } = setup();
world.update(viewport, UIScroll, scroll => { scroll.content = content; });
await app.tick(1 / 60);
world.despawn(content);
await app.tick(1 / 60);
expect(attached.has(viewport)).toBe(false);
});
it('does not recreate a removed content node through a retained container', async () => {
const { app, world, viewport, content, attached } = setup();
await app.tick(1 / 60);
const container = attached.get(viewport)!;
world.remove(content, UINode);
container.scrollBy({ x: 0, y: 120 });
expect(world.has(content, UINode)).toBe(false);
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(); }
});
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);
});
it('preserves scroll position while hidden layout boxes collapse to zero', async () => {
const { app, viewport, content, attached, sizes, hidden } = setup();
await app.tick(1 / 60);
const scroll = attached.get(viewport)!; scroll.setOffset({ x: 0, y: 120 });
hidden.add(viewport); sizes.set(viewport, { w: 0, h: 0 }); sizes.set(content, { w: 0, h: 0 });
await app.tick(1 / 60);
expect(scroll.getOffset().y).toBe(120);
hidden.delete(viewport); sizes.set(viewport, { w: 400, h: 300 }); sizes.set(content, { w: 400, h: 1200 });
await app.tick(1 / 60);
expect(attached.get(viewport)).toBe(scroll);
expect(scroll.getOffset().y).toBe(120);
});
});