gsap

GSAP

使用場面

次の用途では GSAP を使用します。

• シーンの振り付け — 正確なタイミングで複数の要素を連続して動かす場合
• 複雑なタイムライン — 時差をつけたアニメーション、ラベル、ネストされたシーケンス
• テキスト／カードの動き — キャプション、タイトルカード、UI 要素の登場
• 音声と同期したアニメーション — ナレーションに合わせてビート単位で動きを調整する場合
• 大半のスクリプトアニメーション — GSAP は FrameVideo のデフォルトのアニメーションアダプターです

使用しないでください

次の用途では GSAP を避けてください。

• シンプルな装飾用ループ — css-animations を使用します（シマー、パルス、グロー）
• デザイナーが提供した After Effects の書き出しデータ — lottie を使用します
• 3D シーンと WebGL — three を使用します
• GPU 計算シェーダー — typegpu を使用します
• 依存関係を一切追加できない場合 — waapi を使用します

迷った場合は、GSAP を使用してください。最も汎用性が高く、デフォルトの選択肢です。

---

クイックスタート

FrameVideo での最小限の GSAP アニメーション：

<div data-composition-id="main" data-width="1920" data-height="1080">
  <div class="clip" data-start="0" data-duration="3">
    <h1 class="title">Hello GSAP</h1>
  </div>
</div>

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });
  
  // Fade in and slide up
  tl.from(".title", { 
    y: 48, 
    opacity: 0, 
    duration: 0.6, 
    ease: "power3.out" 
  }, 0);
  
  window.__timelines["main"] = tl;
</script>

重要なポイント：

1. CDN から GSAP を読み込みます
2. 一時停止状態のタイムラインを作成します
3. タイミングを指定してトゥイーンを追加します
4. 一致するコンポジション ID を使って、window.__timelines に登録します

---

FrameVideo の契約

FrameVideo は gsap ランタイムアダプターを通じて GSAP を制御します。一時停止状態のタイムラインを同期的に作成し、正確な data-composition-id とともに window.__timelines に登録すると、FrameVideo がシークします。

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
</script>

• 登録キーは、コンポジションのルート要素の data-composition-id と一致させる必要があります。
• レンダリング上重要な動きでは、tl.play() を呼び出さないでください。
• 非同期コード、タイマー、イベントハンドラー内でタイムラインを構築しないでください。
• ループは有限にしてください。FrameVideo は有限の動画時間をレンダリングします。

基本的なトゥイーンメソッド

• gsap.to(targets, vars) — 現在の状態から vars に向けてアニメーションします。最も一般的なメソッドです。
• gsap.from(targets, vars) — vars から現在の状態に向けてアニメーションします（登場時）。
• gsap.fromTo(targets, fromVars, toVars) — 開始状態と終了状態を明示的に指定します。
• gsap.set(targets, vars) — 即座に適用します（duration 0）。

プロパティ名には必ず camelCase を使用してください（例：backgroundColor、rotationX）。

よく使う vars

• duration — 秒単位（デフォルトは 0.5）。
• delay — 開始までの秒数。
• ease — "power1.out"（デフォルト）、"power3.inOut"、"back.out(1.7)"、"elastic.out(1, 0.3)"、"none"。
• stagger — 数値 0.1、またはオブジェクト：{ amount: 0.3, from: "center" }、{ each: 0.1, from: "random" }。
• overwrite — false（デフォルト）、true、または "auto"。
• repeat — 有限の数値を指定します。FrameVideo では -1 を使用しないでください。表示時間から繰り返し回数を計算します。yoyo — repeat に応じて方向を交互に切り替えます。
• onComplete、onStart、onUpdate — コールバック。
• immediateRender — from()/fromTo() ではデフォルトで true です。同じプロパティと要素を対象とする後続のトゥイーンで上書きを避けるには、false に設定します。

トランスフォームと CSS

生の transform 文字列よりも、GSAP の トランスフォームエイリアスを優先してください。

GSAP プロパティ	相当するプロパティ
x、y、z	translateX/Y/Z（px）
xPercent、yPercent	translateX/Y（%）
scale、scaleX、scaleY	scale
rotation	rotate（deg）
rotationX、rotationY	3D rotate
skewX、skewY	skew
transformOrigin	transform-origin

