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.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { Canvas, Transform, Parent, defineComponent } from '../../ecs/component';
import { defineSystem } from '../../ecs/system';
import { Res, Time, type TimeData } from '../../ecs/resource';
import { Input, type InputState } from '../../input/input';
import { primaryPointerCancellationVersion } from '../../input/pointerCancellation';
import { worldEngineApi, type EngineApi } from '../../ecs/bridge/engineApi';
import type { World } from '../../ecs/world';
import type { Entity } from '../../types';
import type { InstantiatePrefabResult } from '../../prefab';
import { UINode, UIPointerEvents, UIDisplay } from '../core/ui-node';
import { Text } from '../core/text';
import { spawnUIEntity } from '../core/compose';
import { px } from '../core/dimension';
import { ScreenLayout, type ScreenLayoutData } from '../core/screen-layout';
import { ScreenOverlay, type ScreenOverlayData } from '../core/screen-overlay';
import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
import { UIControlPointers, type ControlPointer } from '../input/control-pointers';
import { MOUSE_POINTER } from '../input/pointerBook';
import { Focusable, type FocusManagerState, FocusManager } from '../input/focusable';
import { Interactable, UIInteraction } from '../input/interactable';
import { createLiveVisibilityQuery } from '../util/live-visibility';
import { isFocusEligible } from '../input/focus-inspection';
import { isScreenEntity, uiWorldToScreen, screenToUiLayout } from '../util/ui-pick';
import { themeColors } from '../theme/tokens';
import { markThemed } from '../theme/theme-style';
import { measureText } from '../text/measure-text';

/** Trigger and layout settings for an engine UI tooltip. @beta */
export interface UITooltipData {
    content: string;
    stylePrefab: string;
    hover: boolean;
    focus: boolean;
    longPress: boolean;
    hoverDelay: number;
    longPressDelay: number;
    /** 0 bottom, 1 top, 2 left, 3 right. */
    side: number;
    gap: number;
    avoidEdges: boolean;
    maxWidth: number;
}

/** An input-transparent, themed engine UI popup attached to a target. @beta */
export const UITooltip = defineComponent<UITooltipData>('UITooltip', {
    content: 'Tooltip', stylePrefab: '', hover: true, focus: true, longPress: true,
    hoverDelay: 0.5, longPressDelay: 0.6, side: 0, gap: 8, avoidEdges: true, maxWidth: 240,
}, { assetFields: [{ field: 'stylePrefab', type: 'prefab' }], fields: {
    hoverDelay: { min: 0, unit: 's' }, longPressDelay: { min: 0, unit: 's' },
    gap: { min: 0, unit: 'px' }, maxWidth: { min: 24, unit: 'px' },
    side: { enum: [{ label: 'Bottom', value: 0 }, { label: 'Top', value: 1 }, { label: 'Left', value: 2 }, { label: 'Right', value: 3 }] },
} });

interface Box { left: number; right: number; top: number; bottom: number }
/** Layout-domain placement. Flip first, then clamp; oversized bubbles stay inside the safe box. */
export function placeTooltip(target: Box, width: number, height: number, side: number, gap: number,
    bounds: Box, avoidEdges: boolean): { x: number; y: number } {
    const position = (s: number) => ({
        x: s === 2 ? target.left - gap - width : s === 3 ? target.right + gap : (target.left + target.right - width) / 2,
        y: s === 1 ? target.top + gap : s === 0 ? target.bottom - gap - height : (target.top + target.bottom - height) / 2,
    });
    let p = position(side);
    const fits = (v: typeof p) => v.x >= bounds.left && v.x + width <= bounds.right
        && v.y >= bounds.bottom && v.y + height <= bounds.top;
    if (avoidEdges) {
        if (!fits(p)) {
            const flipped = position(side ^ 1);
            if (fits(flipped)) p = flipped;
        }
        p.x = Math.max(bounds.left, Math.min(p.x, bounds.right - width));
        p.y = Math.max(bounds.bottom, Math.min(p.y, bounds.top - height));
    }
    return p;
}

