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.

4.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/layout/layout.ts
 * @brief   Layout concept — the Yoga-backed layout driver.
 *
 * Owns the PreUpdate `UILayoutSystem` (drives the C++ Yoga pass via
 * `uiLayout_update` + `transform_update`) plus the PostUpdate late pass
 * that re-solves after scroll/list mutations. Co-located with the
 * `flex`/`safe-area` schemas in this module.
 */
import type { App, Plugin } from '../../app/app';
import { registerComponent } from '../../ecs/component';
import { defineSystem, Schedule } from '../../ecs/system';
import { SystemLabel } from '../../ecs/systemLabels';
import { Res } from '../../ecs/resource';
import { UINode } from '../core/ui-node';
import { UIVisual } from '../core/ui-visual';
import { FlexContainer } from './flex';
import { ScreenLayout } from '../core/screen-layout';
import type { ScreenLayoutData } from '../core/screen-layout';
import { UILayoutGeneration } from './ui-layout-generation';
import type { UILayoutGenerationData } from './ui-layout-generation';
import type { CppRegistry } from '../../wasm';
import { engineApi } from '../../ecs/bridge/engineApi';
import { initUIHelpers } from '../util/helpers';

export class UILayoutPlugin implements Plugin {
    name = 'uiLayout';
    readonly profileDomain = 'ui';

    build(app: App): void {
        registerComponent('UINode', UINode);
        registerComponent('UIVisual', UIVisual);
        registerComponent('FlexContainer', FlexContainer);

        const world = app.world;
        // The wasm module on the web, the native host's bindings on a device —
        // the layout pass is the same either way.
        const engine = engineApi(app);
        const registry = world.getCppRegistry() as CppRegistry;

        initUIHelpers(engine, registry);

        const layoutGen: UILayoutGenerationData = { generation: 0 };
        app.insertResource(UILayoutGeneration, layoutGen);

        // Track UINode/FlexContainer edits so an authored change is an O(1) signal
        // the C++ solve honours (skip-when-clean). Every input write goes through
        // world.set / insert / Mut-writeback, which record the change; C++ writes
        // only layout OUTPUTS, and tween-driven Transform writes are covered by the
        // engine's own anim_override_ scan — so this pair is the complete authored
        // property signal.
        world.enableChangeTracking(UINode);
        world.enableChangeTracking(FlexContainer);

        // Ticks are per-frame, and both passes run within one tick, so a change can
        // still land at the current tick after this check. Report changes strictly
        // after `solvedTick`, then only advance the watermark to the PREVIOUS tick —
        // anyChangedSince uses '>', so using the current tick would drop a same-frame
        // write. The one extra solve this costs while a change settles is negligible.
        let solvedTick = -1;
        const propertyDirty = (): boolean => {
            const dirty = world.anyChangedSince(UINode, solvedTick)
                       || world.anyChangedSince(FlexContainer, solvedTick);
            solvedTick = world.getWorldTick() - 1;
            return dirty;
        };

        // The box is the SCREEN's: the design resolution fitted to the viewport,
        // centred on the origin — which is what makes a screen root's placement a
        // fact about the screen rather than about where something is looking.
        const layoutFn = (screen: ScreenLayoutData) => {
            if (!screen.valid) return;
            engine?.uiLayout_update?.(
                registry,
                screen.left, screen.bottom,
                screen.right, screen.top,
                propertyDirty(),
            );
            world.ensureTransformsComposed();
            layoutGen.generation++;
        };

        const layoutOnlyFn = (screen: ScreenLayoutData) => {
            if (!screen.valid) return;
            engine?.uiLayout_update?.(
                registry,
                screen.left, screen.bottom,
                screen.right, screen.top,
                propertyDirty(),
            );
            layoutGen.generation++;
        };

        app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
            [Res(ScreenLayout)],
            layoutFn,
            { name: 'UILayoutSystem', runWhenPaused: true }
        ));

        // No transform pass after the late layout: nothing between PostUpdate and
        // render reads world transforms (UIRenderOrder walks hierarchy only), and
        // the renderer's ensureTransformsUpdated composes worlds before collect.
        app.addSystemToSchedule(Schedule.PostUpdate, defineSystem(
            [Res(ScreenLayout)],
            layoutOnlyFn,
            { name: 'UILayoutLateSystem', runWhenPaused: true }
        ), { runAfter: [SystemLabel.ListView], runBefore: [SystemLabel.UIRenderOrder] });
    }
}

export const uiLayoutPlugin = new UILayoutPlugin();