1仕組みと動作原理

実装原理は3つのAPI規約と1つのVRAM回収規約に基づきます：フレームレート非依存（dtを掛ける）、素のrAFではなくsetAnimationLoopを使用、そしてGPUリソースのライフサイクルを第一級市民として扱うことです。

skills/threejs-animation/SKILL.md

Use `clock.getDelta()` to make motion frame-rate independent (multiply rates by `dt`), and `setAnimationLoop` (works with WebXR and pauses on tab blur) instead of raw `requestAnimationFrame`.

ここでの目的：「なぜ素のrAFを使わないのか」「なぜdtを掛けるのか」を明示すること。この2点が以降のすべてのアニメーションコードの構成を決定づけます。

GLTFの再生はAnimationMixerを使用し、要点は「deltaでmixerを更新すること」です。クロスフェードにはcrossFadeTo（線形ウェイトの場合はwarping=false）を用い、単発アクションにはLoopOnce + clampWhenFinished + finishedイベントを使用します。

skills/threejs-animation/SKILL.md

Load a model, play clips through an `AnimationMixer`, and **update the mixer with delta time** every frame.

ここでの目的：clip再生の完全なライフサイクル（load → clipAction → crossFade / one-shot）を提供すること。Three.jsで最も誤りやすい部分です。

カメラの動きには固定係数ではなく指数減衰補間lerp(goal, 1 - exp(-lambda*dt))を使用することで、任意のフレームレートで均一な減衰感覚を保ちます。スクロールは目標位置の変更のみにとどめて減衰で平滑化し、曲線飛行はCatmullRomCurve3 + getPointAtで行います。

skills/threejs-animation/SKILL.md

Smooth camera follow uses exponential interpolation toward a target. Frame-rate-correct damping:

ここでの目的：「フレームレートの正確性」をスローガンから数式へと落とし込み、曲線パスの実装エントリを提示することです。

大量のオブジェクトはInstancedMeshを使って1回のdraw callにまとめ、インスタンスごとのマトリクスをsetMatrixAtで設定します。フレーム毎の更新にはDynamicDrawUsageへの切り替えが必要であり、カラー変更はsetColorAtとneedsUpdateの設定で行います。

skills/threejs-animation/SKILL.md

One draw call for thousands of identical meshes. Set per-instance matrices (and optional colors).

ここでの目的：「数千個のオブジェクト」に対するパフォーマンス経路をAPIの組み合わせとして確立し、フレーム毎更新に必要なフラグを明記することです。

R3FブランチはuseFrame(state, delta)で駆動し、DPRの上限を<Canvas dpr={[1, 2]}>に設定します。モデルやアニメーションはuseGLTF、useAnimationsに委ね、スプリングやスクロールは必要に応じて@react-spring/three、drei ScrollControlsを導入します。

skills/threejs-animation/SKILL.md

Drive animation with `useFrame`; it receives `state` and `delta`.

ここでの目的：同一の規約群を宣言的レンダラー内で対応する記法（useFrame + DPR上限）として提示することです。

VRAMの破棄は本ドキュメントの中核です。通常のGCではGPUのbuffer/textureを解放できない仕組みを解説し、「何をdisposeすべきか、何が不要か」の判断基準を与え、マテリアル配列やすべてのテクスチャスロットを含む完全な走査処理を提供します。

skills/threejs-animation/SKILL.md

GPU resources (geometries, materials, textures, render targets) live on the *GPU*, not the JS heap. The garbage collector frees the JS objects but **cannot free the WebGL buffers/textures they uploaded**.

ここでの目的：「なぜ画面が黒くなるのか / CONTEXT_LOST_WEBGL」に答え、scene.removeがGPUリソースを一切解放しないという一般的な誤解を解くことです。

R3Fにおけるリーク境界を明確に区別します。JSXで宣言的に作成されたリソースはアンマウント時に自動disposeされますが、命令型（useMemo/ref/loader内でnewされたもの）は自動解放されないためuseEffectのクリーンアップで手動disposeする必要があります。これをrenderer.info.memoryによる10回のマウント/アンマウントベースライン回帰で検証します。

skills/threejs-animation/SKILL.md

Verify with `renderer.info.memory` (R3F: `useThree().gl.info.memory`): mount/unmount 10x; if `geometries`/`textures` does not return to baseline, something leaked.

