@guinetik/gcanvas 1.0.0

package/src/motion/orbit.js

@@ -0,0 +1,49 @@
+import { Motion } from "./motion";
+
+/**
+ * Orbit motion animation (circular or elliptical)
+ *
+ * @param {number} centerX - X coordinate of orbit center
+ * @param {number} centerY - Y coordinate of orbit center
+ * @param {number} radiusX - X radius of the orbit (horizontal)
+ * @param {number} radiusY - Y radius of the orbit (vertical)
+ * @param {number} startAngle - Starting angle in radians
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one full orbit in seconds
+ * @param {boolean} [loop=true] - Whether animation should loop
+ * @param {boolean} [clockwise=true] - Direction of orbit
+ * @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 orbitV1(
+  centerX,
+  centerY,
+  radiusX,
+  radiusY,
+  startAngle,
+  elapsedTime,
+  duration,
+  loop = true,
+  clockwise = true,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Update animation time and apply easing
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+  // Calculate current angle
+  const direction = clockwise ? 1 : -1;
+  const angle = startAngle + direction * easedT * Math.PI * 2;
+  // Convert polar coordinates to Cartesian
+  const x = centerX + radiusX * Math.cos(angle);
+  const y = centerY + radiusY * Math.sin(angle);
+  // Return standardized result
+  return Motion.animationResult({ x, y, angle }, t, loop, completed, newState);
+}

package/src/motion/oscillate.js

@@ -0,0 +1,39 @@
+import { Motion } from "./motion";
+
+/**
+ * Oscillate between min and max value using sine
+ *
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one full oscillation in seconds
+ * @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
+ * @returns {Object} Animation result with value and metadata
+ */
+export function oscillateV1(
+  min,
+  max,
+  elapsedTime,
+  duration,
+  loop = true,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Update animation time and apply easing
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+  // Calculate oscillation using sine
+  const amplitude = (max - min) / 2;
+  const center = min + amplitude;
+  const value = center + amplitude * Math.sin(easedT * Math.PI * 2);
+  // Return standardized result
+  return Motion.animationResult({ value }, t, loop, completed, newState);
+}

package/src/motion/parabolic.js

@@ -0,0 +1,141 @@
+import { Motion } from "./motion";
+
+/**
+ * Parabolic arc interpolation
+ *
+ * @param {number} start - Start value
+ * @param {number} peak - Peak value
+ * @param {number} end - End value
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of animation in seconds
+ * @param {boolean} [loop=false] - Whether animation should loop (restart from beginning)
+ * @param {boolean} [yoyo=false] - Whether animation should reverse direction at the end
+ * @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 value and metadata
+ */
+export function parabolicV1(
+  start,
+  peak,
+  end,
+  elapsedTime,
+  duration,
+  loop = false,
+  yoyo = false,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Initialize state if needed
+  if (!state) {
+    state = {
+      started: false,
+      loopCount: 0,
+      direction: 1, // 1 = forward, -1 = backward (for yoyo)
+      lastDirection: 1,
+      completed: false,
+    };
+  }
+  // Calculate normalized time (0-1)
+  let t = duration > 0 ? elapsedTime / duration : 1;
+  let completed = false;
+  let activeCallbacks = { ...callbacks };
+  // Handle yoyo and loop logic
+  if (yoyo || loop) {
+    // For yoyo + loop, or just loop: calculate cycle
+    if (loop) {
+      if (yoyo) {
+        // For yoyo + loop: full cycle is 2x duration (forward + backward)
+        const fullCycle = duration * 2;
+        const cycleTime = elapsedTime % fullCycle;
+        const cycleCount = Math.floor(elapsedTime / fullCycle);
+
+        // Determine direction and adjusted t
+        const newDirection = cycleTime < duration ? 1 : -1;
+        t =
+          newDirection === 1 ? cycleTime / duration : 2 - cycleTime / duration;
+
+        // Check for direction change for callbacks
+        if (newDirection !== state.direction) {
+          state.direction = newDirection;
+          if (state.direction === 1 && activeCallbacks.onLoop) {
+            activeCallbacks.onLoop(cycleCount);
+          }
+        }
+
+        // Track loop count
+        if (cycleCount > state.loopCount) {
+          state.loopCount = cycleCount;
+        }
+      } else {
+        // Just loop, no yoyo: reset t at each cycle
+        t = t % 1;
+
+        // Track loop count for callbacks
+        const newLoopCount = Math.floor(elapsedTime / duration);
+        if (newLoopCount > state.loopCount && activeCallbacks.onLoop) {
+          activeCallbacks.onLoop(newLoopCount);
+          state.loopCount = newLoopCount;
+        }
+      }
+    } else if (yoyo && !loop) {
+      // Yoyo without loop: complete one cycle then stop
+      if (t <= 1) {
+        // Forward part of the cycle
+        state.direction = 1;
+      } else if (t <= 2) {
+        // Backward part of the cycle
+        t = 2 - t;
+        state.direction = -1;
+      } else {
+        // Complete
+        t = 0;
+        completed = true;
+        state.direction = 1;
+      }
+    }
+  } else {
+    // No loop or yoyo: standard behavior
+    if (t >= 1) {
+      t = 1;
+      completed = true;
+    }
+  }
+  // Call onStart callback once
+  if (!state.started && activeCallbacks.onStart) {
+    activeCallbacks.onStart();
+    state.started = true;
+  }
+  // Call onComplete callback once when non-looping animation completes
+  if (completed && !state.completed && activeCallbacks.onComplete) {
+    activeCallbacks.onComplete();
+    state.completed = true;
+  }
+  // Apply easing if provided
+  const easedT = easingFn ? easingFn(t) : t;
+  // Calculate quadratic coefficients
+  // For a parabola that passes through three points: (0,start), (0.5,peak), (1,end)
+  const a = start + end - 2 * peak;
+  const b = 2 * (peak - start);
+  const c = start;
+  // Apply the quadratic formula: a*t^2 + b*t + c
+  const value = a * easedT * easedT + b * easedT + c;
+  // Update state for next frame
+  const newState = {
+    ...state,
+    lastDirection: state.direction,
+    completed: completed || state.completed,
+  };
+  // Return standardized result
+  return Motion.animationResult(
+    {
+      value,
+      direction: state.direction, // Include current direction (1 = forward, -1 = backward)
+    },
+    t,
+    loop || (yoyo && !completed),
+    completed,
+    newState
+  );
+}

