scenario-unity-animation

Unity アニメーション（アニメーターとテクニカルアニメーター）

Unity での高度なアニメーション作業では、順序と計測が重要です。どのレイヤー、制約、トランジション、カメラが優先されるかはリストの順序で決まり、足、エイム、ブレンドが適切かどうかはクリップから取得した数値で判断します。Animator、Timeline、Scene の各ウィンドウを使わないエージェントは、すべてをデータ（AnimatorController、TimelineAsset、Cinemachine、Rigging コンポーネント）から構築し、決定論的にステップ実行して計測し、コンタクトシートを確認します。対象バージョン：Unity 6000.3.21f1、Cinemachine 3.1.7、Animation Rigging 1.4.1、Timeline 1.8.12。ここに記載されている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールのスキーマを参考に進め、不足しているスキルを明記してください。

必須の背景知識： scenario-unity-expert（チャンネル、レビューループ、6.3 の落とし穴）。ツールキット： scripts/ut_animation.py と C# ジョブ scripts/AgentKit/Animation/（名前空間 AgentKit.Animation）、 ランタイムコード scripts/Runtime/。ut_animation.install(P) でインストールします。

姿勢（エキスパートならではの視点）

1. 順序はどこでも挙動を左右します。 Animator のレイヤーは下のレイヤーが優先されます（iHeartGameDev、W0eRZGS6dhQ [00:05:04]）。加算は最初の Override で止まります [00:09:46]。遷移はデフォルトで割り込み不可で、Ordered Interruption を有効にすると、実行中の遷移より上にある遷移だけが割り込み、同順位の場合はリスト順に従います（Catherine Proulx、Unity ブログ。実測：None、ordered、unordered、同一フレームの各ケースで再現）。割り込み時のブレンドは、固定されたスナップショットのポーズから始まります（実測：割り込みフレームでボーンの動きは 0 deg/s）。割り込み遷移は短くしてください［推論を追加］。リグの制約は深度優先で解決され、手や頭より先に背骨が処理されます（Code Monkey、luBBz5oeR4Q [00:06:20]。実測：頭部誤差は 0.0 度対 17.9 度）。
2. ブレンドツリーの座標にはゲームプレイの単位を使います。 子の位置には 0 / 0.5 / 1 ではなく、実測した averageSpeed / averageAngularSpeed を使います（_J8RPIaO2Lc [00:16:30]）。実行時パラメーターを子の範囲内にクランプしないと、速度が上がり続けても端のポーズが維持されます［フレーム 00:13:38］。スクリプト上の速度とクリップの速度が一致しないと、足が滑ります（Ketra Games、mNxEetKzc04 [00:00:32]。実測：スライドの p50 は 0.19 対 1.14 m/s）。
3. 歩行とポーズが異なる場合、Idle は独立したステートにします（IsMoving に Exit Time を設定しない）。ツリーを遅い歩行から始める方法もあります（mNxEetKzc04 [00:08:54]）。ツリーの原点を Idle にするのは、スクリプトの速度で制御するインプレースクリップの場合に限り問題ありません（_J8RPIaO2Lc [00:04:24]）。
4. ルートモーションはクリップごと、軸ごとに決めます（6.3 Manual）。アイドルでは回転、Y、XZ をベイクします。直進移動では回転と Y をベイクします。旋回では回転を維持します。高さが変化するクリップでは、Y を Based Upon Feet でベイクせずに残します。これによりブレンドで浮かず、スクリプトによるジャンプでクリップの腰の上昇が二重に加算されることもありません。Based Upon がドリフトを引き起こすことはありません。 ベイクした軸のデルタは、設定内容にかかわらずゼロであり、ポーズの位置を決めるだけです。Original はファイルの向きと位置を維持します（Ketra は Mixamo のアイドルをこの方法でベイクしており、ドリフトしません）。Body Orientation はモーションキャプチャのセグメントを再センタリングします（30 秒間の実測：どちらもドリフトは 0 m。Original は 88 度ずれた方向を向き、2.43 m 外れた位置に立ちました。XZ をベイクしない場合のドリフトは 0.246 m）。OnAnimatorMove で CharacterController.Move(deltaPosition + y) を 1 回呼び出し、deltaPosition * Time.deltaTime は使いません［00:07:21］。Animator.gravityWeight は、Y をベイクしたクリップでは 1、ベイクしていないクリップでは 0 であり、遷移中にブレンドされます（Manual。実測済み。ルートモーションがオフの場合はどこでも 0）。
5. 1 つの参照元を基準に、フォルダーの範囲内でインポートを自動化します（git-amend、V9_Z6hUOG_8）。リグは OnPreprocessModel で、クリップは OnPreprocessAnimation で処理し、ルールを変更したら GetVersion() を更新します。コールバック内で再インポートしてはいけません。役割はファイル名またはルールから判断し、テイク名を使ってはいけません。Mixamo のテイク名はすべて「mixamo.com」です。参照元には FBX のサブアセットクリップを使います。Humanoid に切り替える前に複製したクリップでは、ボーンパスが保持されます（BEZHVYk6Fa4 [00:12:03]。実測：Humanoid の移動は 0.0 度、切り替え後に作成したコピーでは 40.1 度）。異なる階層にある場合、Copy From Other ではクリップが一切インポートされず、インポートログにのみ記録されます（確認済み）。Translation DoF はデフォルトでオフです［00:02:21］。
6. マスクでレイヤーを作り、参照ポーズで加算レイヤーを作ります。 マスクのない Override レイヤーは全身を置き換えます。加算クリップが機能するのは、作成時のベースポーズの上だけです（W0eRZGS6dhQ [00:05:33]、[00:09:57]）。インポート時のマスクで、クリップに不要な指と IK ゴールを除外します（Manual、コスト）。
7. カメラ：Brain は 1 つにし、ターゲットを動かし、ゲームの種類に応じてリグを選びます（Unity CM3.1 シリーズ）。Smart Update と Late Update を使うと、ジッター発生時にブレンドが先に処理されます（Brain のドキュメント）。肩越し視点には Third Person Follow を使います。FreeLook と Camera Offset と Deoccluder の併用は競合します（u0a1F6BlczE [00:02:41]）。プロシージャルな Position Control はアニメーションより優先されます。移動オブジェクトの子にしてはいけません（XTVzs4B1d7I [00:03:10]）。反対側にあるカメラ同士はターゲットを通ってブレンドします。CylindricalPosition のヒントを使います（実測：設定なしでは 0.5 m、上方向のドット積は 0.0。Cylindrical では 5.02 m、0.995。IgnoreTarget のみでは依然として 0.5 m）［00:13:32］。Deoccluder ではプレイヤーに Ignore Tag を設定し、ガラスは Transparent Layers に追加します。トリガーはカウントされません（実測）。Timeline は Brain より優先され、停止するまで優先度は無視されます（Play モードで実測）。
8. Timeline：継続するアクションにはトラック、一瞬のイベントにはマーカー、ペイロードがない場合は Signals を使います（Ciro Continisio、gsEe0_o_934 [00:18:53]）。受信先には、そこに送られるすべての通知が届きます。型を確認してください［フレーム 00:22:57］。スクラブ中もミキサーは実行されます。OnGraphStart で生成し、その後破棄してください［00:45:30］。

