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.

12.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/controller/gear-apply.ts
 * @brief   The systems that turn controller pages into applied field values.
 *
 * Two systems:
 *
 *   • InteractionControllerDriverSystem — writes the `$interaction` controller's
 *     `current` page from pointer state (via `driverStateFor`), so a button
 *     built from UIController + gears gets normal/hover/pressed/disabled for free.
 *   • GearApplySystem — for every UIGear binding, resolves its controller's page,
 *     looks up the page's value, and writes it to the target field, snapping or
 *     tweening. It runs in edit mode too (not play-gated): setting a controller's
 *     `current` in the editor immediately previews that page, for free.
 *
 * The read/write/lerp helpers are pure and exported so unit tests (and a future
 * editor preview path) can exercise the value logic without a World.
 */
import { defineSystem, type SystemDef } from '../../ecs/system';
import { getComponent, Parent } from '../../ecs/component';
import { Res, Time, type TimeData } from '../../ecs/resource';
import { applyEasing } from '../../animation/Easing';
import { EntityStateMap } from '../util/helpers';
import { Interactable, UIInteraction, type InteractableData, type UIInteractionData } from '../input/interactable';
import { Focusable, FocusManager, type FocusManagerState } from '../input/focusable';
import type { Entity } from '../../types';
import type { World } from '../../ecs/world';
import {
    UIController,
    INTERACTION_CONTROLLER,
    getControllerPage,
    type UIControllerData,
} from './ui-controller';
import { UIGear, type GearValue, type UIGearData } from './ui-gear';

// ─── Pure field/value helpers ───────────────────────────────────────────────

/** Read the value at a dot-path (returns undefined if the path doesn't resolve). */
export function readFieldPath(data: Record<string, unknown>, path: string): unknown {
    const parts = path.split('.');
    let cur: any = data;
    for (const p of parts) {
        if (cur == null || typeof cur !== 'object') return undefined;
        cur = cur[p];
    }
    return cur;
}

/**
 * Write `value` at a dot-path. Object values (Color/Vec) are shallow-cloned so a
 * shared authored value never becomes aliased across entities. Returns false
 * (writes nothing) when the path doesn't resolve to an existing leaf.
 */
export function writeFieldPath(data: Record<string, unknown>, path: string, value: unknown): boolean {
    const parts = path.split('.');
    let cur: any = data;
    for (let i = 0; i < parts.length - 1; i++) {
        cur = cur[parts[i]];
        if (cur == null || typeof cur !== 'object') return false;
    }
    const last = parts[parts.length - 1];
    if (cur == null || typeof cur !== 'object' || !(last in cur)) return false;
    cur[last] = (value !== null && typeof value === 'object') ? { ...(value as object) } : value;
    return true;
}

/** Numbers, colours (`r`…), and vectors (`x`…) interpolate; everything else snaps. */
export function isLerpable(v: unknown): boolean {
    if (typeof v === 'number') return true;
    if (v !== null && typeof v === 'object') {
        const o = v as Record<string, unknown>;
        return typeof o.r === 'number' || typeof o.x === 'number';
    }
    return false;
}

function lerp(a: number, b: number, t: number): number {
    return a + (b - a) * t;
}

/**
 * Interpolate between two gear values at `t`. Handles number, Color (r/g/b/a),
 * and Vec2/Vec3 (x/y/z); any non-numeric or shape-mismatched pair falls through
 * to the target (a snap). Type is chosen from `to` (the authored destination).
 */
export function lerpGearValue(from: unknown, to: unknown, t: number): unknown {
    if (typeof to === 'number') {
        return typeof from === 'number' ? lerp(from, to, t) : to;
    }
    if (to !== null && typeof to === 'object' && from !== null && typeof from === 'object') {
        const f = from as Record<string, number>;
        const g = to as Record<string, number>;
        if (typeof g.r === 'number' && typeof f.r === 'number') {
            return {
                r: lerp(f.r, g.r, t), g: lerp(f.g, g.g, t),
                b: lerp(f.b, g.b, t), a: lerp(f.a ?? 1, g.a ?? 1, t),
            };
        }
        if (typeof g.x === 'number' && typeof f.x === 'number') {
            const out: Record<string, number> = { x: lerp(f.x, g.x, t), y: lerp(f.y, g.y, t) };
            if ('z' in g) out.z = lerp(f.z ?? 0, g.z ?? 0, t);
            return out;
        }
    }
    return to;
}