interface TooltipState {
    elapsed: number;
    trigger: 'hover' | 'focus' | 'touch' | null;
    pointer: number;
    startX: number;
    startY: number;
    moved: boolean;
    overlay?: Entity;
    popup?: Entity;
    label?: Entity;
    signature?: string;
    pending?: object;
}

export interface TooltipPrefabHost {
    instantiate(ref: string, parent: Entity): Promise<InstantiatePrefabResult>;
}
const previews = new WeakMap<World, Set<Entity>>();
/** Ephemeral authoring preview; never changes scene data or authored delays. @experimental */
export function previewTooltip(world: World, target: Entity): () => void {
    let set = previews.get(world);
    if (!set) { set = new Set(); previews.set(world, set); }
    set.add(target);
    return () => { set.delete(target); };
}

/** Owns all transient entities, asynchronous loads and matrix memory for one App. */
export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost, isPlaying = () => true) {
    const states = new Map<Entity, TooltipState>();
    let disposed = false, owner: EngineApi | null = null, matrixPtr = 0, cancellation = -1;
    let touchBlocksHover = false, touchMouseX = 0, touchMouseY = 0;
    const close = (s: TooltipState) => {
        s.pending = undefined;
        if (s.overlay !== undefined && world.valid(s.overlay)) world.despawn(s.overlay);
        s.overlay = s.popup = s.label = undefined; s.signature = undefined;
    };
    const offDespawn = world.onDespawn(e => {
        const s = states.get(e);
        if (s) { states.delete(e); close(s); }
        previews.get(world)?.delete(e);
    });
    const reset = () => { for (const s of states.values()) close(s); states.clear(); };
    const dispose = () => {
        disposed = true; offDespawn(); reset();
        if (matrixPtr) owner?._free?.(matrixPtr);
        matrixPtr = 0; owner = null;
    };
    const boundsOf = (e: Entity, camera: UICameraData, overlay: ScreenOverlayData): Box | null => {
        const engine = worldEngineApi(world), registry = world.getCppRegistry();
        if (!engine || !registry || !world.has(e, Transform)) return null;
        const w = engine.getUINodeComputedWidth?.(registry, e) ?? 0;
        const h = engine.getUINodeComputedHeight?.(registry, e) ?? 0;
        if (!(w > 0 && h > 0)) return null;
        if (owner !== engine) { if (matrixPtr) owner?._free?.(matrixPtr); matrixPtr = 0; owner = engine; }
        if (!matrixPtr && engine._malloc && engine._free) matrixPtr = engine._malloc(64);
        if (!matrixPtr || !engine.transform_copyFlatRenderMatrix?.(registry, e, matrixPtr)) return null;
        const heap = engine.HEAPU8;
        if (!heap) return null;
        const m = new Float32Array(heap.buffer, heap.byteOffset + matrixPtr, 16);
        const screen = isScreenEntity(world, e);
        const xs: number[] = [], ys: number[] = [];
        for (const x of [-w / 2, w / 2]) for (const y of [-h / 2, h / 2]) {
            const wx = m[0] * x + m[4] * y + m[12], wy = m[1] * x + m[5] * y + m[13];
            const pixel = screen ? null : uiWorldToScreen(camera, wx, wy);
            const p = pixel ? screenToUiLayout(overlay, pixel.x, pixel.y) : { x: wx, y: wy };
            xs.push(p.x); ys.push(p.y);
        }
        return { left: Math.min(...xs), right: Math.max(...xs), bottom: Math.min(...ys), top: Math.max(...ys) };
    };
    const system = defineSystem([Res(Input), Res(Time), Res(ScreenLayout), Res(ScreenOverlay),
        Res(UICameraInfo), Res(UIControlPointers), Res(FocusManager)],
    (input: InputState, time: TimeData, layout: ScreenLayoutData, overlay: ScreenOverlayData,
        camera: UICameraData, pointers: { pointers: Map<number, ControlPointer> }, focus: FocusManagerState) => {
        if (disposed) return;
        const version = primaryPointerCancellationVersion(input);
        const cancelled = cancellation !== -1 && version !== cancellation;
        cancellation = version;
        const mousePointer = pointers.pointers.get(MOUSE_POINTER);
        if (input.touches.size || input.touchesEnded.size || [...pointers.pointers.values()].some(p => p.id !== MOUSE_POINTER && p.down)) {
            touchBlocksHover = true; touchMouseX = input.mouseX; touchMouseY = input.mouseY;
        } else if (input.mouseX !== touchMouseX || input.mouseY !== touchMouseY || mousePointer?.pressed) {
            // The host may leave its synthesized mouse over the lifted finger.
            // Resume hover only on fresh mouse activity, never from that stale position.
            touchBlocksHover = false;
        }
        const hidden = createLiveVisibilityQuery(world, () => false);
        const live = new Set(world.getEntitiesWithComponents([UITooltip, UINode]));
        for (const [e, s] of states) if (!live.has(e)) { close(s); states.delete(e); }
        for (const e of live) {
            let s = states.get(e);
            if (!s) { s = { elapsed: 0, trigger: null, pointer: -2, startX: 0, startY: 0, moved: false }; states.set(e, s); }
            const d = world.get(e, UITooltip);
            const preview = !isPlaying() && !!previews.get(world)?.has(e);
            const available = layout.valid && overlay.active && !hidden(e) && world.isEntityActive(e)
                && !world.isDestructionPending(e) && (!world.has(e, Interactable) || world.get(e, Interactable).enabled);
            const touch = [...pointers.pointers.values()].find(p => p.id !== MOUSE_POINTER && p.down && p.entity === e);
            const mouse = pointers.pointers.get(MOUSE_POINTER);
            const hovered = world.has(e, UIInteraction) && world.get(e, UIInteraction).hovered;
            let trigger: TooltipState['trigger'] = null;
            if (cancelled && touch) { s.moved = true; s.pointer = touch.id; }
            if (available && d.content && preview) trigger = 'focus';
            else if (isPlaying() && available && d.content && !cancelled && !input.isKeyPressed('Escape')) {
                if (touch && d.longPress) {
                    if (s.pointer !== touch.id) {
                        s.pointer = touch.id; s.startX = touch.layoutX; s.startY = touch.layoutY; s.moved = false;
                    }
                    if (Math.hypot(touch.layoutX - s.startX, touch.layoutY - s.startY) * layout.scale > 8) s.moved = true;
                    if (!s.moved && touch.entity === e) trigger = 'touch';
                } else if (d.focus && focus.isVisiblyFocused(e) && isFocusEligible(world, e)) trigger = 'focus';
                else if (d.hover && hovered && mouse?.down === false && !touchBlocksHover) trigger = 'hover';
            }
            if (!touch) { s.pointer = -2; s.moved = false; }
            if (trigger !== s.trigger) { close(s); s.elapsed = 0; s.trigger = trigger; }
            if (!trigger) continue;
            s.elapsed += Number.isFinite(time.delta) ? Math.max(0, time.delta) : 0;
            const delay = trigger === 'focus' ? 0 : trigger === 'touch' ? d.longPressDelay : d.hoverDelay;
            if (s.elapsed < (Number.isFinite(delay) ? Math.max(0, delay) : 0)) continue;
            const target = boundsOf(e, camera, overlay);
            if (!target) { close(s); continue; }
            const signature = JSON.stringify([d.content, d.stylePrefab]);
            if (s.signature !== signature) { close(s); s.signature = signature; }
            if (s.overlay === undefined) {
                const canvas = spawnUIEntity({ world, node: { fill: true, pointerEvents: UIPointerEvents.None } });
                let ancestor = e;
                const visited = new Set<Entity>();
                while (world.valid(ancestor) && !world.has(ancestor, Canvas) && world.has(ancestor, Parent) && !visited.has(ancestor)) {
                    visited.add(ancestor); ancestor = world.get(ancestor, Parent).entity;
                }
                const canvasData = structuredClone(world.has(ancestor, Canvas) ? world.get(ancestor, Canvas) : Canvas._default);
                // The screen domain is shared; this late root is only a non-interactive paint layer.
                world.insert(canvas, Canvas, canvasData);
                s.overlay = canvas;
                if (d.stylePrefab && prefabHost) {
                    const token = {}; s.pending = token;
                    const state = s;
                    void prefabHost.instantiate(d.stylePrefab, canvas).then(result => {
                        if (disposed || state.pending !== token || !world.valid(canvas)) {
                            for (const id of result.entities.values()) if (world.valid(id)) world.despawn(id);
                            return;
                        }
                        state.pending = undefined;
                        if (!world.has(result.root, UINode)) throw new Error('Tooltip style needs a UINode root');
                        state.popup = result.root;
                        state.label = [...result.entities.values()].find(id => id !== result.root && world.has(id, Text) && world.has(id, UINode));
                        if (state.label === undefined) throw new Error('Tooltip style needs a Text node');
                        for (const id of result.entities.values()) {
                            if (world.has(id, Focusable)) world.remove(id, Focusable);
                            if (world.has(id, Interactable)) world.remove(id, Interactable);
                        }
                    }).catch(error => {
                        if (state.overlay !== canvas || disposed) return;
                        state.pending = undefined;
                        if (state.popup !== undefined && world.valid(state.popup)) world.despawn(state.popup);
                        state.popup = state.label = undefined;
                        console.warn('[UITooltip] Could not display style prefab:', error);
                    });
                } else {
                    const c = themeColors();
                    s.popup = spawnUIEntity({ world, parent: canvas, node: { position: 1 }, visual: { color: c.surfaceElevated } });
                    markThemed(world, s.popup, { visual: 'surfaceElevated' });
                    s.label = spawnUIEntity({ world, parent: s.popup, node: { fill: true },
                        text: { content: d.content, color: c.text, fontSize: 14, wordWrap: true } });
                    markThemed(world, s.label, { text: 'text' });
                }
            }
            if (s.popup === undefined || s.label === undefined || !world.valid(s.popup) || !world.valid(s.label)) continue;
            const text = world.get(s.label, Text);
            const availableWidth = Math.max(1, layout.safeRight - layout.safeLeft);
            const maxWidth = Math.max(1, Math.min(Number.isFinite(d.maxWidth) ? Math.max(24, d.maxWidth) : 240, availableWidth - 20));
            const measured = measureText(d.content, { ...text, maxWidth,
                lineHeight: text.fontSize * text.lineHeight });
            const width = Math.min(availableWidth, measured.width + 20);
            const height = Math.min(Math.max(24, measured.height + 16), layout.safeTop - layout.safeBottom);
            const p = placeTooltip(target, width, height, Number.isInteger(d.side) && d.side >= 0 && d.side <= 3 ? d.side : 0,
                Number.isFinite(d.gap) ? Math.max(0, d.gap) : 8,
                { left: layout.safeLeft, right: layout.safeRight, bottom: layout.safeBottom, top: layout.safeTop }, d.avoidEdges);
            const node = world.get(s.popup, UINode);
            const left = p.x - layout.left, top = layout.top - p.y - height;
            const same = (dim: { value: number; unit: number }, n: number) => dim.unit === 0 && Math.abs(dim.value - n) < 0.01;
            if (node.position !== 1 || node.display !== UIDisplay.Flex || node.pointerEvents !== UIPointerEvents.None
                || !same(node.width, width) || !same(node.height, height) || !same(node.insetLeft, left) || !same(node.insetTop, top)) {
                world.insert(s.popup, UINode, { ...node, position: 1, display: UIDisplay.Flex, pointerEvents: UIPointerEvents.None,
                    width: px(width), height: px(height), insetLeft: px(left), insetTop: px(top) });
            }
            if (text.content !== d.content || !text.wordWrap) world.insert(s.label, Text, { ...text, content: d.content, wordWrap: true });
            const labelNode = world.get(s.label, UINode);
            if (labelNode.position !== 1 || labelNode.insetLeft.value !== 10 || labelNode.insetRight.value !== 10
                || labelNode.insetTop.value !== 8 || labelNode.insetBottom.value !== 8) {
                world.insert(s.label, UINode, { ...labelNode, position: 1, insetLeft: px(10), insetRight: px(10), insetTop: px(8), insetBottom: px(8) });
            }
        }
    }, { name: 'UITooltipSystem', runAfter: ['UITabViewSystem', 'FocusSystem'] });
    return { system, dispose, reset };
}