まず決めること

プラットフォームとフレーム予算（パフォーマンスの引き継ぎ数値）；3D スケルトンか 2D スプライトか（スプライトは scenario-unity-2d へ）；リグタイプ（リターゲットと Mixamo には Humanoid、スケルトンが 1 つで コストが重要な場合は Generic。Generic のルートモーションは Root Node を通じて動作します）；ルートモーション（プレイヤーの足の品質）か インプレース（NavMesh AI、速度を厳密に制御）か；コンテンツのソース：Mixamo（Unity 用 FBX、30 fps、キーフレーム削減なし、同じ Mixamo キャラクター、クリップには Without Skin；ルートモーション：In Place をオフ、Character Arm Space を上げる；mNxEetKzc04 [00:03:04]、_J8RPIaO2Lc [00:01:24]）、分割するモーションキャプチャのテイク、DCC；カメラスタイル；CM2 はすでにプロジェクトにあるか；カットシーンの長さと分岐。デフォルト：Humanoid、プレイヤーにはルートモーション、CM 3.1.7、Timeline は 30 fps、Input System。

ワークフロー

1. パッケージ。 AnimPackages.Add に ["[email protected]", "[email protected]"] を指定（非同期、quit=False）し、 続いて ua.install(P) を実行します。GATE：ua.pinned_packages(P) がすべて ok。
2. インポート。 ua.default_rules("Hero.fbx", files) -> AnimImport.ImportDrop（ルール JSON、 キャラクターを先頭に、マスク、階層の不一致を修復）。AnimSampler.ClipProfile でテイクを分割します。 GATE：counts.error == 0 を監査し、アバターが有効かつヒューマンであること、すべてのクリップが human_motion であること、 anim.role_fallback がないこと、フォルダー外の FBX は引き続き Generic であること；AnimImport.AuditClips に anim.generic_duplicate がないこと。
3. コントローラー。 Spec -> AnimControllerBuilder.Build（マスク、レイヤー、auto ツリー位置、 割り込み設定付き遷移、ハッシュクラス）。GATE：counts.error == 0；位置が計測した速度と一致すること； ua.blend_tree_checks(tree, param_ranges) に問題がないこと；SampleStates 内の ua.interruption_probe_spec 形式のイベントで緊急退出が検証されていること。
4. サンプルと見た目。 AnimSampler.SampleStates（Rebind、固定の Animator.Update；events、 trace、サンプルごとの clip／controller）、LocomotionMetrics（単独のクリップには clip）。GATE： 期待する状態；マスクされたボーンが 0.000 deg；地上速度が 5 % 以内；スライド p50 < 0.25 m/s；アイドル状態で 30 s 経過後のドリフトが < 1 cm；Y がベイクされていないクリップでは gravityWeight が 0（ルートモーションが有効）；シートを開いていること。
5. リギング。 AnimRigging.BuildAimRig の後に AuditRigs を実行します。GATE：頭部 < 1 deg、手 < 1 cm、 rig.solve_order がないこと；フレームを確認済みであること；ターゲットを 1 つ動かし、再バインドしないこと （rig.runtime_rebind）；ターゲットが背後に移動するとリグのウェイトがフェードすること（Htl7ysv10Qs [00:07:54]、Play モードでの Rig.weight サンプル）。
6. カメラ。 AnimCinemachine.SetupCameras（リグ、blend_hint、deoccluder）、AuditCameras、 CameraProbe（Manual Update；obstacles、オクルージョンのラインキャスト、series）。GATE：各イベントにライブカメラがあること； ua.camera_probe_checks が空（反転、すり抜け、オクルージョン、ジオメトリ内のフレームがないこと）；ua.jitter_metrics の 反転が < 5 %［追加］；監査の warn が 0。
7. Timeline。 AnimTimeline.BuildCutscene、SampleCutscene（スクラブ、フレーム）、 PlayCutscene（Play モード：マーカー、シグナル、ライブカメラ、引き継ぎ）、AuditTimeline。GATE：バインディング； 数値ブレンド；ルートのスナップがないこと；マーカーとシグナルがそれぞれ 1 回だけ発生すること；監査の warn が 0； 終了後に Brain の優先カメラがライブであること。
8. 検証とコード。 AnimProcedural.RootMotionPlay（フレームごとに Move を 1 回）、 ua.scan_csharp(Assets) に問題がないこと、数値を scenario-unity-performance へ。

