注意点・既知問題

ハマりやすいポイントをまとめた「困ったらここ」ページ。
書き出し時の不具合は大半が headless Chromium の合成パスとの相性問題。

レンダラ周りの既知問題

1. backdrop-filter でちらつく・欠ける

ガラス表現（背面ぼかし）でフレームの一部が抜けたり、特定フレームでチラついたりする。

原因（推定）

• backdrop-filter は背面サンプリングが必要で合成パスが複雑。
• headless Chromium では backdrop-filter + transform の同時使用で合成が不安定になる。
• 結果、中間状態が写ってしまうフレームが出る。

回避策

• レンダー時だけ backdrop-filter を none にするのが最も確実。
• サンプル付属の GlassPanel はレンダー時に自動で backdrop-filter: none にしている。同じパターンで自作する。
• filter: blur(...) や drop-shadow(...) の多用も避ける。
• 大きな要素への transform + フィルタの同時使用も避ける。

const isRenderMode = import.meta.env.MODE === "render" // 例
// 実際の判定方法はプロジェクトの GlassPanel 実装を参照

アニメーション設計の落とし穴

useAnimation は1回しか走らない

async コールバックは マウント時に1回だけ。深い deps を使って 毎フレーム再実行するつもりで書くと事前計算が壊れる。

変数の値はあくまで「マウント時に決めたセグメント」を補間したもの。 実行時に値で分岐させたい場合は、その分岐ぶんだけ別シーン（別 Clip）を用意する。

変数の共有はできない

1 つの useVariable に対して ctx.move できるのは1 つの useAnimation だけ。 共有しようとすると
useAnimation: a variable cannot be shared across multiple animations で例外。

同じ動きを複数箇所で見せたいなら、変数のほうを別々に作るか、結果を計算済みの値として variable.use() で読むだけのコンポーネントに分ける。

"0%" は変数を初期化しない

プロジェクト同梱の keyframes ヘルパーで "0%" を書いても、 変数の現在値が変わるわけではない（補間の起点として使われるだけ）。

呼び出し時点で変数が "0%" の値になっていないと、 1フレーム目で大ジャンプが起きる。useVariable(initial) を合わせるか、 直前に ctx.move(...).to(value, 1) で揃える。

Clip 範囲外で状態は失われる

Clip がアクティブでなくなった瞬間、子コンポーネントは DOM ごと消える。 次にアクティブになると useState・useRef は初期化される。
Clip を跨いで何かを保持したいなら、より上位のコンテキストか useVariable を使う。

メディア周りの落とし穴

Studio とレンダラで挙動が違う

<Video> は Studio では <video> 要素、レンダー時は WebSocket + Canvas で 再生される。合成系の CSS（mix-blend-mode や filter）は Studio で意図通りでも書き出しでズレる場合がある。早めに書き出して確認する。

パスはプロジェクト内の assets/ に置く

絶対パスや ~/... も動くが、Studio とレンダラと配布バイナリの3者が 同じファイルにアクセスできる必要がある。プロジェクト外を参照すると後で必ず困る。

波形表示は60秒未満が自動、それ以上は明示

長尺の BGM やナレーションを波形ありで見たい時は showWaveform を付ける。 付けないとタイムラインに波形が出ず、ハマる。

PSD まわりの落とし穴

レイヤー名のスペルミスで死ぬ

kind: "bool" | "enum" どちらでも、PSD のレイヤー名・オプション名と コードの文字列が完全一致している必要がある。スペース混入や全角半角の混在に注意。

<PsdCharacter> 配下ではフックが使えない

motion コールバック内で useCurrentFrame() や useVariable は呼べない。 値は引数の frames[0] を variable.get(frames[0]) に渡して取得する。

編集ルール

• src/ はいじらない。コントリビュート目的でない限り、自分の作品コードは project/ に集める。
• サンプルの sample/ は動くお手本として残しつつ、必要に応じて project/scenes/ 等に移植する。
• AGENTS.md に編集ルールが書いてある。AI エージェントに作業させる前に最初に読ませる。

パフォーマンス

• 非アクティブな Clip は描画されない。シーンを細かく Clip に分けるのは無料の最適化。
• 巨大な静的レイアウトは WithFrameUpdates enabled={false} で囲うとフレーム更新通知が止まる。
• Three.js は dispose を必ず書く。リークするとレンダー後半でカクつく。