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.

9.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Easing.ts
 * @brief   Pure easing math — 1:1 port of C++ EasingFunctions.hpp
 *
 * The EasingType enum values are WASM boundary contract — they must stay
 * in lock-step with src/esengine/animation/TweenData.hpp::EasingType.
 */

import { EasingType } from '../wasm/wasm.generated';

// =============================================================================
// EasingType (wire protocol — generated from C++ TweenData.hpp)
// =============================================================================

/**
 * The easing curves the C++ `TweenSystem` can drive, from the enum that owns
 * them. Generated, so this is not a second answer, and the values are in the
 * ABI layout hash — they cross as bare numbers, where a drift is a different
 * curve rather than an error.
 */
export { EasingType } from '../wasm/wasm.generated';

export interface BezierPoints {
    p1x: number;
    p1y: number;
    p2x: number;
    p2y: number;
}

// =============================================================================
// Easing Functions
// =============================================================================

function easeLinear(t: number): number {
    return t;
}

function easeInQuad(t: number): number {
    return t * t;
}

function easeOutQuad(t: number): number {
    return t * (2 - t);
}

function easeInOutQuad(t: number): number {
    return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
}

function easeInCubic(t: number): number {
    return t * t * t;
}

function easeOutCubic(t: number): number {
    const t1 = t - 1;
    return t1 * t1 * t1 + 1;
}

function easeInOutCubic(t: number): number {
    return t < 0.5
        ? 4 * t * t * t
        : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
}

const BACK_C1 = 1.70158;
const BACK_C3 = BACK_C1 + 1;
const BACK_C2 = BACK_C1 * 1.525;

function easeInBack(t: number): number {
    return BACK_C3 * t * t * t - BACK_C1 * t * t;
}

function easeOutBack(t: number): number {
    const t1 = t - 1;
    return 1 + BACK_C3 * t1 * t1 * t1 + BACK_C1 * t1 * t1;
}

function easeInOutBack(t: number): number {
    if (t < 0.5) {
        return (Math.pow(2 * t, 2) * ((BACK_C2 + 1) * 2 * t - BACK_C2)) / 2;
    }
    return (Math.pow(2 * t - 2, 2) * ((BACK_C2 + 1) * (t * 2 - 2) + BACK_C2) + 2) / 2;
}

const ELASTIC_C4 = (2 * Math.PI) / 3;
const ELASTIC_C5 = (2 * Math.PI) / 4.5;

function easeInElastic(t: number): number {
    if (t === 0 || t === 1) return t;
    return -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * ELASTIC_C4);
}

function easeOutElastic(t: number): number {
    if (t === 0 || t === 1) return t;
    return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * ELASTIC_C4) + 1;
}

function easeInOutElastic(t: number): number {
    if (t === 0 || t === 1) return t;
    if (t < 0.5) {
        return -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * ELASTIC_C5)) / 2;
    }
    return (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * ELASTIC_C5)) / 2 + 1;
}

const BOUNCE_N1 = 7.5625;
const BOUNCE_D1 = 2.75;

function easeOutBounce(t: number): number {
    if (t < 1 / BOUNCE_D1) {
        return BOUNCE_N1 * t * t;
    } else if (t < 2 / BOUNCE_D1) {
        t -= 1.5 / BOUNCE_D1;
        return BOUNCE_N1 * t * t + 0.75;
    } else if (t < 2.5 / BOUNCE_D1) {
        t -= 2.25 / BOUNCE_D1;
        return BOUNCE_N1 * t * t + 0.9375;
    } else {
        t -= 2.625 / BOUNCE_D1;
        return BOUNCE_N1 * t * t + 0.984375;
    }
}

const BEZIER_MAX_ITERATIONS = 8;
const BEZIER_EPSILON = 1e-6;

function cubicBezier(t: number, p1x: number, p1y: number, p2x: number, p2y: number): number {
    let x = t;
    for (let i = 0; i < BEZIER_MAX_ITERATIONS; i++) {
        const ix = 1 - x;
        const cx = 3 * p1x * ix * ix * x + 3 * p2x * ix * x * x + x * x * x - t;
        if (Math.abs(cx) < BEZIER_EPSILON) break;
        // dX/dx of 3·p1x·(1-x)²·x + 3·p2x·(1-x)·x² + x³. The first term derivative
        // is 3·p1x·(1-x)·(1-3x) — the (1-3x) factor, not (1-2x).
        const dx = 3 * p1x * (1 - 3 * x) * (1 - x)
                 + 6 * p2x * x * (1 - x)
                 - 3 * p2x * x * x
                 + 3 * x * x;
        if (Math.abs(dx) < BEZIER_EPSILON) break;
        x -= cx / dx;
    }
    const ix = 1 - x;
    return 3 * p1y * ix * ix * x + 3 * p2y * ix * x * x + x * x * x;
}

function step(t: number): number {
    return t < 1 ? 0 : 1;
}

// Sine, quart, quint, expo, circ, bounce in/in-out, smoothstep: ports of the same-named functions in EasingFunctions.hpp.

