GSAP Integration Patterns

To use GSAP with Helios, you must drive the GSAP Timeline instance using the Helios frame state. This allows GSAP animations to be scrubbed, paused, and rendered frame-by-frame.

Quick Start

The "Paused Timeline" Pattern

1. Create a GSAP Timeline with paused: true.
2. Subscribe to Helios updates.
3. Inside the subscription, convert the Helios frame to seconds.
4. Call timeline.seek(seconds) to synchronize.

<script type="module">
  import { Helios } from '@helios-project/core';
  import { gsap } from 'gsap';

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

  // 2. Setup GSAP Timeline (PAUSED is critical)
  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,
    duration: 2
  });

  // 4. Subscribe and Sync
  helios.subscribe((state) => {
    // Convert frame count to seconds
    const timeInSeconds = state.currentFrame / helios.fps;

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

  // 5. Bind for Preview
  helios.bindToDocumentTimeline();
  window.helios = helios;
</script>

Critical Rules

1. Always Pause: The GSAP timeline must be initialized with { paused: true }. If it plays automatically, it will fight with Helios for control.
2. Use Seek: Do not use tl.progress() unless you calculate the normalized 0-1 value. tl.seek(seconds) is usually more direct since Helios knows FPS and Frame Count.
3. No requestAnimationFrame: Do not create your own rAF loop for GSAP. Let Helios drive the updates via subscribe.

Source Files

• Example: examples/gsap-animation/