ここでの目的：「リークしているかどうか」を推測ではなく、実行可能な定量的検査にすることです。

2コア機能

01最小限のシーン + レンダーループのスケルトン（カメラパラメータ、DPR上限、リサイズ、setAnimationLoop、dt駆動の回転）

02GLTFアニメーション：AnimationMixer再生、crossFadeToクロスフェード、LoopOnce + finishedイベント

03カメラの減衰追従とスクロール駆動3D（CatmullRomCurve3による曲線飛行を含む）

04InstancedMeshバッチレンダリング（インスタンスごとのマトリクス + カラー + 毎フレームのneedsUpdateパフォーマンススイッチ）

05React Three Fiberモーション：useFrame、DPR上限、useGLTF/useAnimations、drei ScrollControlsおよびsprings

06パフォーマンスチェックリスト：DPR上限、ジオメトリ/マテリアルの再利用と静的ジオメトリ結合、リアルタイム照明/シャドウの抑制、ジオメトリ移動よりマテリアルアニメーションの優先

07GPU VRAM回収：disposeObject走査（マテリアル配列 + 全テクスチャスロット）、renderer.dispose + forceContextLoss、R3F useMemo+cleanup、共有リソースdispose={null}

08決定論的スクリーンショットハーネス（?t=Nで経過時間を固定、mixerは絶対時間setTimeを使用）と完了前チェックリスト

3外部依存関係

Kind	Dependency / Endpoint
cli	npx playwright screenshot（验证回路：截 file:// 页面冻结帧）
cli	仓库根共享脚本 scripts/seek-shot.sh、scripts/contact-sheet.sh（不在 skill 目录内）
cli	ffmpeg / ffprobe（contact-sheet.sh / probe-mp4.sh）
package	three + three/addons（GLTFLoader 等），产物期经 importmap 从 CDN 取
package	React Three Fiber 生态（@react-three/fiber、drei 的 useGLTF/ScrollControls、@react-spring/three，以及 postprocessing 的 UnrealBloom / DepthOfField）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: （SKILL.mdの指示）npx playwright screenshot --wait-for-timeout=600 "file://$PWD/
网络端点: 外部ネットワークアクセスの宣言: skillディレクトリ内にネットワーク呼び出しコードはなし。実行時のネットワーク面は `npx playwright` のツール取得（npmレジストリ + Chromiumバイナリのダウンロード）のみ
本地工作目录: ファイルの読み書きと成果物出力: 成果物本体：単一のscene.html（エージェントが出力規約に従って作成）

監査ノート： 評価対象＝skill自身のディレクトリ。SKILL.mdおよび2つのMarkdownリファレンス（他に0バイトのREADME.md）のみで構成：自前スクリプトなし、認証情報の読み取りなし、エンドポイント呼び出しなし、ユーザー素材の外部送信なし。成果物はローカルの単一ファイルHTML（またはユーザー自身のR3Fプロジェクト）。実行時はローカルツール（`npx playwright screenshot` によるfile://ローカルページのキャプチャ、ffmpegによる画像結合）のみが関与。成果物HTMLがimportmap経由でCDNからthree / three/addonsを取得するのはブラウザ側の取得に該当（「成果物による参照は評価対象外」とする原則に基づきreasonに記載）。注意点：① `npx playwright` はリモートパッケージを取得し初回実行時にChromiumをダウンロード（サプライチェーン接点、バージョン未固定）；② scripts/seek-shot.sh、scripts/contact-sheet.sh はリポジトリルートに存在するため、skillディレクトリ単体導入では参照が切れる；③ WebGL/GPU前提：ヘッドレスSwiftShaderのソフトウェアレンダリング下ではフレームタイムが実機と大幅に異なるため、リーク回帰はホストマシンのGPU上で再実行すべき；④ R3Fブランチは複数のサードパーティパッケージ（fiber/drei/react-spring/postprocessing）を宣言しており、ユーザープロジェクト側でインストールおよびバージョン固定を行う必要あり。いずれも黄色（通常の外部ネットワーク送信なし）および橙色の基準を満たさず、リポジトリ全体の走査によりサンドボックス解除/TLS無効化/自動検出回避などの赤色相当の行為がないことを確認済み。

