esengine/packages/math/src/Animation/Easing.ts

/**
 * 缓动函数集合
 * 
 * 提供各种常用的缓动函数，用于创建平滑的动画效果
 * 所有函数接受时间参数 t (0-1)，返回缓动后的值 (通常0-1)
 */
export class Easing {
  
  // 线性缓动
  
  /**
   * 线性缓动（无缓动）
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static linear(t: number): number {
    return t;
  }

  // 二次方缓动 (Quadratic)

  /**
   * 二次方缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quadIn(t: number): number {
    return t * t;
  }

  /**
   * 二次方缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quadOut(t: number): number {
    return 1 - (1 - t) * (1 - t);
  }

  /**
   * 二次方缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quadInOut(t: number): number {
    return t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t);
  }

  // 三次方缓动 (Cubic)

  /**
   * 三次方缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static cubicIn(t: number): number {
    return t * t * t;
  }

  /**
   * 三次方缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static cubicOut(t: number): number {
    return 1 - Math.pow(1 - t, 3);
  }

  /**
   * 三次方缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static cubicInOut(t: number): number {
    return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
  }

  // 四次方缓动 (Quartic)

  /**
   * 四次方缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quartIn(t: number): number {
    return t * t * t * t;
  }

  /**
   * 四次方缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quartOut(t: number): number {
    return 1 - Math.pow(1 - t, 4);
  }

  /**
   * 四次方缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quartInOut(t: number): number {
    return t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2;
  }

  // 五次方缓动 (Quintic)

  /**
   * 五次方缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quintIn(t: number): number {
    return t * t * t * t * t;
  }

  /**
   * 五次方缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quintOut(t: number): number {
    return 1 - Math.pow(1 - t, 5);
  }

  /**
   * 五次方缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static quintInOut(t: number): number {
    return t < 0.5 ? 16 * t * t * t * t * t : 1 - Math.pow(-2 * t + 2, 5) / 2;
  }

  // 正弦缓动 (Sine)

  /**
   * 正弦缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static sineIn(t: number): number {
    return 1 - Math.cos((t * Math.PI) / 2);
  }

  /**
   * 正弦缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static sineOut(t: number): number {
    return Math.sin((t * Math.PI) / 2);
  }

  /**
   * 正弦缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static sineInOut(t: number): number {
    return -(Math.cos(Math.PI * t) - 1) / 2;
  }

  // 指数缓动 (Exponential)

  /**
   * 指数缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static expoIn(t: number): number {
    return t === 0 ? 0 : Math.pow(2, 10 * (t - 1));
  }

  /**
   * 指数缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static expoOut(t: number): number {
    return t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
  }

  /**
   * 指数缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static expoInOut(t: number): number {
    if (t === 0) return 0;
    if (t === 1) return 1;
    
    return t < 0.5 
      ? Math.pow(2, 20 * t - 10) / 2
      : (2 - Math.pow(2, -20 * t + 10)) / 2;
  }

  // 圆形缓动 (Circular)

  /**
   * 圆形缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static circIn(t: number): number {
    return 1 - Math.sqrt(1 - t * t);
  }

  /**
   * 圆形缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static circOut(t: number): number {
    return Math.sqrt(1 - (t - 1) * (t - 1));
  }

  /**
   * 圆形缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static circInOut(t: number): number {
    return t < 0.5
      ? (1 - Math.sqrt(1 - 4 * t * t)) / 2
      : (Math.sqrt(1 - (-2 * t + 2) * (-2 * t + 2)) + 1) / 2;
  }

  // 回弹缓动 (Back)

  /**
   * 回弹缓入
   * @param t 时间参数 (0-1)
   * @param s 回弹强度，默认1.70158
   * @returns 缓动值
   */
  static backIn(t: number, s: number = 1.70158): number {
    const c1 = s;
    const c3 = c1 + 1;
    return c3 * t * t * t - c1 * t * t;
  }

  /**
   * 回弹缓出
   * @param t 时间参数 (0-1)
   * @param s 回弹强度，默认1.70158
   * @returns 缓动值
   */
  static backOut(t: number, s: number = 1.70158): number {
    const c1 = s;
    const c3 = c1 + 1;
    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
  }

  /**
   * 回弹缓入缓出
   * @param t 时间参数 (0-1)
   * @param s 回弹强度，默认1.70158
   * @returns 缓动值
   */
  static backInOut(t: number, s: number = 1.70158): number {
    const c1 = s;
    const c2 = c1 * 1.525;

    return t < 0.5
      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
  }

  // 弹性缓动 (Elastic)

  /**
   * 弹性缓入
   * @param t 时间参数 (0-1)
   * @param amplitude 振幅，默认1
   * @param period 周期，默认0.3
   * @returns 缓动值
   */
  static elasticIn(t: number, amplitude: number = 1, period: number = 0.3): number {
    if (t === 0) return 0;
    if (t === 1) return 1;

    const s = period / 4;
    return -(amplitude * Math.pow(2, 10 * (t - 1)) * Math.sin((t - 1 - s) * (2 * Math.PI) / period));
  }