コード全文と記録済み結果を含む手順： references/procedures.md。

数値

値	対象	出典
Clamp(0.1 x length, 0.1 s, 0.5 x length)	ワンショットブレンド。length から blend を引いた位置でブレンドアウト	fQzKJO-0dS8 [00:07:58]
0.7 aim / 0.3 look	手でエイム／頭で視線を向ける場合の胸部の重み	luBBz5oeR4Q [00:06:53]; Htl7ysv10Qs [00:08:59]
-100..100 deg	頭部エイムの制限、後方のフェード重み	Htl7ysv10Qs [00:06:58]
Min 1 s, Wait 0	状態がちらつく場合のState-Drivenカメラ	u0a1F6BlczE [00:09:32]
primary 2, fallback 1	ClearShotの優先度	u0a1F6BlczE [00:14:53]
30 fps, keyframe reduction none	Mixamoのダウンロード	_J8RPIaO2Lc [00:01:24]
T < sqrt(4 k2 + k1^2) - k1	2次系の安定性	KPoeNZZ6H4s [00:12:29]
1.08 / 3.51 m/s, -98 / +77 deg/s	Unityのサンプルモーションキャプチャの歩行、ジョグ、ターン	観測値
0 m vs 0.246 m	30秒のアイドル時のドリフト、XZをベイクした場合としない場合	観測値
0.5 m vs 5.02 m	カメラの最接近距離、ヒントなしと円筒形の場合	観測値

品質ゲート

• 測定可能な項目： インポート監査とAuditClipsのクリーン状態、コントローラー監査、マスクチェック、速度が5％以内、 スライドのp50、アイドル時のドリフト、リグエラー、カメラプローブのチェックとジッター、Timelineのバインディング、イベント、 監査、1フレームあたり1回のMove、C#スキャン。
• 視覚的な項目： 各ステージのコンタクトシートを references/critique.md に基づいて評価します（Tポーズ、床への足のめり込み、腕が 身体を貫通する状態、急な動き、カメラの反転、フレーミング）。ut_review でフラグが立たないこと。

よくある間違い

