GSAP integration

Learn how to integrate GSAP animations with Helios for deterministic timeline control

GSAP is a powerful animation library that can be synchronized with Helios by pausing its timeline and seeking to specific time positions based on Helios frame updates.

Installation

Install GSAP alongside Helios:

npm install gsap @helios-project/core

Basic integration

The key to integrating GSAP with Helios is to:

1. Create a GSAP timeline with paused: true
2. Subscribe to Helios updates
3. Convert frame count to seconds
4. Seek the GSAP timeline to the exact time

import { Helios } from "@helios-project/core";
import { gsap } from "gsap";

// 1. Initialize Helios
const helios = new Helios({
  fps: 30,
  duration: 5,
});

// 2. Setup GSAP Timeline
// IMPORTANT: The timeline must be paused so Helios can drive it!
const tl = gsap.timeline({ paused: true });

// 3. Define animations
tl.to(".box", {
  rotation: 360,
  x: 100,
  duration: 2,
  ease: "power1.inOut"
})
.to(".box", {
  scale: 2,
  backgroundColor: "#00eeff",
  duration: 2,
  ease: "elastic.out(1, 0.3)"
})
.to(".box", {
  x: 0,
  scale: 1,
  duration: 1,
  ease: "power2.out"
});

// 4. Subscribe to Helios updates to drive GSAP
helios.subscribe((state) => {
  // Convert frame count to seconds
  const timeInSeconds = state.currentFrame / state.fps;

  // Seek the GSAP timeline to the exact time
  tl.seek(timeInSeconds);
});

// 5. Start Helios (bind to document timeline for preview)
helios.bindToDocumentTimeline();

Integration pattern

Timeline control

GSAP timelines must be created with paused: true to prevent automatic playback:

const tl = gsap.timeline({ paused: true });

This allows Helios to have full control over the timeline position.

Frame to time conversion

Convert Helios frame numbers to seconds for GSAP:

const timeInSeconds = state.currentFrame / state.fps;
tl.seek(timeInSeconds);

Using GSAP easing

GSAP provides powerful easing functions that work seamlessly:

tl.to(".element", {
  x: 100,
  duration: 2,
  ease: "elastic.out(1, 0.3)"
});

Common easing options:

• power1.inOut, power2.out, power3.in
• elastic.out(1, 0.3)
• bounce.out
• back.inOut(1.7)

Why this works

By pausing the GSAP timeline and manually seeking to specific time positions, Helios can:

• Ensure deterministic frame-by-frame rendering
• Enable scrubbing through the animation
• Support export to video formats
• Maintain synchronization across multiple animation systems

This pattern works with any GSAP feature including plugins, custom properties, and complex timelines.