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.

10.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Vec2 } from '../../types';
import { log } from '../../util/logger';

export interface ScrollContainerOptions {
    viewportSize: Vec2;
    contentSize: Vec2;
    initialOffset?: Vec2;
    /** Axis restrictions. Default 'vertical'. */
    direction?: 'both' | 'vertical' | 'horizontal';
    /** Multiplier applied to wheel deltas. Default 1. */
    wheelSpeed?: number;
    /** Drag/touch scrolling (pointer grab + kinetic fling). Default true. */
    dragScroll?: boolean;
    /** Fling velocity left after 1s of coasting. Default 0.135. */
    decelerationRate?: number;
    /** Auto-fading overlay scrollbar thumbs. Default true. */
    showScrollbar?: boolean;
    /**
     * Let a drag pull the content past either end (rubber-banded, so the further out, the stiffer), and spring it back when let go.
     * The offset itself stays clamped; the extra is {@link ScrollContainer.getOverscroll}. Default false.
     */
    elastic?: boolean;
    /** Seconds the spring back takes to settle. Default 0.5. */
    bounceTime?: number;
}

export type ScrollListener = (offset: Vec2) => void;
/** Told when the overscroll changes; @p offset is the (clamped) offset it is measured from. */
export type OverscrollListener = (overscroll: Vec2, offset: Vec2) => void;

/** How far a pull of @p distance past an end shows, for a viewport of @p view: stiffer the further out, never more than the viewport. */
export function rubberBand(distance: number, view: number): number {
    if (distance === 0 || view <= 0) return 0;
    const d = Math.abs(distance);
    return Math.sign(distance) * view * (1 - 1 / ((d * 0.55) / view + 1));
}

/** The pull that {@link rubberBand} turns into @p shown: what the finger has travelled past the end to hold the content there. */
export function rubberBandInverse(shown: number, view: number): number {
    if (shown === 0 || view <= 0) return 0;
    const r = Math.min(0.999, Math.abs(shown) / view);
    return Math.sign(shown) * (view * r) / (0.55 * (1 - r));
}

/**
 * Scroll state for a virtualized view. Clamps offset to the legal range
 * `[0, contentSize - viewportSize]` and notifies listeners on any change.
 *
 * The ScrollContainer itself has no input knowledge; a system pushes
 * wheel / drag deltas into `scrollBy`. Consumers that need to react
 * (e.g. a ListView) subscribe via `onScroll`.
 */
export class ScrollContainer {
    private viewportSize_: Vec2;
    private contentSize_: Vec2;
    private offset_: Vec2 = { x: 0, y: 0 };
    private readonly direction_: 'both' | 'vertical' | 'horizontal';
    private readonly wheelSpeed_: number;
    private readonly dragScroll_: boolean;
    private readonly decelerationRate_: number;
    private readonly showScrollbar_: boolean;
    private readonly listeners_ = new Set<ScrollListener>();
    private readonly overListeners_ = new Set<OverscrollListener>();
    private readonly elastic_: boolean;
    private readonly bounceTime_: number;
    private over_: Vec2 = { x: 0, y: 0 };
    private overVel_: Vec2 = { x: 0, y: 0 };

    constructor(opts: ScrollContainerOptions) {
        this.viewportSize_ = { x: opts.viewportSize.x, y: opts.viewportSize.y };
        this.contentSize_ = { x: opts.contentSize.x, y: opts.contentSize.y };
        this.direction_ = opts.direction ?? 'vertical';
        this.wheelSpeed_ = opts.wheelSpeed ?? 1;
        this.dragScroll_ = opts.dragScroll ?? true;
        this.decelerationRate_ = opts.decelerationRate ?? 0.135;
        this.showScrollbar_ = opts.showScrollbar ?? true;
        this.elastic_ = opts.elastic ?? false;
        this.bounceTime_ = Math.max(0.05, opts.bounceTime ?? 0.5);
        this.setOffset(opts.initialOffset ?? { x: 0, y: 0 });
    }

    getOffset(): Vec2 {
        return { x: this.offset_.x, y: this.offset_.y };
    }

    getViewportSize(): Vec2 {
        return { x: this.viewportSize_.x, y: this.viewportSize_.y };
    }

    getContentSize(): Vec2 {
        return { x: this.contentSize_.x, y: this.contentSize_.y };
    }

    getMaxOffset(): Vec2 {
        return {
            x: Math.max(0, this.contentSize_.x - this.viewportSize_.x),
            y: Math.max(0, this.contentSize_.y - this.viewportSize_.y),
        };
    }

    getShowScrollbar(): boolean {
        return this.showScrollbar_;
    }

    getWheelSpeed(): number {
        return this.wheelSpeed_;
    }

    getDragScroll(): boolean {
        return this.dragScroll_;
    }

    getDecelerationRate(): number {
        return this.decelerationRate_;
    }

    setOffset(offset: Vec2): void {
        const max = this.getMaxOffset();
        const lockX = this.direction_ === 'vertical';
        const lockY = this.direction_ === 'horizontal';
        const next: Vec2 = {
            x: lockX ? 0 : clamp(offset.x, 0, max.x),
            y: lockY ? 0 : clamp(offset.y, 0, max.y),
        };
        if (next.x === this.offset_.x && next.y === this.offset_.y) return;
        this.offset_ = next;
        for (const listener of Array.from(this.listeners_)) {
            try {
                listener({ x: next.x, y: next.y });
            } catch (err) {
                log.error('ui', 'ScrollContainer listener error', err);
            }
        }
    }