// ─── Systems ────────────────────────────────────────────────────────────────

/**
 * Pages the `$interaction` driver owns. If the controller's `current` holds any
 * other value, user code set it (e.g. "loading" via {@link setButtonState}) and
 * the driver must not steal it back.
 */
const DRIVER_OWNED_PAGES: ReadonlySet<string> = new Set([
    '', 'normal', 'hover', 'pressed', 'disabled', 'focused',
]);

/**
 * Pure derivation: choose the interaction page a hit-test pass implies.
 * Extracted so unit tests can cover the branching without a World.
 *
 * `focusVisible` is `:focus-visible`, not "has focus": a pointer press moves focus
 * too, and a control that keeps a focus look after being clicked reads as stuck —
 * the pointer is long gone and the button is still lit until you click elsewhere.
 * See {@link FocusManagerState.focusVisible}.
 */
export function driverStateFor(
    enabled: boolean,
    interaction: UIInteractionData | null,
    focusVisible = false,
): string {
    if (!enabled) return 'disabled';
    if (interaction?.pressed) return 'pressed';
    if (interaction?.hovered) return 'hover';
    if (focusVisible) return 'focused';
    return 'normal';
}

/**
 * Writes the `$interaction` controller's page from Interactable + UIInteraction.
 * Only touches entities that actually declare a `$interaction` controller, only
 * to a page the controller lists — so a controller with a custom page set (say
 * no "disabled") is never forced into a page it doesn't have — and never while
 * `current` holds a user-managed page outside {@link DRIVER_OWNED_PAGES}.
 */
export function createInteractionControllerDriverSystem(world: World): SystemDef {
    return defineSystem([Res(FocusManager)], (focus: FocusManagerState) => {
        for (const e of world.getEntitiesWithComponents([Interactable, UIController])) {
            const data = world.get(e, UIController) as UIControllerData;
            const ctrl = data.controllers.find(c => c.name === INTERACTION_CONTROLLER);
            if (!ctrl || !DRIVER_OWNED_PAGES.has(ctrl.current)) continue;

            const inter = world.has(e, UIInteraction)
                ? (world.get(e, UIInteraction) as UIInteractionData)
                : null;
            const interactable = world.get(e, Interactable) as InteractableData;
            // The manager, not Focusable.isFocused: only it knows HOW focus arrived,
            // and a pointer-focused control must not wear the focus look.
            const focusVisible = world.has(e, Focusable) && focus.isVisiblyFocused(e);
            const next = driverStateFor(interactable.enabled, inter, focusVisible);
            if (next !== ctrl.current && ctrl.pages.includes(next)) {
                ctrl.current = next;
                world.insert(e, UIController, data);
            }
        }
    }, { name: 'InteractionControllerDriverSystem' });
}

/** Per-binding transition bookkeeping (kept out of the ECS, GC'd with the entity). */
interface BindingTx {
    /** Page this transition is heading to / settled at. */
    page: string;
    elapsed: number;
    /** Snapshot of the field value when the page changed (the tween's `from`). */
    from: unknown;
    /** Settled: value written, skip work until the page changes again. */
    done: boolean;
}

/**
 * Applies every UIGear binding from its controller's current page. Snaps when the
 * binding has no tween (or the value can't interpolate); otherwise eases from the
 * field's value at page-change time over `tween.duration`. Idle bindings settle
 * (stop writing) until their page changes, so a static UI costs nothing per frame.
 */