package/src/motion/patrol.js

@@ -0,0 +1,147 @@
+import { Motion } from "./motion";
+/**
+ * Simple patrol animation that moves randomly within a radius
+ * Character moves along cardinal directions with waiting periods
+ * @function patrolV1
+ * @param {number} initialX - Initial X position (center point)
+ * @param {number} initialY - Initial Y position (center point)
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} moveTime - Time to spend moving between points
+ * @param {number} waitTime - Time to wait at each point
+ * @param {number} radius - Maximum distance from center point
+ * @param {boolean} [loop=true] - Whether animation should loop
+ * @param {Object} [state] - Internal state tracking
+ * @returns {Object} Animation result with position and direction
+ *
+ * @section Metadata
+ * @property {boolean} requiresState - Indicates this animation must be called with a persistent state object across frames.
+ * This ensures consistent behavior (e.g. waypoint progress, direction, internal timers).
+ * You should initialize and reuse a `state` object outside the update loop.
+ */
+export function patrolV1(
+  initialX,
+  initialY,
+  elapsedTime,
+  moveTime,
+  waitTime,
+  radius,
+  loop = true,
+  state = null
+) {
+  // Initialize state if not provided
+  if (!state) {
+    state = {
+      currentX: initialX,
+      currentY: initialY,
+      targetX: initialX,
+      targetY: initialY,
+      isWaiting: true,
+      waitStartTime: 0,
+      moveStartTime: 0,
+      moveCount: 0,
+      direction: "idle",
+    };
+  }
+  // Create a simple random function
+  const rand = () => Math.random();
+  // Calculate time and movement state
+  let isWaiting = state.isWaiting;
+  let x = state.currentX;
+  let y = state.currentY;
+  let direction = state.direction;
+  // Check if we need to transition between waiting and moving
+  if (isWaiting) {
+    // Currently waiting
+    if (elapsedTime - state.waitStartTime >= waitTime) {
+      // Wait period is over, pick a new target point
+      isWaiting = false;
+      state.moveStartTime = elapsedTime;
+      // Choose a new cardinal direction (up, down, left, right)
+      const directions = ["up", "down", "left", "right"];
+      direction = directions[Math.floor(rand() * 4)];
+      // Calculate potential new target based on direction
+      let newTargetX = state.currentX;
+      let newTargetY = state.currentY;
+      // Random move distance (20-80% of radius)
+      const moveDistance = radius * (0.2 + rand() * 0.6);
+      // handle direction by manipulating corresponding position
+      switch (direction) {
+        case "up":
+          newTargetY = state.currentY - moveDistance;
+          break;
+        case "down":
+          newTargetY = state.currentY + moveDistance;
+          break;
+        case "left":
+          newTargetX = state.currentX - moveDistance;
+          break;
+        case "right":
+          newTargetX = state.currentX + moveDistance;
+          break;
+      }
+      // If new target would be outside radius, move toward center instead
+      const newDistSq =
+        Math.pow(newTargetX - initialX, 2) + Math.pow(newTargetY - initialY, 2);
+      if (newDistSq > radius * radius) {
+        // Move back toward center
+        if (direction === "up" || direction === "down") {
+          // Moving vertically, adjust Y
+          newTargetY = initialY;
+          direction = state.currentY > initialY ? "up" : "down";
+        } else {
+          // Moving horizontally, adjust X
+          newTargetX = initialX;
+          direction = state.currentX > initialX ? "left" : "right";
+        }
+      }
+      // Update State
+      state.targetX = newTargetX;
+      state.targetY = newTargetY;
+      state.direction = direction;
+      state.moveCount++;
+    }
+  } else {
+    // Currently moving
+    const moveProgress = (elapsedTime - state.moveStartTime) / moveTime;
+    if (moveProgress >= 1) {
+      // Reached target, start waiting
+      isWaiting = true;
+      state.waitStartTime = elapsedTime;
+      state.currentX = state.targetX;
+      state.currentY = state.targetY;
+      direction = "idle";
+    } else {
+      // Interpolate position
+      x = state.currentX + (state.targetX - state.currentX) * moveProgress;
+      y = state.currentY + (state.targetY - state.currentY) * moveProgress;
+    }
+  }
+  // Update state
+  state.isWaiting = isWaiting;
+  state.direction = direction;
+  if (!isWaiting) {
+    state.currentX = x;
+    state.currentY = y;
+  }
+  // Calculate t value (0-1)
+  const cycleTime = moveTime + waitTime;
+  const t = (elapsedTime % cycleTime) / cycleTime;
+  // Calculate distance from center
+  const distanceFromCenter = Math.sqrt(
+    Math.pow(x - initialX, 2) + Math.pow(y - initialY, 2)
+  );
+  // Return result
+  return Motion.animationResult(
+    {
+      x,
+      y,
+      moving: !isWaiting,
+      direction,
+      distanceFromCenter,
+    },
+    t,
+    loop,
+    false,
+    state
+  );
+}

