GSAP(GreenSock Animation Platform)

• **GSAP (GreenSock Animation Platform)**은 JavaScript 기반의 고성능 애니메이션 라이브러리
• DOM 요소뿐 아니라 어떤 객체의 어떤 속성이든 애니메이션할 수 있는 범용 프로퍼티 세터
• Tween(단일 애니메이션)과 Timeline(시퀀싱 컨테이너)으로 구성되는 2-레벨 애니메이션 시스템

해당 개념이 필요한 이유

• Hyperframes에서 애니메이션은 GSAP 타임라인으로 정의하고, 프레임워크가 seekFrame()을 통해 스크러빙한다
• GSAP 타임라인을 { paused: true }로 만들고 window.__timelines에 등록하는 패턴이 Hyperframes의 핵심 규약
• CSS 애니메이션만으로는 프레임 단위 탐색(seek)이 어렵지만, GSAP은 timeline.totalTime(seconds)로 정확한 프레임 탐색이 가능

AS-IS — 딜레이 기반 수동 타이밍

// 각 애니메이션의 시작 시점을 수동으로 계산해야 함
gsap.to("#a", { x: 100, duration: 1, delay: 0 });
gsap.to("#b", { y: 50, duration: 1, delay: 1 });     // #a 끝난 후
gsap.to("#c", { opacity: 0, duration: 0.5, delay: 2 }); // #b 끝난 후
// 중간에 하나 바뀌면 이후 모든 delay를 수정해야 함

TO-BE — Timeline 시퀀싱

const tl = gsap.timeline({ paused: true });
tl.to("#a", { x: 100, duration: 1 })      // 0초부터 자동
  .to("#b", { y: 50, duration: 1 })        // #a 끝나면 자동
  .to("#c", { opacity: 0, duration: 0.5 }); // #b 끝나면 자동
// 하나를 수정해도 이후 타이밍이 자동으로 조정됨

Tween — 애니메이션의 최소 단위

Tween은 “대상 객체의 속성 값을 일정 시간에 걸쳐 변화시키는 단위”다.

3가지 생성 방식

메서드	의미	예시
gsap.to()	현재 값 → 목표 값	gsap.to("#box", { x: 100, duration: 1 })
gsap.from()	지정 값 → 현재 값	gsap.from("#box", { opacity: 0, duration: 1 })
gsap.fromTo()	시작 값 → 끝 값 모두 지정	gsap.fromTo("#box", { x: 0 }, { x: 100 })

주요 속성

속성	설명	기본값
duration	애니메이션 길이(초)	0.5
delay	시작 전 대기 시간(초)	0
ease	가감속 곡선	"power1.out"
repeat	반복 횟수 (-1 = 무한)	0
yoyo	반복 시 역방향 재생	false

Timeline — 시퀀싱 컨테이너

Timeline은 여러 Tween을 하나로 묶어 제어하는 컨테이너다.

Position Parameter — 배치의 핵심

세 번째 인자로 타임라인 내 정확한 배치를 지정한다:

const tl = gsap.timeline();
 
// 절대 시간
tl.to("#a", { x: 100 }, 3);         // 3초 지점에 배치
 
// 상대 시간
tl.to("#b", { y: 50 }, "+=1");      // 이전 끝 + 1초
tl.to("#c", { opacity: 0 }, "-=0.5"); // 이전 끝 - 0.5초 (오버랩)
 
// 이전 애니메이션 기준
tl.to("#d", { scale: 2 }, "<");      // 이전 시작과 동시에
tl.to("#e", { rotation: 90 }, ">");  // 이전 끝과 동시에

프로그래매틱 제어

tl.play();            // 재생
tl.pause();           // 일시정지
tl.seek(1.5);         // 1.5초 지점으로 점프
tl.totalTime(3);      // 3초 지점으로 이동 (repeat 포함)
tl.progress(0.5);     // 50% 지점으로 이동
tl.reverse();         // 역방향 재생
tl.duration();        // 전체 길이 반환

Hyperframes에서의 GSAP 사용 패턴

// 1. 반드시 paused: true
const tl = gsap.timeline({ paused: true });
 
// 2. 절대 위치 파라미터로 정확한 타이밍 지정
tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
tl.to("#subtitle", { opacity: 1, duration: 0.5 }, 1.5);
 
// 3. composition-id와 매칭하여 등록
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = tl;
 
// → 프레임워크가 tl.totalTime(frame/fps)로 각 프레임을 스크러빙

참고 문서

• GSAP Official Docs
• GSAP Timeline
• GSAP Tween
• Hyperframes GSAP Animation Guide