@guinetik/gcanvas 1.0.0

package/src/motion/easing.js

@@ -0,0 +1,349 @@
+export class Easing {
+  // =========================================================================
+  // EASING FUNCTIONS
+  // =========================================================================
+
+  static lerp(a, b, t) {
+    return a + (b - a) * t;
+  }
+
+  /**
+   * Linear - no easing, straight line
+   * @param {number} t - Input (0-1)
+   * @returns {number} Same value as input
+   */
+  static linear(t) {
+    return t;
+  }
+
+  /**
+   * Smoothstep - classic shader S-curve interpolation
+   * Smooth start and end with zero first derivative at endpoints
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static smoothstep(t) {
+    return t * t * (3 - 2 * t);
+  }
+
+  /**
+   * Smootherstep - Ken Perlin's improved smoothstep
+   * Even smoother with zero first AND second derivatives at endpoints
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static smootherstep(t) {
+    return t * t * t * (t * (t * 6 - 15) + 10);
+  }
+
+  /**
+   * Quadratic ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInQuad(t) {
+    return t * t;
+  }
+
+  /**
+   * Quadratic ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutQuad(t) {
+    return t * (2 - t);
+  }
+
+  /**
+   * Quadratic ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutQuad(t) {
+    return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+  }
+
+  /**
+   * Cubic ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInCubic(t) {
+    return t * t * t;
+  }
+
+  /**
+   * Cubic ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutCubic(t) {
+    return --t * t * t + 1;
+  }
+
+  /**
+   * Cubic ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutCubic(t) {
+    return t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
+  }
+
+  /**
+   * Quartic ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInQuart(t) {
+    return t * t * t * t;
+  }
+
+  /**
+   * Quartic ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutQuart(t) {
+    return 1 - --t * t * t * t;
+  }
+
+  /**
+   * Quartic ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutQuart(t) {
+    return t < 0.5 ? 8 * t * t * t * t : 1 - 8 * --t * t * t * t;
+  }
+
+  /**
+   * Sine ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInSine(t) {
+    return 1 - Math.cos((t * Math.PI) / 2);
+  }
+
+  /**
+   * Sine ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutSine(t) {
+    return Math.sin((t * Math.PI) / 2);
+  }
+
+  /**
+   * Sine ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutSine(t) {
+    return -(Math.cos(Math.PI * t) - 1) / 2;
+  }
+
+  /**
+   * Exponential ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInExpo(t) {
+    return t === 0 ? 0 : Math.pow(2, 10 * (t - 1));
+  }
+
+  /**
+   * Exponential ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutExpo(t) {
+    return t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
+  }
+
+  /**
+   * Exponential ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutExpo(t) {
+    if (t === 0 || t === 1) return t;
+    if (t < 0.5) {
+      return 0.5 * Math.pow(2, 20 * t - 10);
+    } else {
+      return 0.5 * (2 - Math.pow(2, -20 * t + 10));
+    }
+  }
+
+  /**
+   * Circular ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInCirc(t) {
+    return 1 - Math.sqrt(1 - t * t);
+  }
+
+  /**
+   * Circular ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutCirc(t) {
+    return Math.sqrt(1 - --t * t);
+  }
+
+  /**
+   * Circular ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutCirc(t) {
+    return t < 0.5
+      ? 0.5 * (1 - Math.sqrt(1 - 4 * t * t))
+      : 0.5 * (Math.sqrt(-(2 * t - 3) * (2 * t - 1)) + 1);
+  }
+
+  /**
+   * Elastic ease-in
+   * @param {number} t - Input (0-1)
+   * @param {number} [amplitude=1] - Amplitude
+   * @param {number} [period=0.3] - Period
+   * @returns {number} Eased value
+   */
+  static easeInElastic(t, amplitude = 1, period = 0.3) {
+    if (t === 0 || t === 1) return t;
+
+    const s = (period / (2 * Math.PI)) * Math.asin(1 / amplitude);
+    return -(
+      amplitude *
+      Math.pow(2, 10 * (t - 1)) *
+      Math.sin(((t - 1 - s) * (2 * Math.PI)) / period)
+    );
+  }
+
+  /**
+   * Elastic ease-out
+   * @param {number} t - Input (0-1)
+   * @param {number} [amplitude=1] - Amplitude
+   * @param {number} [period=0.3] - Period
+   * @returns {number} Eased value
+   */
+  static easeOutElastic(t, amplitude = 1, period = 0.3) {
+    if (t === 0 || t === 1) return t;
+
+    const s = (period / (2 * Math.PI)) * Math.asin(1 / amplitude);
+    return (
+      amplitude *
+        Math.pow(2, -10 * t) *
+        Math.sin(((t - s) * (2 * Math.PI)) / period) +
+      1
+    );
+  }
+
+  /**
+   * Elastic ease-in-out
+   * @param {number} t - Input (0-1)
+   * @param {number} [amplitude=1] - Amplitude
+   * @param {number} [period=0.3] - Period
+   * @returns {number} Eased value
+   */
+  static easeInOutElastic(t, amplitude = 1, period = 0.3) {
+    if (t === 0 || t === 1) return t;
+
+    const s = (period / (2 * Math.PI)) * Math.asin(1 / amplitude);
+
+    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))
+      );
+    } else {
+      return (
+        amplitude *
+          Math.pow(2, -10 * (2 * t - 1)) *
+          Math.sin(((2 * t - 1 - s) * (2 * Math.PI)) / period) *
+          0.5 +
+        1
+      );
+    }
+  }
+
+  /**
+   * Back ease-in
+   * @param {number} t - Input (0-1)
+   * @param {number} [overshoot=1.70158] - Overshoot amount
+   * @returns {number} Eased value
+   */
+  static easeInBack(t, overshoot = 1.70158) {
+    return t * t * ((overshoot + 1) * t - overshoot);
+  }
+
+  /**
+   * Back ease-out
+   * @param {number} t - Input (0-1)
+   * @param {number} [overshoot=1.70158] - Overshoot amount
+   * @returns {number} Eased value
+   */
+  static easeOutBack(t, overshoot = 1.70158) {
+    return --t * t * ((overshoot + 1) * t + overshoot) + 1;
+  }
+
+  /**
+   * Back ease-in-out
+   * @param {number} t - Input (0-1)
+   * @param {number} [overshoot=1.70158] - Overshoot amount
+   * @returns {number} Eased value
+   */
+  static easeInOutBack(t, overshoot = 1.70158) {
+    const s = overshoot * 1.525;
+
+    if (t < 0.5) {
+      return 0.5 * (2 * t) * (2 * t) * ((s + 1) * 2 * t - s);
+    } else {
+      return (
+        0.5 * ((2 * t - 2) * (2 * t - 2) * ((s + 1) * (2 * t - 2) + s) + 2)
+      );
+    }
+  }
+
+  /**
+   * Bounce ease-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeOutBounce(t) {
+    if (t < 1 / 2.75) {
+      return 7.5625 * t * t;
+    } else if (t < 2 / 2.75) {
+      return 7.5625 * (t -= 1.5 / 2.75) * t + 0.75;
+    } else if (t < 2.5 / 2.75) {
+      return 7.5625 * (t -= 2.25 / 2.75) * t + 0.9375;
+    } else {
+      return 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375;
+    }
+  }
+
+  /**
+   * Bounce ease-in
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInBounce(t) {
+    return 1 - Easing.easeOutBounce(1 - t);
+  }
+
+  /**
+   * Bounce ease-in-out
+   * @param {number} t - Input (0-1)
+   * @returns {number} Eased value
+   */
+  static easeInOutBounce(t) {
+    return t < 0.5
+      ? Easing.easeInBounce(t * 2) * 0.5
+      : Easing.easeOutBounce(t * 2 - 1) * 0.5 + 0.5;
+  }
+}