  /**
   * 弹性缓出
   * @param t 时间参数 (0-1)
   * @param amplitude 振幅，默认1
   * @param period 周期，默认0.3
   * @returns 缓动值
   */
  static elasticOut(t: number, amplitude: number = 1, period: number = 0.3): number {
    if (t === 0) return 0;
    if (t === 1) return 1;

    const s = period / 4;
    return amplitude * Math.pow(2, -10 * t) * Math.sin((t - s) * (2 * Math.PI) / period) + 1;
  }

  /**
   * 弹性缓入缓出
   * @param t 时间参数 (0-1)
   * @param amplitude 振幅，默认1
   * @param period 周期，默认0.45
   * @returns 缓动值
   */
  static elasticInOut(t: number, amplitude: number = 1, period: number = 0.45): number {
    if (t === 0) return 0;
    if (t === 1) return 1;

    const s = period / 4;
    
    if (t < 0.5) {
      return -0.5 * (amplitude * Math.pow(2, 10 * (2 * t - 1)) * Math.sin((2 * t - 1 - s) * (2 * Math.PI) / period));
    }
    
    return amplitude * Math.pow(2, -10 * (2 * t - 1)) * Math.sin((2 * t - 1 - s) * (2 * Math.PI) / period) * 0.5 + 1;
  }

  // 跳跃缓动 (Bounce)

  /**
   * 跳跃缓入
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static bounceIn(t: number): number {
    return 1 - Easing.bounceOut(1 - t);
  }

  /**
   * 跳跃缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static bounceOut(t: number): number {
    const n1 = 7.5625;
    const d1 = 2.75;

    if (t < 1 / d1) {
      return n1 * t * t;
    } else if (t < 2 / d1) {
      return n1 * (t -= 1.5 / d1) * t + 0.75;
    } else if (t < 2.5 / d1) {
      return n1 * (t -= 2.25 / d1) * t + 0.9375;
    } else {
      return n1 * (t -= 2.625 / d1) * t + 0.984375;
    }
  }

  /**
   * 跳跃缓入缓出
   * @param t 时间参数 (0-1)
   * @returns 缓动值
   */
  static bounceInOut(t: number): number {
    return t < 0.5
      ? (1 - Easing.bounceOut(1 - 2 * t)) / 2
      : (1 + Easing.bounceOut(2 * t - 1)) / 2;
  }

  // 组合缓动

  /**
   * 创建自定义缓动函数（组合多个缓动）
   * @param easingFunctions 缓动函数数组
   * @param weights 权重数组，默认均等
   * @returns 组合后的缓动函数
   */
  static combine(
    easingFunctions: ((t: number) => number)[],
    weights?: number[]
  ): (t: number) => number {
    if (!weights) {
      weights = new Array(easingFunctions.length).fill(1 / easingFunctions.length);
    }

    return (t: number): number => {
      let result = 0;
      for (let i = 0; i < easingFunctions.length; i++) {
        result += easingFunctions[i](t) * (weights![i] || 0);
      }
      return result;
    };
  }

  /**
   * 创建分段缓动函数
   * @param segments 分段配置数组，每段包含 {duration, easing}
   * @returns 分段缓动函数
   */
  static piecewise(segments: Array<{duration: number; easing: (t: number) => number}>): (t: number) => number {
    // 计算总持续时间
    const totalDuration = segments.reduce((sum, seg) => sum + seg.duration, 0);
    
    // 归一化持续时间
    const normalizedSegments = segments.map(seg => ({
      ...seg,
      duration: seg.duration / totalDuration
    }));

    return (t: number): number => {
      let accumulatedTime = 0;
      
      for (const segment of normalizedSegments) {
        if (t <= accumulatedTime + segment.duration) {
          const localT = (t - accumulatedTime) / segment.duration;
          return segment.easing(Math.max(0, Math.min(1, localT)));
        }
        accumulatedTime += segment.duration;
      }
      
      // 如果超出范围，返回最后一段的结束值
      return normalizedSegments[normalizedSegments.length - 1].easing(1);
    };
  }

  /**
   * 创建反向缓动函数
   * @param easing 原缓动函数
   * @returns 反向缓动函数
   */
  static reverse(easing: (t: number) => number): (t: number) => number {
    return (t: number): number => 1 - easing(1 - t);
  }

  /**
   * 创建镜像缓动函数（先正向再反向）
   * @param easing 原缓动函数
   * @returns 镜像缓动函数
   */
  static mirror(easing: (t: number) => number): (t: number) => number {
    return (t: number): number => {
      if (t < 0.5) {
        return easing(t * 2);
      } else {
        return easing(2 - t * 2);
      }
    };
  }

  // 常用预设
  
  /** 平滑进入（常用于UI动画） */
  static readonly smoothIn = Easing.quadOut;
  
  /** 平滑退出（常用于UI动画） */
  static readonly smoothOut = Easing.quadIn;
  
  /** 快速进入（常用于出现动画） */
  static readonly quickIn = Easing.cubicOut;
  
  /** 快速退出（常用于消失动画） */
  static readonly quickOut = Easing.cubicIn;
  
  /** 自然运动（模拟物理） */
  static readonly natural = Easing.quartOut;
  
  /** 强调效果（吸引注意力） */
  static readonly emphasize = Easing.backOut;
}