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.

3.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/collection/kinetic-scroll.ts
 * @brief   KineticScroll — the pure velocity model behind drag/touch scrolling:
 *          EMA-smoothed sampling while held, exponential decay after release.
 *          Like {@link ScrollContainer}, it has no input or ECS knowledge.
 */
import type { Vec2 } from '../../types';

export interface KineticScrollOptions {
    /** Fling velocity left after 1s of coasting (`v *= rate^dt`). Default 0.135. */
    decelerationRate?: number;
    /** Speed floor (px/s) below which coasting stops. Default 4. */
    restVelocity?: number;
    /** Per-second EMA rate for velocity samples (`1 - e^(-rate·dt)`). Default 12. */
    sampleRate?: number;
}

export class KineticScroll {
    private readonly decayLog_: number;
    private readonly restVelocity_: number;
    private readonly sampleRate_: number;
    private velocity_: Vec2 = { x: 0, y: 0 };
    private dragging_ = false;

    constructor(opts: KineticScrollOptions = {}) {
        this.decayLog_ = Math.log(opts.decelerationRate ?? 0.135);
        this.restVelocity_ = opts.restVelocity ?? 4;
        this.sampleRate_ = opts.sampleRate ?? 12;
    }

    /** A finger/pointer grabbed the content: cancel any coast, start sampling. */
    beginDrag(): void {
        this.dragging_ = true;
        this.velocity_ = { x: 0, y: 0 };
    }

    /** Feed one frame's offset delta (px) while the drag is held. */
    sample(delta: Vec2, dt: number): void {
        if (!this.dragging_ || dt <= 0) return;
        const instant = { x: delta.x / dt, y: delta.y / dt };
        const blend = 1 - Math.exp(-this.sampleRate_ * dt);
        this.velocity_.x += (instant.x - this.velocity_.x) * blend;
        this.velocity_.y += (instant.y - this.velocity_.y) * blend;
    }

    /** Release: the sampled velocity carries over into coasting. */
    endDrag(): void {
        this.dragging_ = false;
    }

    /** Hard stop (new grab, wheel input, or hitting a clamp edge). */
    stop(): void {
        this.dragging_ = false;
        this.velocity_ = { x: 0, y: 0 };
    }

    /** Kill one axis of the coast (that axis hit its clamp edge). */
    killAxis(axis: 'x' | 'y'): void {
        this.velocity_[axis] = 0;
    }

    isDragging(): boolean {
        return this.dragging_;
    }

    /** Coasting = released with speed above the rest floor. */
    isCoasting(): boolean {
        if (this.dragging_) return false;
        const { x, y } = this.velocity_;
        return Math.hypot(x, y) > this.restVelocity_;
    }

    getVelocity(): Vec2 {
        return { x: this.velocity_.x, y: this.velocity_.y };
    }

    /**
     * Advance one coast frame: returns the offset delta to apply and decays
     * the velocity. Zero vector when not coasting.
     */
    tick(dt: number): Vec2 {
        if (this.dragging_ || dt <= 0) return { x: 0, y: 0 };
        const speed = Math.hypot(this.velocity_.x, this.velocity_.y);
        if (!(speed > this.restVelocity_)) return { x: 0, y: 0 };
        const exponent = this.decayLog_ * dt;
        const decay = Math.exp(exponent);
        const atRest = speed * decay <= this.restVelocity_;
        const movingTime = atRest && this.restVelocity_ > 0 && this.decayLog_ < 0
            ? Math.min(dt, Math.log(this.restVelocity_ / speed) / this.decayLog_) : dt;
        const integratedTime = this.decayLog_ === -Infinity ? 0
            : this.decayLog_ === 0 ? movingTime : Math.expm1(this.decayLog_ * movingTime) / this.decayLog_;
        const delta = { x: this.velocity_.x * integratedTime, y: this.velocity_.y * integratedTime };
        this.velocity_.x *= decay;
        this.velocity_.y *= decay;
        if (atRest) this.velocity_ = { x: 0, y: 0 };
        return delta;
    }
}