5二重目の独立検証

[ok] 「skill 目录内无脚本、无 3D 资产」是否成立 — 文件清单实证：目录内只有 SKILL.md、README.md(0 B) 与两份 markdown reference；无 .glb/.gltf/.hdr/贴图，也无 package.json 或构建配置。引用到的 scripts/*.sh 属仓库根资产。
[ok] 凭证/环境变量读取是否存在 — 本仓全仓正则 `process.env|API_KEY|TOKEN|SECRET|Authorization` 零命中；credential_reads 为空成立。
[ok] 是否有更高的触发条件被漏掉（红档特征） — `sandbox|automationcontrolled|no-verify|stealth|bypass|ignoreHTTPSErrors|dangerously` 全仓零命中；无任意代码执行面（交付物在浏览器沙箱内运行用户自己的场景代码）。
[ok] 「显存 GC 释放不了」的解释与处置是否自洽 — 文档先讲机制（GC 释放 JS 对象但释放不了上传的 WebGL buffer/texture），再给「该 dispose / 不用 dispose」清单，再给 disposeObject 遍历（含材质数组与 for…in 贴图槽），三者互证；scene.remove 的误解也单独点破：'it frees **nothing** on the GPU'。
[ok] R3F 自动 dispose 的边界声明是否有可验证手段 — 声明式自动 dispose vs imperative 泄漏的分界写得很具体，并要求 renderer.info.memory 挂载/卸载 10 次回归；references/resource-disposal.md 另附完整泄漏案例与 <DisposeOnUnmount> 方案，属可执行而非口号。
[ok] 冻结 harness 与 mixer 的配合是否写对（易错点） — harness 段用 `mixer.setTime(elapsed)` 并注释 'setTime is absolute, not delta'，与循环里 `mixer.update(dt)` 的增量语义区分开，说明作者意识到差异，声明可信。

6結論

VRAM回収をメインテーマとして解説：メカニズム → 判定基準 → 走査コード → 定量的回帰を通じて、ブラックキャンバスやCONTEXT_LOSTなどの症状に正面から対処

重要APIにアンチパターンの注意喚起を併記（素のrAF、scene.remove、R3Fは宣言的リソースのみ自動disposeなど）

フレームレートの正確性を数式（指数減衰 1 - exp(-lambda*dt)）へと落とし込み、「dtを掛ける」という単なるスローガンを脱却

GLTFのライフサイクルをクロスフェードから単発アクションの終了イベントまで網羅し、そのままコピー＆ペースト可能

2つのリファレンスに分離し、破棄編ではテクスチャスロット、レンダーターゲット、HMR安全性まで詳細に記載

パフォーマンスの優先順位とトレードオフを提示（DPR上限が最大の費用対効果、マテリアルアニメーションはジオメトリ移動より低コスト）

最適な用途： 3Dヒーローセクション、WebGL背景、プロダクトビューワー、スクロール連動3D、GLTFキャラクター再生、数千個のオブジェクトのインスタンシング、およびR3Fプロジェクトのアニメーション・パフォーマンス改善に適しています。特に「アニメーションは動くがVRAM使用量が肥大化し続ける」「ルーティング切り替え後に画面が黒くなる」といったレガシー問題のトラブルシューティングに最適です（リーク回帰テストと破棄ツールを即座に利用可能）。出力は直接開ける単一ファイルHTMLであり、チーム内のThree.jsパフォーマンス/破棄規約ドキュメントとしても活用できます。

不向きな用途： 以下には適していません：① オフラインレンダリングや映画品質を必要とする動画制作（本スキルはリアルタイムWebGL向けです）；② GPUが一切なく実機並みのパフォーマンスが要求される検証環境（ソフトウェアレンダリングでは結果が歪みます）；③ 3Dアセットやモデルの同梱を期待するプロジェクト（本スキルはコード手法とリファレンスのみを提供し、モデル/テクスチャは含みません）；④ CDN版やサードパーティパッケージを許容できない厳格なサプライチェーン環境（セルフホストおよびバージョンの固定が必要です）；⑤ skillディレクトリ単体のみを導入し、リポジトリルートのscripts/が存在することを前提とする環境。

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload threejs-animation.tar.gz

sha256: de5e7ad51ab285c7…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 50697d659f.