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/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' });
}