package/src/motion/pendulum.js

@@ -0,0 +1,48 @@
+import { Motion } from "./motion";
+
+/**
+ * Pendulum animation - swings around a center angle with optional damping
+ *
+ * @param {number} originAngle - Resting angle in radians (typically 0)
+ * @param {number} amplitude - Maximum swing from center (in radians)
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Time for one full swing (left-right-left)
+ * @param {boolean} [loop=true] - Whether the animation loops
+ * @param {boolean} [damped=false] - If true, swing slows down over time
+ * @param {Function} [easingFn=null] - Optional easing function
+ * @param {Object} [callbacks={}] - Optional callback functions
+ * @param {Object} [state=null] - Internal state tracking
+ * @returns {Object} Animation result with angle and metadata
+ */
+export function pendulumV1(
+  originAngle,
+  amplitude,
+  elapsedTime,
+  duration,
+  loop = true,
+  damped = false,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, null, callbacks, state); // <- remove easing here
+
+  // Optional decay multiplier (energy loss)
+  const decay = damped && !loop ? Math.exp(-4 * t) : 1;
+
+  // Oscillate with cosine (max at start, zero at center)
+  let angle = originAngle + amplitude * Math.cos(easedT * 2 * Math.PI) * decay;
+
+  // Apply optional easing to the *angle*, not the time
+  if (easingFn) {
+    const normalized = (angle - originAngle) / (amplitude * decay);
+    angle = originAngle + easingFn((normalized + 1) / 2) * amplitude * decay * 2 - amplitude * decay;
+  }
+
+  return Motion.animationResult({ angle }, t, loop, completed, newState);
+}

package/src/motion/pulse.js