package/src/motion/float.js

@@ -0,0 +1,130 @@
+import { Motion } from "./motion";
+
+/**
+ * Patrol animation - creates movement around an area with natural pausing
+ * Perfect for characters patrolling or objects drifting within bounds
+ *
+ * @param {Object} target - Object with x,y properties defining the center point
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one full float cycle in seconds
+ * @param {number} speed - Movement speed multiplier (0.1-2.0 recommended)
+ * @param {number} randomness - How random/unpredictable the float path is (0-1)
+ * @param {number} radius - Radius of float area (object will move within -radius to +radius)
+ * @param {boolean} [loop=true] - Whether animation should loop
+ * @param {Function} [easingFn=null] - Optional easing function to apply
+ * @param {Object} [callbacks] - Optional callback functions
+ * @param {Object} [state] - Internal state tracking for callbacks and initial position
+ * @returns {Object} Animation result with x, y coordinates and metadata
+ */
+export function floatV1(
+  target,
+  elapsedTime,
+  duration,
+  speed,
+  randomness,
+  radius,
+  loop = true,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Early return for zero duration
+  if (duration <= 0) {
+    return Motion.animationResult(
+      { x: target.x, y: target.y, moving: false },
+      1,
+      false,
+      true
+    );
+  }
+  // Initialize state if not provided, capturing initial position
+  if (!state) {
+    state = {
+      initialX: target.x,
+      initialY: target.y,
+      started: false,
+      completed: false,
+      loopCount: 0,
+    };
+  }
+  // Use initialX and initialY from state as the center point
+  const centerX = state.initialX;
+  const centerY = state.initialY;
+  // Update animation time and apply easing if needed
+  const {
+    t,
+    easedT,
+    completed,
+    state: timeState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+  // Update state with time tracking info
+  state = {
+    ...state,
+    ...timeState,
+  };
+  // Scale time by speed (higher speed = faster oscillations)
+  const scaledTime = elapsedTime * speed;
+  // Clamp randomness to valid range (0-1)
+  const clampedRandomness = Math.max(0, Math.min(1, randomness));
+  // Multi-layered sinusoidal movements with different frequencies
+  // to create patrol-like motion with natural pauses
+
+  // Primary motion (large, slow)
+  const baseFreqX = 0.7;
+  const baseFreqY = 0.9; // Slightly different to avoid perfect circles
+  // Secondary motion (direction changes)
+  const secondFreqX = 2.3;
+  const secondFreqY = 1.9;
+  // Calculate combined motion patterns
+  const dx =
+    Math.sin(scaledTime * baseFreqX) +
+    clampedRandomness * 0.4 * Math.sin(scaledTime * secondFreqX + 0.5);
+  const dy =
+    Math.cos(scaledTime * baseFreqY) +
+    clampedRandomness * 0.4 * Math.cos(scaledTime * secondFreqY + 0.7);
+  // Scale by radius - the multiplier is 0.5 because we want values to range from -radius to +radius
+  // This properly centers the patrol area around the initial position
+  const x = centerX + dx * radius;
+  const y = centerY + dy * radius;
+  //this.logger.log(x, y, centerX, centerY);
+  // Calculate if currently moving or paused
+  // Object "pauses" when velocity is low (near turning points of sine waves)
+  const dxdt =
+    baseFreqX * Math.cos(scaledTime * baseFreqX) +
+    clampedRandomness *
+      0.4 *
+      secondFreqX *
+      Math.cos(scaledTime * secondFreqX + 0.5);
+  const dydt =
+    -baseFreqY * Math.sin(scaledTime * baseFreqY) +
+    clampedRandomness *
+      0.4 *
+      -secondFreqY *
+      Math.sin(scaledTime * secondFreqY + 0.7);
+  // Calculate velocity magnitude
+  const velocity = Math.sqrt(dxdt * dxdt + dydt * dydt);
+  // Determine if moving or paused (using a threshold)
+  const isMoving = velocity > 0.8;
+  // Calculate distance from center
+  const distanceFromCenter = Math.sqrt(
+    (x - centerX) * (x - centerX) + (y - centerY) * (y - centerY)
+  );
+  // Return standardized result with patrol-specific metadata
+  return Motion.animationResult(
+    {
+      x,
+      y,
+      centerX,
+      centerY,
+      offsetX: x - centerX,
+      offsetY: y - centerY,
+      distance: distanceFromCenter,
+      moving: isMoving,
+      velocity: velocity,
+    },
+    t,
+    loop,
+    completed,
+    state
+  );
+}

package/src/motion/follow.js

@@ -0,0 +1,125 @@
+import { Motion } from "./motion";
+import { Tween } from "./tween";
+
+/**
+ * Follow path animation along a series of points
+ *
+ * @param {Array<Array<number>>} points - Array of points as [x, y] coordinates
+ * @param {boolean} [closed=false] - Whether path is closed (connects back to start)
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of animation in seconds
+ * @param {boolean} [loop=false] - Whether animation should loop
+ * @param {Function} [easingFn=null] - Optional easing function to apply
+ * @param {Object} [callbacks] - Optional callback functions
+ * @param {Object} [state] - Internal state tracking for callbacks
+ * @returns {Object} Animation result with x, y coordinates and metadata
+ */
+export function followPath(
+  points,
+  closed = false,
+  elapsedTime,
+  duration,
+  loop = false,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Need at least 2 points
+  if (!points || points.length < 2) {
+    return this._createResult({ x: 0, y: 0 }, 0, loop, false);
+  }
+  // Update animation time and apply easing
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+
+  // Calculate total path length and segment lengths
+  if (!state || !state.pathData) {
+    const pathData = {
+      segmentLengths: [],
+      totalLength: 0,
+      points: [...points],
+    };
+
+    // Calculate length of each segment
+    for (let i = 0; i < points.length - 1; i++) {
+      const p1 = points[i];
+      const p2 = points[i + 1];
+      const dx = p2[0] - p1[0];
+      const dy = p2[1] - p1[1];
+      const length = Math.sqrt(dx * dx + dy * dy);
+
+      pathData.segmentLengths.push(length);
+      pathData.totalLength += length;
+    }
+
+    // If closed, add final segment back to start
+    if (closed) {
+      const p1 = points[points.length - 1];
+      const p2 = points[0];
+      const dx = p2[0] - p1[0];
+      const dy = p2[1] - p1[1];
+      const length = Math.sqrt(dx * dx + dy * dy);
+
+      pathData.segmentLengths.push(length);
+      pathData.totalLength += length;
+    }
+
+    newState.pathData = pathData;
+  }
+
+  // Get path data
+  const { segmentLengths, totalLength, points: pathPoints } = newState.pathData;
+
+  // Calculate distance along path
+  const targetDistance = easedT * totalLength;
+
+  // Find which segment we're on and the progress through it
+  let distanceTraveled = 0;
+  let segmentIndex = 0;
+
+  for (let i = 0; i < segmentLengths.length; i++) {
+    if (distanceTraveled + segmentLengths[i] >= targetDistance) {
+      segmentIndex = i;
+      break;
+    }
+    distanceTraveled += segmentLengths[i];
+  }
+
+  // Calculate progress through current segment
+  const segmentProgress =
+    (targetDistance - distanceTraveled) / segmentLengths[segmentIndex];
+
+  // Get points for current segment
+  const p1 = pathPoints[segmentIndex];
+  const p2 =
+    segmentIndex < pathPoints.length - 1
+      ? pathPoints[segmentIndex + 1]
+      : pathPoints[0]; // Wrap to start if closed
+
+  // Interpolate between points
+  const x = Tween.lerp(p1[0], p2[0], segmentProgress);
+  const y = Tween.lerp(p1[1], p2[1], segmentProgress);
+
+  // Calculate angle of current segment (for rotation if needed)
+  const angle = Math.atan2(p2[1] - p1[1], p2[0] - p1[0]);
+
+  // Return standardized result
+  return Motion.animationResult(
+    {
+      x,
+      y,
+      angle,
+      segmentIndex,
+      segmentProgress,
+      pathProgress: easedT,
+    },
+    t,
+    loop,
+    completed,
+    newState
+  );
+}

package/src/motion/hop.js

@@ -0,0 +1,52 @@
+import { Motion } from "./motion";
+
+/**
+ * Hop animation - makes the object jump up and down rhythmically
+ *
+ * @param {number} baseY - The ground/base Y position
+ * @param {number} hopHeight - Maximum height (negative Y offset)
+ * @param {number} elapsedTime - Elapsed time in seconds
+ * @param {number} duration - Duration of one hop (up and down)
+ * @param {boolean} [loop=true] - Whether the hop repeats
+ * @param {boolean} [yoyo=true] - Whether the hop repeats
+ * @param {Function} [easingFn=null] - Optional easing for jump arc
+ * @param {Object} [callbacks={}] - Optional callback functions
+ * @param {Object} [state=null] - Internal state
+ * @returns {Object} Animation result with y position
+ */
+export function hopV1(
+  baseY,
+  hopHeight,
+  elapsedTime,
+  duration,
+  loop = true,
+  yoyo = true,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state, yoyo);
+
+  let arc = 0;
+
+  if (!loop && !yoyo) {
+    // One-shot up only: freeze at peak when done
+    arc = completed ? 1 : Math.sin(Math.min(t, 1) * Math.PI * 0.5); // sin(π/2 * t) = 0 → 1
+  } else if (yoyo) {
+    // Full up/down cycle using easedT (symmetric)
+    arc = Math.sin(easedT * Math.PI); // 0 → 1 → 0
+  } else {
+    // Looping up-only arc (snap to origin after)
+    arc = Math.sin(Math.min(t, 1) * Math.PI * 0.5); // sin(π/2 * t)
+  }
+
+  const y = baseY - hopHeight * arc;
+
+  return Motion.animationResult({ y }, t, loop, completed, newState);
+}
+