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.

8.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/behavior/slider.ts
 * @brief   UISlider — data-driven slider state + input.
 *
 * The component IS the slider's state (min/max/step/value + its fill/handle
 * entity refs); the system is the single writer of the visuals, re-deriving
 * them whenever the value, range or visual targets change. Any writer — pointer
 * drag, keyboard, `handle.setValue`, a data binding, the editor inspector —
 * just writes `value`, and change events fire uniformly for all of them.
 */
import { defineComponent } from '../../ecs/component';
import { defineSystem, type SystemDef } from '../../ecs/system';
import { Res } from '../../ecs/resource';
import { Input, type InputState } from '../../input/input';
import { primaryPointerCancellationVersion } from '../../input/pointerCancellation';
import { worldEngineApi } from '../../ecs/bridge/engineApi';
import { Transform, type TransformData } from '../../ecs/component';
import type { World } from '../../ecs/world';
import type { Entity } from '../../types';
import { UIVisual, type UIVisualData } from '../core/ui-visual';
import { UINode, type UINodeData } from '../core/ui-node';
import { percent } from '../core/dimension';
import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
import { ScreenOverlay, type ScreenOverlayData } from '../core/screen-overlay';
import { uiPointerFor } from '../util/ui-pick';
import { UIInteraction, type UIInteractionData } from '../input/interactable';
import { Interactable, type InteractableData } from '../input/interactable';
import { Focusable, type FocusableData } from '../input/focusable';
import { UIEventType, type UIEventQueue } from '../core/events';
import { EntityStateMap } from '../util/helpers';
import { UIConsumesDrag } from '../input/drag-consumption';

export interface UISliderData {
    min: number;
    max: number;
    /** Quantization step; 0 = continuous. */
    step: number;
    value: number;
    /** The Filled fill bar entity (fillAmount tracks the value fraction). */
    fill: Entity;
    /** The handle thumb entity (insetLeft tracks the value fraction). */
    handle: Entity;
}

export const UISlider = defineComponent<UISliderData>('UISlider', {
    min: 0,
    max: 1,
    step: 0,
    value: 0,
    fill: 0 as Entity,
    handle: 0 as Entity,
}, { entityFields: ['fill', 'handle'] });

export function sliderClamp(v: number, d: { min: number; max: number; step: number }): number {
    const clamped = v < d.min ? d.min : v > d.max ? d.max : v;
    if (d.step <= 0) return clamped;
    const snapped = Math.round((clamped - d.min) / d.step) * d.step + d.min;
    return snapped < d.min ? d.min : snapped > d.max ? d.max : snapped;
}

export function sliderFraction(d: { min: number; max: number; value: number }): number {
    if (d.max <= d.min) return 0;
    const t = (d.value - d.min) / (d.max - d.min);
    return t < 0 ? 0 : t > 1 ? 1 : t;
}

/** Keyboard nudge: explicit step, else 1% of the range. */
function keyStep(d: UISliderData): number {
    return d.step > 0 ? d.step : (d.max - d.min) / 100;
}

/**
 * Pointer drag (press-capture on the track), keyboard (arrows/Home/End while
 * focused), and value→visual sync for every UISlider.
 */