export function createGearApplySystem(world: World): SystemDef {
    const tracker = new EntityStateMap<{ ref: unknown; txs: Array<BindingTx | null> }>();

    // A frame in which nothing a gear reads has changed does the same nothing as the last one, so it is not run. Everything the
    // pass depends on is tracked: the controllers' pages (UIController), the bindings (UIGear), where each node hangs (Parent, which
    // is how a controller is found), and what exists and carries which component (the world's structural version, which covers a
    // target component arriving later). A tween in flight is the one thing that moves without any of those changing, so it keeps
    // the pass running until it settles. A world without change tracking (a test double) runs every frame as it always did.
    const canSkip = typeof world.enableChangeTracking === 'function' && typeof world.anyChangedSince === 'function'
        && typeof world.getWorldTick === 'function' && typeof world.getWorldVersion === 'function';
    if (canSkip) {
        world.enableChangeTracking(UIController);
        world.enableChangeTracking(UIGear);
        world.enableChangeTracking(Parent);
    }
    let settledTick = -1, settledVersion = -1, inFlight = true;

    return defineSystem([Res(Time)], (time: TimeData) => {
        if (canSkip && !inFlight && settledVersion === world.getWorldVersion()
            && !world.anyChangedSince(UIController, settledTick) && !world.anyChangedSince(UIGear, settledTick)
            && !world.anyChangedSince(Parent, settledTick)) return;
        let moving = false;
        const dt = time.delta;
        const seen = new Set<Entity>();

        for (const e of world.getEntitiesWithComponents([UIGear])) {
            seen.add(e);
            const gear = world.get(e, UIGear) as UIGearData;
            const bindings = gear.bindings;

            // Keyed on the bindings array's identity: any rewrite (theme
            // re-resolution, editor gear authoring) swaps in a new array, which
            // must re-arm settled transitions or the current page never repaints.
            let entry = tracker.get(e);
            if (!entry || entry.ref !== bindings || entry.txs.length !== bindings.length) {
                entry = { ref: bindings, txs: bindings.map(() => null) };
                tracker.set(e, entry);
            }
            const txs = entry.txs;

            for (let i = 0; i < bindings.length; i++) {
                const b = bindings[i];
                const page = getControllerPage(world, e, b.controller);
                if (page === null) continue;

                const target = b.pages[page];
                if (target === undefined) continue; // page not authored → leave field alone

                const comp = getComponent(b.component);
                if (!comp) { moving = true; continue; }                  // not registered yet: look again next frame
                if (!world.has(e, comp)) continue;

                const fade = Math.max(0, b.tween?.duration ?? 0);
                const lerpable = fade > 0 && isLerpable(target);

                let tx = txs[i];
                if (!tx || tx.page !== page) {
                    const cur = readFieldPath(world.get(e, comp) as Record<string, any>, b.property);
                    tx = { page, elapsed: 0, from: lerpable ? cur : (target as GearValue), done: false };
                    txs[i] = tx;
                } else if (tx.done) {
                    continue;
                } else {
                    tx.elapsed += dt;
                }

                const t = lerpable ? Math.min(tx.elapsed / fade, 1) : 1;
                const value = (lerpable && t < 1)
                    ? lerpGearValue(tx.from, target, applyEasing(b.tween!.easing, t))
                    : target;

                const data = world.get(e, comp) as Record<string, any>;
                if (writeFieldPath(data, b.property, value)) {
                    world.insert(e, comp, data);
                }
                if (t >= 1) tx.done = true; else moving = true;
            }
        }
        if (canSkip) {
            inFlight = moving;
            // Strictly-after, like the layout pass: a write that lands later in this same tick is seen next frame.
            settledTick = world.getWorldTick() - 1;
            settledVersion = world.getWorldVersion();
        }

        // Purge trackers for entities that no longer carry UIGear (the query only
        // yields live UIGear entities, so anything unseen is gone or stripped).
        for (const [e] of tracker) {
            if (!seen.has(e)) tracker.delete(e);
        }
    }, { name: 'GearApplySystem' });
}