• autoAlpha — opacity よりもこちらを優先してください。値が 0 の場合、visibility: hidden も設定されます。
• CSS 変数 — "--hue": 180。
• svgOrigin (SVG のみ) — グローバルな SVG 座標空間の原点です。transformOrigin と組み合わせないでください。
• 方向付き回転 — "360_cw"、"-170_short"、"90_ccw"。
• clearProps — "all" またはカンマ区切りの値を指定します。完了時にインラインスタイルを削除します。
• 相対値 — "+=20"、"-=10"、"*=2"。

関数ベースの値

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

イージング

組み込みのイージング：power1～power4、back、bounce、circ、elastic、expo、sine。それぞれに .in、.out、.inOut があります。

デフォルト値

gsap.defaults({ duration: 0.6, ease: "power2.out" });

トゥイーンの制御

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia()（レスポンシブ + アクセシビリティ）

メディアクエリが一致した場合にのみセットアップを実行し、一致しなくなると自動的に元に戻します。

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

---

タイムライン

タイムラインの作成

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

位置パラメーター

3 番目の引数で配置を指定します。

• 絶対位置：1 — 1 秒時点
• 相対位置："+=0.5" — 終了後、"-=0.2" — 終了前
• ラベル："intro"、"intro+=0.3"
• 位置合わせ："<" — 前のアニメーションと同じ開始位置、">" — 前のアニメーションの終了後、"<0.2" — 前のアニメーションの開始から 0.2 秒後

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // same start as .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts

ラベル

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

タイムラインのオプション

• paused: true — 一時停止状態で作成します。開始するには .play() を呼び出します。
• repeat、yoyo — タイムライン全体に適用されます。
• defaults — すべての子トゥイーンにマージされる変数です。

タイムラインのネスト

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

再生の制御

tl.play()、tl.pause()、tl.reverse()、tl.restart()、tl.time(2)、tl.progress(0.5)、tl.kill()。

---

パフォーマンス

transform と opacity を優先する

x、y、scale、rotation、opacity のアニメーションはコンポジター上で実行されます。transform で同じ効果を実現できる場合は、width、height、top、left を避けてください。

will-change

will-change: transform;

実際にアニメーションする要素にのみ指定してください。

頻繁な更新には gsap.quickTo()

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

多数のトゥイーンより stagger

手動で遅延を指定した個別のトゥイーンではなく、stagger を使用してください。

クリーンアップ

画面外のアニメーションは一時停止するか、終了させてください。

---

参考資料（必要に応じて読み込み）

• references/effects.md — すぐに使えるエフェクト：タイプライター風テキスト、オーディオビジュアライザー。FrameVideo 用のすぐに使えるエフェクトパターンが必要な場合に読みます。

ベストプラクティス

• プロパティ名には camelCase を使用し、transform のエイリアスと autoAlpha を優先してください。
• delay を使った連鎖よりタイムラインを優先し、位置パラメーターを使用してください。
• addLabel() でラベルを追加し、シーケンスを読みやすくしてください。
• タイムラインのコンストラクターにデフォルト値を渡してください。
• 再生を制御する場合は、トゥイーンまたはタイムラインの戻り値を保存してください。

避けるべきこと

• transform で十分な場合に、レイアウトプロパティ（width／height／top／left）をアニメーションさせないでください。
• 同じ SVG 要素で svgOrigin と transformOrigin の両方を使用しないでください。
• タイムラインで順序を指定できる場合に、delay でアニメーションを連鎖させないでください。
• DOM が存在する前にトゥイーンを作成しないでください。
• クリーンアップを省略しないでください。不要になったトゥイーンは必ず終了させてください。
• FrameVideo のコンポジションで無限リピート値を使用しないでください。表示時間から計算した有限のリピート回数を使用してください。

検証

GSAP アニメーションを記述した後：

npx framevideo lint      # Check timeline registration and timing
npx framevideo validate  # Check for runtime errors
npx framevideo preview   # Scrub timeline to verify seekability

手動での確認：

1. タイムラインの登録 — window.__timelines["main"] が data-composition-id と一致することを確認します。
2. 一時停止状態 — タイムラインが paused: true で作成されていることを確認します。
3. 有限の再生時間 — 無限ループや -1 のリピート値がないことを確認します。
4. シーク可能性 — プレビュータイムラインをスクラブし、アニメーションがどのフレームでも保持されることを確認します。
5. 非同期登録なし — FrameVideo の初期化前に、タイムラインが同期的に作成されていることを確認します。

クレジットと参考資料

• FrameVideo アダプターのソース：packages/core/src/runtime/adapters/gsap.ts。
• GSAP ドキュメント：https://gsap.com/docs/v3/
• GSAP タイムラインの一時停止とシークの動作：https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/