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-layout-integration.test.ts
* @brief Integration tests: App.tick() drives the single-pass UINode Yoga
* layout via the real WASM module.
*
* Requires pre-built WASM at build/wasm/web/esengine.wasm.
* Run `node build-tools/cli.js build -t web` first if missing.
*/
import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
import { log } from '../src/util/logger';
import { App } from '../src/app/app';
import { UINode, type UINodeData } from '../src/ui/core/ui-node';
import { FlexContainer, type FlexContainerData } from '../src/ui/layout/flex';
import { Canvas } from '../src/ecs/component';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { ScreenLayout } from '../src/ui/core/screen-layout';
import { uiLayoutPlugin } from '../src/ui/layout/layout';
import { uiRenderOrderPlugin } from '../src/ui/render/render-order';
import { defineSystem, Schedule } from '../src/ecs/system';
import { Time } from '../src/ecs/resource';
import { Transform, Sprite } from '../src/ecs/component';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
// The SDK's own dimension factories, not hand-written {value, unit} pairs: the
// unit numbers written a second time here are a second answer, and the engine
// this drives reads the first one.
import { px, percent as pct, auto, type Dimension } from '../src/ui/core/dimension';
/** A complete UINode value-object (embind requires every member present). */
function node(over: Partial<UINodeData> = {}): UINodeData {
return {
position: 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(),
...over,
} as UINodeData;
}
/** Stretch to fill the parent box (Absolute + inset 0 on all edges). */
function fillNode(): UINodeData {
return node({ position: 1, insetLeft: px(0), insetTop: px(0), insetRight: px(0), insetBottom: px(0) });
}
/** Fixed-size in-flow box. Annotated, so a `Dimension` that grew a field or
* renamed one fails here rather than at whatever reads it next. */
function sizedNode(w: number, h: number): UINodeData {
const width: Dimension = px(w);
const height: Dimension = px(h);
return node({ width, height });
}
/** Fill the parent inset by `n` px on every edge (Absolute). */
function insetNode(n: number): UINodeData {
return node({ position: 1, insetLeft: px(n), insetTop: px(n), insetRight: px(n), insetBottom: px(n) });
}
function makeTransform(x = 0, y = 0) {
return {
position: { x, y, z: 0 },
rotation: { x: 0, y: 0, z: 0, w: 1 },
scale: { x: 1, y: 1, z: 1 },
};
}
/** A complete FlexContainer value-object (embind requires every member present). */
function flex(over: Partial<FlexContainerData> = {}): FlexContainerData {
return {
direction: 0, wrap: 0, justifyContent: 0, alignItems: 3, alignContent: 0,
gap: { x: 0, y: 0 }, padding: { left: 0, top: 0, right: 0, bottom: 0 },
...over,
} as FlexContainerData;
}
function makeSprite(w = 100, h = 100) {
return {
texture: 0,
color: { r: 1, g: 1, b: 1, a: 1 },
size: { x: w, y: h },
uvOffset: { x: 0, y: 0 },
uvScale: { x: 1, y: 1 },
layer: 0,
flipX: false,
flipY: false,
};
}
describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () => {
let module: ESEngineModule;
beforeEach(() => { vi.spyOn(log, 'error'); });
afterEach(() => {
// App reports system errors rather than rejecting tick; they must fail
// this integration suite even when a Promise resolves successfully.
try { expect(log.error).not.toHaveBeenCalled(); }
finally { vi.restoreAllMocks(); }
});
beforeAll(async () => {
module = await loadWasmModule();
});
function createEditorApp(): { app: App; registry: CppRegistry } {
const app = App.new();
const registry = new module.Registry() as unknown as CppRegistry;
app.connectCpp(registry, module);
app.insertResource(UICameraInfo, {
viewProjection: new Float32Array(16),
vpX: 0, vpY: 0, vpW: 0, vpH: 0,
screenW: 0, screenH: 0,
worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,
worldMouseX: 0, worldMouseY: 0,
valid: false,
revision: 1,
});
app.insertResource(ScreenLayout, { ...ScreenLayout._default });
app.addPlugin(uiLayoutPlugin);
app.addPlugin(uiRenderOrderPlugin);
return { app, registry };
}
function disposeApp(app: App, registry: CppRegistry): void {
const world = app.world;
for (const e of world.getAllEntities()) {
try { world.despawn(e); } catch (_) {}
}
world.disconnectCpp();
(registry as unknown as { delete(): void }).delete();
}
// The box UI lays out in is the SCREEN's, not a camera's — a camera has no
// way to reach it (see ui/core/screen-layout.ts).
function setCanvasRect(app: App, left: number, bottom: number, right: number, top: number): void {
const screen = app.getResource(ScreenLayout);
screen.left = left;
screen.bottom = bottom;
screen.right = right;
screen.top = top;
screen.safeLeft = left;
screen.safeBottom = bottom;
screen.safeRight = right;
screen.safeTop = top;
screen.scale = 1;
screen.viewportW = right - left;
screen.viewportH = top - bottom;
screen.valid = true;
}
const nodeW = (registry: CppRegistry, e: number) => module.getUINodeComputedWidth!(registry, e);
const nodeH = (registry: CppRegistry, e: number) => module.getUINodeComputedHeight!(registry, e);
it('should call uiLayout_update via tick without error', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
setCanvasRect(app, -400, -300, 400, 300);
await expect(app.tick(1 / 60)).resolves.toBeUndefined();
expect(nodeW(registry, root)).toBeCloseTo(800, 3);
expect(nodeH(registry, root)).toBeCloseTo(600, 3);
disposeApp(app, registry);
});
it('lays out the first paused frame, resizes, and applies edits before rendering', async () => {
const { app, registry } = createEditorApp();
try {
const world = app.world, root = world.spawn(), child = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
world.insert(root, Sprite, makeSprite());
world.setParent(child, root);
world.insert(child, UINode, insetNode(10));
world.insert(child, Transform, makeTransform());
world.insert(child, Sprite, makeSprite());
const widths: number[] = [];
let updates = 0;
app.addSystem(defineSystem([], () => { updates++; }));
app.addSystemToSchedule(Schedule.Last, defineSystem([], () => {
widths.push(nodeW(registry, child));
}));
app.setPaused(true);
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(0.1);
expect(widths).toEqual([780]);
expect(registry.getSprite(child).layer).toBeGreaterThan(registry.getSprite(root).layer);
setCanvasRect(app, -640, -360, 640, 360);
await app.tick(0.1);
world.set(child, UINode, insetNode(30));
await app.tick(0.1);
expect(widths).toEqual([780, 1260, 1220]);
expect(nodeH(registry, child)).toBe(660);
expect(updates).toBe(0);
expect(app.getResource(Time).elapsed).toBe(0);
} finally {
disposeApp(app, registry);
}
});
it('should compute layout for child UINode entities', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
const child = world.spawn();
world.setParent(child, root);
world.insert(child, UINode, insetNode(10));
world.insert(child, Transform, makeTransform());
world.insert(child, Sprite, makeSprite());
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
expect(nodeW(registry, child)).toBeCloseTo(780, 0);
expect(nodeH(registry, child)).toBeCloseTo(580, 0);
disposeApp(app, registry);
});
it('should update render order after tick', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
world.insert(root, Sprite, makeSprite(800, 600));
const child = world.spawn();
world.setParent(child, root);
world.insert(child, UINode, sizedNode(100, 100));
world.insert(child, Transform, makeTransform());
world.insert(child, Sprite, makeSprite());
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
const rootSprite = registry.getSprite(root);
const childSprite = registry.getSprite(child);
expect(childSprite.layer).toBeGreaterThan(rootSprite.layer);
disposeApp(app, registry);
});
it('should handle 50%-width fill for slider-like entities', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
const background = world.spawn();
world.setParent(background, root);
world.insert(background, UINode, fillNode());
world.insert(background, Transform, makeTransform());
world.insert(background, Sprite, makeSprite(200, 30));
const fill = world.spawn();
world.setParent(fill, background);
world.insert(fill, UINode, node({
position: 1,
insetLeft: px(0), insetTop: px(0),
width: pct(50), height: pct(100),
}));
world.insert(fill, Transform, makeTransform());
world.insert(fill, Sprite, makeSprite(100, 30));
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
const fillW = nodeW(registry, fill);
const fillH = nodeH(registry, fill);
const bgW = nodeW(registry, background);
expect(fillW).toBeGreaterThan(0);
expect(fillH).toBeGreaterThan(0);
expect(fillW).toBeCloseTo(bgW * 0.5, 0);
disposeApp(app, registry);
});
it('should handle multiple tick calls without error', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
setCanvasRect(app, -400, -300, 400, 300);
for (let i = 0; i < 60; i++) {
await expect(app.tick(1 / 60)).resolves.toBeUndefined();
}
expect(nodeW(registry, root)).toBeCloseTo(800, 3);
expect(nodeH(registry, root)).toBeCloseTo(600, 3);
disposeApp(app, registry);
});
it('should skip layout when UICameraInfo.valid is false', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
const cam = app.getResource(UICameraInfo);
cam.valid = false;
await expect(app.tick(1 / 60)).resolves.toBeUndefined();
expect(nodeW(registry, root)).toBe(0);
disposeApp(app, registry);
});
it('Canvas without UINode: layout should not overwrite Transform positions', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
// Root is a Canvas but has no UINode → it is not a layout root, so its
// subtree is never laid out and the child Transform is left untouched.
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, Transform, makeTransform());
const child = world.spawn();
world.setParent(child, root);
world.insert(child, UINode, sizedNode(200, 100));
world.insert(child, Transform, makeTransform(50, 75));
world.insert(child, Sprite, makeSprite());
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
const t = registry.getTransform(child);
expect(t.position.x).toBeCloseTo(50, 1);
expect(t.position.y).toBeCloseTo(75, 1);
disposeApp(app, registry);
});
// The skip-when-clean gate keys the solve off a structure signature + camera
// rect + a TS-supplied property-dirty flag (UINode/FlexContainer change) + a
// tween-activity scan. These assert the two failure modes that gate can have:
// a bare field edit (no structural change) must still re-solve, and a clean
// frame must leave the computed output intact.
it('gate: a property edit with no structural change still re-solves', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, Transform, makeTransform());
const child = world.spawn();
world.setParent(child, root);
world.insert(child, UINode, sizedNode(100, 50));
world.insert(child, Transform, makeTransform());
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
expect(nodeW(registry, child)).toBeCloseTo(100, 0);
// Same entity set (identical structure signature) — only the width field
// changes. A gate that trusted structure alone would wrongly skip here.
// (insert is the in-place update door for a builtin the entity already has;
// set is emplace-only for existing builtins.)
world.insert(child, UINode, sizedNode(240, 50));
await app.tick(1 / 60);
expect(nodeW(registry, child)).toBeCloseTo(240, 0);
// Nothing changed this frame → the retained output must be preserved.
await app.tick(1 / 60);
expect(nodeW(registry, child)).toBeCloseTo(240, 0);
disposeApp(app, registry);
});
it('gate: a FlexContainer edit repositions children without a structural change', async () => {
const { app, registry } = createEditorApp();
const world = app.world;
const root = world.spawn();
world.insert(root, Canvas, {});
world.insert(root, UINode, fillNode());
world.insert(root, FlexContainer, flex({ direction: 1 })); // Column
world.insert(root, Transform, makeTransform());
const a = world.spawn();
world.setParent(a, root);
world.insert(a, UINode, sizedNode(100, 50));
world.insert(a, Transform, makeTransform());
const b = world.spawn();
world.setParent(b, root);
world.insert(b, UINode, sizedNode(100, 50));
world.insert(b, Transform, makeTransform());
setCanvasRect(app, -400, -300, 400, 300);
await app.tick(1 / 60);
const startY = registry.getTransform(b).position.y;
// justify-content Start → End packs the column to the bottom: 'b' moves.
world.insert(root, FlexContainer, flex({ direction: 1, justifyContent: 2 }));
await app.tick(1 / 60);
const endY = registry.getTransform(b).position.y;
expect(Math.abs(endY - startY)).toBeGreaterThan(1);
disposeApp(app, registry);
});
});