@@ -0,0 +1,88 @@
+import { Easing } from "./easing";
+import { Motion } from "./motion";
+import { Tween } from "./tween";
+/**
+ * Pulse between min and max value and back
+ *
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one full pulse in seconds
+ * @param {boolean} [loop=true] - Whether animation should loop
+ * @param {boolean} [yoyo=false] - Whether to use separate easing for return journey
+ * @param {Function} [easingFn=null] - Optional easing function to apply
+ * @param {Object} [callbacks] - Optional callback functions
+ * @returns {Object} Animation result with value and metadata
+ */
+export function pulseV1(
+  min,
+  max,
+  elapsedTime,
+  duration,
+  loop = true,
+  yoyo = false,
+  easingFn = null,
+  callbacks = {}
+) {
+  // Normalize time (0-1) within current cycle
+  let t = elapsedTime / duration;
+  let phase = "forward";
+  // Handle looping vs. non-looping
+  if (loop) {
+    // Calculate loop count (for callbacks)
+    const loopCount = Math.floor(t);
+    // Use only the fractional part for looping (0-1 repeating)
+    t = t % 1;
+    // Call onLoop callback if provided and we crossed a loop boundary
+    if (loopCount > 0 && callbacks.onLoop) {
+      callbacks.onLoop(loopCount);
+    }
+  } else {
+    // Clamp to 1 for non-looping animations
+    if (t > 1) t = 1;
+  }
+  // Call onStart callback if needed
+  if (t > 0 && elapsedTime <= duration && callbacks.onStart) {
+    callbacks.onStart();
+  }
+  let value;
+  if (yoyo) {
+    // Yoyo approach - separate forward and return journeys
+    if (t < 0.5) {
+      // Forward journey (0 to 0.5 becomes 0 to 1)
+      const adjustedT = t * 2;
+      // Apply easing if provided
+      const easedT = easingFn ? easingFn(adjustedT) : adjustedT;
+      // Interpolate from min to max
+      value = min + (max - min) * easedT;
+      phase = "forward";
+    } else {
+      // Return journey (0.5 to 1 becomes 0 to 1)
+      const adjustedT = (t - 0.5) * 2;
+      // Apply easing if provided
+      const easedT = easingFn ? easingFn(adjustedT) : adjustedT;
+      // Interpolate from max to min
+      value = max - (max - min) * easedT;
+      phase = "return";
+      // Call onYoyoTurn callback at the turning point
+      if (t >= 0.5 && t < 0.51 && callbacks.onYoyoTurn) {
+        callbacks.onYoyoTurn();
+      }
+    }
+  } else {
+    // Standard pulse approach (triangle wave)
+    // Apply easing to normalized time if provided
+    const easedT = easingFn ? easingFn(t) : t;
+    // Convert to 0-1-0 pattern
+    const adjusted = easedT < 0.5 ? easedT * 2 : 2 - easedT * 2;
+    value = min + (max - min) * adjusted;
+  }
+  // Check if non-looping animation is complete
+  const isDone = !loop && t >= 1;
+  // Call onComplete if animation has completed
+  if (isDone && callbacks.onComplete) {
+    callbacks.onComplete();
+  }
+  // Return standardized result
+  return Motion.animationResult({ value, phase }, t, loop, isDone);
+}

package/src/motion/shake.js

@@ -0,0 +1,83 @@
+import { Motion } from "./motion";
+
+/**
+ * Shake animation with decreasing intensity
+ *
+ * @param {number} centerX - Center X position
+ * @param {number} centerY - Center Y position
+ * @param {number} maxOffsetX - Maximum X offset
+ * @param {number} maxOffsetY - Maximum Y offset
+ * @param {number} frequency - Frequency of shakes
+ * @param {number} decay - How quickly the shake decreases (0-1)
+ * @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 shakeV1(
+  centerX,
+  centerY,
+  maxOffsetX,
+  maxOffsetY,
+  frequency,
+  decay,
+  elapsedTime,
+  duration,
+  loop = false,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Update animation time and apply easing
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+
+  // Apply decay to reduce shake over time
+  const intensity = Math.pow(1 - easedT, decay);
+
+  // Create randomized but deterministic shake using sine/cosine at different frequencies
+  const angleX = easedT * Math.PI * 2 * frequency;
+  const angleY = easedT * Math.PI * 2 * frequency * 1.3; // Different frequency for Y
+
+  // Add multiple sine waves at different frequencies for more organic motion
+  const xOffset =
+    intensity *
+    maxOffsetX *
+    (Math.sin(angleX) * 0.6 +
+      Math.sin(angleX * 2.5) * 0.3 +
+      Math.sin(angleX * 5.6) * 0.1);
+
+  const yOffset =
+    intensity *
+    maxOffsetY *
+    (Math.cos(angleY) * 0.6 +
+      Math.cos(angleY * 2.7) * 0.3 +
+      Math.cos(angleY * 6.3) * 0.1);
+
+  // Make sure we end at the center
+  let x = centerX + xOffset;
+  let y = centerY + yOffset;
+
+  // Gradually return to center in the last 10% of the animation
+  if (easedT > 0.9) {
+    const returnT = (easedT - 0.9) / 0.1;
+    x = centerX + xOffset * (1 - returnT);
+    y = centerY + yOffset * (1 - returnT);
+  }
+
+  // Return standardized result
+  return Motion.animationResult(
+    { x, y, intensity },
+    t,
+    loop,
+    completed,
+    newState
+  );
+}