export function createSliderSystem(world: World, events: UIEventQueue): SystemDef {
    // Press on a track captures the drag until release, even off-entity.
    let active: Entity | null = null;
    let lastCancellationVersion = 0;
    const engine = worldEngineApi(world);
    const registry = world.getCppRegistry();
    const receivesInput = (e: Entity): boolean => world.isEntityActive(e)
        && !world.isDestructionPending(e)
        && (!world.has(e, Interactable) || (world.get(e, Interactable) as InteractableData).enabled)
        && (!world.has(e, UINode) || !engine?.getUINodeHiddenInTree?.(registry!, e));
    const shown = new EntityStateMap<Pick<UISliderData, 'value' | 'min' | 'max' | 'fill' | 'handle'>>();

    return defineSystem(
        [Res(Input), Res(UICameraInfo), Res(ScreenOverlay)],
        (input: InputState, camera: UICameraData, overlay: ScreenOverlayData) => {
            const version = primaryPointerCancellationVersion(input);
            const cancelled = version !== lastCancellationVersion;
            lastCancellationVersion = version;
            const pointerAvailable = camera.valid || overlay.active;
            if (active !== null && (cancelled || !pointerAvailable || !world.valid(active)
                || !world.has(active, UISlider) || !receivesInput(active)
                || !world.has(active, Transform) || !input.isMouseButtonDown(0))) active = null;
            for (const e of world.getEntitiesWithComponents([UISlider])) {
                if (!world.valid(e) || !world.has(e, UISlider)) continue;
                if (!world.has(e, UIConsumesDrag)) world.insert(e, UIConsumesDrag);
                const d = world.get(e, UISlider) as UISliderData;
                let next = d.value;

                const enabled = receivesInput(e);

                // Pointer: capture on press, track while held.
                if (enabled && pointerAvailable && input.isMouseButtonDown(0) && world.has(e, UIInteraction)
                    && (world.get(e, UIInteraction) as UIInteractionData).justPressed) {
                    active = e;
                }
                if (active === e) {
                    if (!input.isMouseButtonDown(0)) {
                        active = null;
                    } else if ((camera.valid || overlay.active) && world.has(e, Transform)) {
                        const t = world.get(e, Transform) as TransformData;
                        const w = (registry ? engine?.getUINodeComputedWidth?.(registry, e) ?? 0 : 0) * t.worldScale.x;
                        if (w > 0) {
                            // The pointer in the track's own domain: the fraction
                            // is a ratio of two positions, so both have to be in
                            // the coordinates the track was laid out in.
                            const pointer = uiPointerFor(world, e, camera, overlay);
                            const left = t.worldPosition.x - w / 2;
                            next = sliderClamp(
                                d.min + ((pointer.x - left) / w) * (d.max - d.min), d);
                        }
                    }
                }

                // Keyboard while focused.
                if (enabled && world.has(e, Focusable)
                    && (world.get(e, Focusable) as FocusableData).isFocused) {
                    const s = keyStep(d);
                    if (input.isKeyPressed('ArrowLeft') || input.isKeyPressed('ArrowDown')) {
                        next = sliderClamp(next - s, d);
                    }
                    if (input.isKeyPressed('ArrowRight') || input.isKeyPressed('ArrowUp')) {
                        next = sliderClamp(next + s, d);
                    }
                    if (input.isKeyPressed('Home')) next = d.min;
                    if (input.isKeyPressed('End')) next = d.max;
                }

                if (next !== d.value) {
                    d.value = next;
                    world.insert(e, UISlider, d);
                }

                // Value → visuals + change event, whoever wrote the value.
                const previous = shown.get(e);
                if (!previous || previous.value !== d.value || previous.min !== d.min
                    || previous.max !== d.max || previous.fill !== d.fill || previous.handle !== d.handle) {
                    const emitChange = previous !== undefined && previous.value !== d.value;
                    if (previous) {
                        previous.value = d.value; previous.min = d.min; previous.max = d.max;
                        previous.fill = d.fill; previous.handle = d.handle;
                    } else {
                        shown.set(e, { value: d.value, min: d.min, max: d.max, fill: d.fill, handle: d.handle });
                    }
                    const frac = sliderFraction(d);
                    if (world.valid(d.fill) && world.has(d.fill, UIVisual)) {
                        const vis = world.get(d.fill, UIVisual) as UIVisualData;
                        if (vis.fillAmount !== frac) {
                            vis.fillAmount = frac;
                            world.insert(d.fill, UIVisual, vis);
                        }
                    }
                    if (world.valid(d.handle) && world.has(d.handle, UINode)) {
                        const n = world.get(d.handle, UINode) as UINodeData;
                        n.insetLeft = percent(frac * 100);
                        world.insert(d.handle, UINode, n);
                    }
                    if (emitChange) events.emit(e, UIEventType.Change, { value: d.value });
                }
            }
            shown.cleanup(world);
        },
        { name: 'UISliderSystem' },
    );
}