    isElastic(): boolean {
        return this.elastic_;
    }

    /** How far the content is pulled past an end on each axis: negative before the start, positive past the end, 0 inside. */
    getOverscroll(): Vec2 {
        return { x: this.over_.x, y: this.over_.y };
    }

    /** Whether the content is out past an end, or still moving back from it. */
    isSpringing(): boolean {
        return this.over_.x !== 0 || this.over_.y !== 0 || this.overVel_.x !== 0 || this.overVel_.y !== 0;
    }

    /**
     * Put the content where a finger holding it would: @p raw is the UNCLAMPED offset the drag asks for. Inside the range it is the
     * offset; past an end the offset stops there and the rest is shown as rubber-banded overscroll. Not elastic, this is `setOffset`.
     */
    dragTo(raw: Vec2): void {
        this.setOffset(raw);
        if (!this.elastic_) return;
        const max = this.getMaxOffset();
        const lockX = this.direction_ === 'vertical';
        const lockY = this.direction_ === 'horizontal';
        this.setOverscroll({
            x: lockX ? 0 : rubberBand(raw.x - clamp(raw.x, 0, max.x), this.viewportSize_.x),
            y: lockY ? 0 : rubberBand(raw.y - clamp(raw.y, 0, max.y), this.viewportSize_.y),
        }, { x: 0, y: 0 });
    }

    /** Take the speed out of the spring, leaving the content where it is. */
    releaseSpring(): void {
        this.overVel_ = { x: 0, y: 0 };
    }

    /** Momentum arriving at an end: some of it goes into the overscroll, which then springs back. */
    absorb(axis: 'x' | 'y', velocity: number): void {
        if (!this.elastic_) return;
        this.overVel_[axis] += velocity * 0.3;
    }

    /** Advance the spring by @p dt seconds. Returns whether the overscroll changed. */
    tickSpring(dt: number): boolean {
        if (!this.elastic_ || dt <= 0 || !this.isSpringing()) return false;
        // critically damped, in closed form so the step size does not matter; tuned so it has all but settled by `bounceTime`
        const w = 7 / this.bounceTime_;
        const decay = Math.exp(-w * dt);
        const x = { ...this.over_ };
        const v = { ...this.overVel_ };
        for (const axis of ['x', 'y'] as const) {
            const c = v[axis] + w * x[axis];
            x[axis] = decay * (x[axis] + c * dt);
            v[axis] = decay * (v[axis] - w * c * dt);
        }
        for (const axis of ['x', 'y'] as const) {
            if (Math.abs(x[axis]) < 0.1 && Math.abs(v[axis]) < 1) { x[axis] = 0; v[axis] = 0; }
        }
        return this.setOverscroll(x, v);
    }

    private setOverscroll(over: Vec2, velocity: Vec2): boolean {
        const changed = over.x !== this.over_.x || over.y !== this.over_.y;
        this.over_ = over;
        this.overVel_ = velocity;
        if (changed) this.notifyOver_();
        return changed;
    }

    private notifyOver_(): void {
        const offset = this.getOffset();
        for (const listener of Array.from(this.overListeners_)) {
            try {
                listener({ x: this.over_.x, y: this.over_.y }, offset);
            } catch (err) {
                log.error('ui', 'ScrollContainer overscroll listener error', err);
            }
        }
    }

    scrollBy(delta: Vec2): void {
        this.setOffset({
            x: this.offset_.x + delta.x,
            y: this.offset_.y + delta.y,
        });
    }

    setViewportSize(size: Vec2): void {
        this.setSizes(size, this.contentSize_);
    }

    setContentSize(size: Vec2): void {
        this.setSizes(this.viewportSize_, size);
    }

    /** Update both extents before clamping, so resize emits only its final offset. */
    setSizes(viewport: Vec2, content: Vec2): void {
        if (viewport.x === this.viewportSize_.x && viewport.y === this.viewportSize_.y
            && content.x === this.contentSize_.x && content.y === this.contentSize_.y) return;
        this.viewportSize_ = { x: viewport.x, y: viewport.y };
        this.contentSize_ = { x: content.x, y: content.y };
        this.setOffset(this.offset_);
    }

    onScroll(listener: ScrollListener): () => void {
        this.listeners_.add(listener);
        return () => {
            this.listeners_.delete(listener);
        };
    }

    onOverscroll(listener: OverscrollListener): () => void {
        this.overListeners_.add(listener);
        return () => {
            this.overListeners_.delete(listener);
        };
    }

    dispose(): void {
        this.listeners_.clear();
        this.overListeners_.clear();
    }
}

/** Registry of scroll containers keyed by the entity they're attached to. */
export class ScrollContainerRegistry {
    private readonly entries_ = new Map<number, ScrollContainer>();

    attach(entity: number, container: ScrollContainer): void {
        this.entries_.set(entity, container);
    }

    detach(entity: number): void {
        this.entries_.delete(entity);
    }

    get(entity: number): ScrollContainer | undefined {
        return this.entries_.get(entity);
    }

    entries(): IterableIterator<[number, ScrollContainer]> {
        return this.entries_.entries();
    }

    size(): number {
        return this.entries_.size;
    }

    clear(): void {
        this.entries_.clear();
    }
}

function clamp(value: number, lo: number, hi: number): number {
    return value < lo ? lo : value > hi ? hi : value;
}