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.

16.6 KB
Raw Blame
// 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);
    });
});