example-gsap

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;

## 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/`