間違い	状況	修正
Culling Mode が Always Animate 以外の状態でサンプリングする	バッチキャプチャでバインドポーズが表示される	サンプラーが Always Animate を強制します（確認済み）
テイク名からフラグを選ぶ	すべての Mixamo クリップに同じループフラグとベイクフラグが設定される	ファイル名またはルールからロールを指定し、クリップ名を変更します
対象範囲を限定していないインポートプロセッサ	プロジェクト内のすべての FBX が Humanoid に変換される	ルールファイルまたは assetPath ガードを使用します。ua.scan_csharp
ルート Y をベイクしたジャンプクリップ	ブレンドで浮き上がる。スクリプトによるジャンプに腰の上昇が加わる	Y はベイクせず、Based Upon は Feet に設定します
Humanoid への切り替え前に .anim を複製する	Humanoid ではクリップが再生されない	切り替え後に再度複製するか、FBX のクリップを参照します
階層が異なるオブジェクトで Copy From Other を使う	FBX がクリップなしでインポートされ、コンソールにも何も表示されない	インポートログを確認し、ファイルごとに独自のアバターを用意します（確認済み）
ドリフトの原因を Based Upon だと決めつける	アイドルアニメーションがループのたびにずれていく	XZ をベイクします。Based Upon はポーズの配置のみを行います
パラメーターがツリーの範囲外になる	速度は上がるが、アニメーションは変化しない	子の範囲内に制限します
頭部の制約を胸部より上に配置する	頭部がターゲットを外す	同じ階層の兄弟順で体を先に配置します
ヒントなしでカメラを反対側に配置する	ブレンドが頭部を通り抜けるように動き、反転する	両方に CylindricalPosition を設定します
ガラスやトリガーを壁として扱う	カメラが窓の前に飛び出す	Transparent Layers を設定します。トリガーは無視されます
カットシーン中に優先度を上げる	カットシーンが終わるまで何も変わらない	Brain は Timeline が管理します
エディタースクリプトで Priority を設定する	Brain が古いカメラを使い続ける	cam.Prioritize() を使います（確認済み）
マーカーや制御の引き渡しをテストするためにスクラブする	マーカーが発火せず、最後のショットが有効なままになる	PlayCutscene を使います（確認済み）
型チェックなしで OnNotify を使う	すべてのマーカーに反応する	if (n is MyMarker m) を使います
Optimize Game Objects を早い段階で適用する	シーンインスタンスが消える	出荷前の遅い段階で適用します（BEZHVYk6Fa4 [00:07:22]）

その他のエージェント向けの落とし穴（アーカイブ時の GUID 移動、ファイルごとに 1 クラス、Unity オブジェクトでの ??、Play モード中の読み取り）については、references/procedures.md を参照してください。

引き継ぎ

• 受け取るもの： scenario-blender-export、scenario-maya-expert、または scenario-3d からのキャラクター FBX とクリップ、scenario-unity-architecture からの入力アクション、scenario-unity-gameplay からの移動速度、NavMesh エージェント、ゲームプレイイベント、scenario-unity-pipeline-automation からのインポートパイプラインの規約。
• 引き渡すもの： scenario-unity-gameplay には、コントローラー、パラメーターの仕様（Speed m/s、TurnRate deg/s、IsMoving、Jump）、ハッシュクラス、ルートモーションムーバー（垂直方向のソース）を渡します。scenario-unity-rendering-lighting には、カメラカット（Camera Cut 時に時間依存エフェクトをリセット）と Timeline のライトトラックを渡します。scenario-unity-performance には、Animator の数、カリングモード、インポートマスク、遅い段階で適用する Optimize Game Objects を渡します。scenario-unity-vfx には、Signals と Activation トラックを渡します。パケット：プロジェクト、ジョブ、監査 JSON、シート、メトリクス、Verified と Assumed の一覧。

Unity 6.3 に関する注意点

• 6000.3.21f1 のマニフェストには Cinemachine 2.10.7 が記載されていますが、引数なしの Client.Add では 3.1.7 が解決されました（確認済み）： いずれにしてもバージョンを固定してください。CM3 は Unity.Cinemachine と CinemachineCamera および各コンポーネントを使用します。CM2 のアップグレードでは、型を CinemachineVirtualCameraBase に変更してから「Upgrade Entire Project」を実行します（取り消し不可）。6.6 では、CM3、Timeline、Animation Rigging がコア機能になります。
• Timeline 1.8：editorSettings.frameRate。6.3 では Animator.ResetControllerState が追加されます。非推奨の ModelImporter メンバーは 6.5 でエラーになります。
• テンプレートでは Input System のみが実行されます。Play モードに入るとドメインが再読み込みされます（Play モードのジョブでは、実行中はこれをオフにします）。

参考資料

• references/expert-notes.md：専門家による原則と判断、情報源、タイムスタンプ。
• references/procedures.md：各ジョブの引数、そのジョブで使用する Unity 呼び出し、実機テスト、結果。
• references/critique.md：リグ、ブレンド、足、カメラ、カットシーンを評価するための基準。
• references/gui-paths.md：同じ作業に使用するウィンドウとメニュー。
• references/sources.md：すべての情報源、認証情報、URL、最適なタイムスタンプ、改訂履歴。