export function easeInSine(t: number): number { return 1 - Math.cos((t * Math.PI) / 2); }
export function easeOutSine(t: number): number { return Math.sin((t * Math.PI) / 2); }
export function easeInOutSine(t: number): number { return -(Math.cos(Math.PI * t) - 1) / 2; }

export function easeInQuart(t: number): number { return t * t * t * t; }
export function easeOutQuart(t: number): number { const u = 1 - t; return 1 - u * u * u * u; }
export function easeInOutQuart(t: number): number {
    if (t < 0.5) return 8 * t * t * t * t;
    const u = -2 * t + 2;
    return 1 - (u * u * u * u) / 2;
}

export function easeInQuint(t: number): number { return t * t * t * t * t; }
export function easeOutQuint(t: number): number { const u = 1 - t; return 1 - u * u * u * u * u; }
export function easeInOutQuint(t: number): number {
    if (t < 0.5) return 16 * t * t * t * t * t;
    const u = -2 * t + 2;
    return 1 - (u * u * u * u * u) / 2;
}

export function easeInExpo(t: number): number { return t === 0 ? 0 : 2 ** (10 * t - 10); }
export function easeOutExpo(t: number): number { return t === 1 ? 1 : 1 - 2 ** (-10 * t); }
export function easeInOutExpo(t: number): number {
    if (t === 0 || t === 1) return t;
    return t < 0.5 ? 2 ** (20 * t - 10) / 2 : (2 - 2 ** (-20 * t + 10)) / 2;
}

export function easeInCirc(t: number): number { return 1 - Math.sqrt(1 - t * t); }
export function easeOutCirc(t: number): number { const u = t - 1; return Math.sqrt(1 - u * u); }
export function easeInOutCirc(t: number): number {
    if (t < 0.5) return (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2;
    return (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2;
}

export function easeInBounce(t: number): number { return 1 - easeOutBounce(1 - t); }
export function easeInOutBounce(t: number): number {
    return t < 0.5 ? (1 - easeOutBounce(1 - 2 * t)) / 2 : (1 + easeOutBounce(2 * t - 1)) / 2;
}

export function smoothstep(t: number): number { return t <= 0 ? 0 : t >= 1 ? 1 : t * t * (3 - 2 * t); }
export function smootherstep(t: number): number { return t <= 0 ? 0 : t >= 1 ? 1 : t * t * t * (t * (t * 6 - 15) + 10); }

// =============================================================================
// Public Easing Dispatcher
// =============================================================================

export function applyEasing(type: EasingType, t: number, bezier?: BezierPoints): number {
    switch (type) {
        case EasingType.Linear:           return easeLinear(t);
        case EasingType.EaseInQuad:       return easeInQuad(t);
        case EasingType.EaseOutQuad:      return easeOutQuad(t);
        case EasingType.EaseInOutQuad:    return easeInOutQuad(t);
        case EasingType.EaseInCubic:      return easeInCubic(t);
        case EasingType.EaseOutCubic:     return easeOutCubic(t);
        case EasingType.EaseInOutCubic:   return easeInOutCubic(t);
        case EasingType.EaseInBack:       return easeInBack(t);
        case EasingType.EaseOutBack:      return easeOutBack(t);
        case EasingType.EaseInOutBack:    return easeInOutBack(t);
        case EasingType.EaseInElastic:    return easeInElastic(t);
        case EasingType.EaseOutElastic:   return easeOutElastic(t);
        case EasingType.EaseInOutElastic: return easeInOutElastic(t);
        case EasingType.EaseOutBounce:    return easeOutBounce(t);
        case EasingType.CubicBezier:
            if (bezier) return cubicBezier(t, bezier.p1x, bezier.p1y, bezier.p2x, bezier.p2y);
            return easeLinear(t);
        case EasingType.Step:             return step(t);
        case EasingType.EaseInSine: return easeInSine(t);
        case EasingType.EaseOutSine: return easeOutSine(t);
        case EasingType.EaseInOutSine: return easeInOutSine(t);
        case EasingType.EaseInQuart: return easeInQuart(t);
        case EasingType.EaseOutQuart: return easeOutQuart(t);
        case EasingType.EaseInOutQuart: return easeInOutQuart(t);
        case EasingType.EaseInQuint: return easeInQuint(t);
        case EasingType.EaseOutQuint: return easeOutQuint(t);
        case EasingType.EaseInOutQuint: return easeInOutQuint(t);
        case EasingType.EaseInExpo: return easeInExpo(t);
        case EasingType.EaseOutExpo: return easeOutExpo(t);
        case EasingType.EaseInOutExpo: return easeInOutExpo(t);
        case EasingType.EaseInCirc: return easeInCirc(t);
        case EasingType.EaseOutCirc: return easeOutCirc(t);
        case EasingType.EaseInOutCirc: return easeInOutCirc(t);
        case EasingType.EaseInBounce: return easeInBounce(t);
        case EasingType.EaseInOutBounce: return easeInOutBounce(t);
        case EasingType.Smoothstep: return smoothstep(t);
        case EasingType.Smootherstep: return smootherstep(t);
        default:                          return easeLinear(t);
    }
}