scenario-unreal-animation

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

エキスパートレベルとは、ゲームで再生されるすべてのクリップで接触状態を維持し、入力フレームでカテゴリが変化する移動モデルに基づいてロコモーションを作成し、ターゲット上で実測したミリ秒単位の処理コストを把握し、ソースのデータをクリーンに保つことです。エージェントはデータとテンプレートを使って作業します。アセット、IK Rig、リターゲッター、データベース、設定をスクリプトで作成し、グラフを描く代わりにEpicのAnimBPを複製し、接触状態を数値で測定してからフレームを確認します。ここに記載された関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業する場合は、ツールスキーマに基づいて進め、不足している点を明示してください。

必須の背景知識： scenario-unreal-expert（チャンネル、レビューループ、5.8の注意点）。

ステータス（2026-09-24）： Unrealはインストールされていません。scripts/ue_anim.pyのオフライン層は30件のテストに合格しました （python3 tests/code/unreal-animation/run_all.py --offline）。エディター内で実行するすべてのスニペットはまだUnrealで実行されていません。[verify]の対象はjob_00_anim_probe.pyで回答します。インポート： sys.path[:0] = ["<skills>/scenario-unreal-animation/scripts", "<skills>/scenario-unreal-expert/scripts"]; import ue_anim as A

スタンス（専門家ならではの知見）

• 最も転送コストの低い方法を優先し、その後はリターゲット順で接触が決まります。 同じスケルトン、互換性のあるスケルトン、Copy Pose From Mesh、Leader Pose は、IK Retargeter より優先されます（Greg Richardson、-8CQNaODNNA [00:02:40]-[00:06:04]）。リターゲット時は、auto align と snap to ground を使い、膝と肘を少し曲げた、新しい名前付きのリターゲットポーズ（Default は使わない）を作成します。IK ゴールを基準に Scale Source を最初に一度だけ調整します。脚の IK でブレンドする場合や足が沈み込む場合は、Blend to Source を使います。自動エクスポートされたリターゲッターでは IK がオフになっています（Richardson [00:08:13]、[00:16:29]、[00:21:26]、[00:29:14]）。ゲームプレイ側が読み取る IK ヘルパーボーン （ik_foot_l/r、ik_hand_gun）を固定します。一度きりの調整はベースポーズではなく、Additive Pose オペレーションに設定します （Richardson [00:33:16]、5.8 retargeting doc）。
• まず移動モデルを決め、それに合わせてアニメーションを作成します。 ラフなアニメーションを使い、カプセルの速度、加速、ブレーキを調整して、動きがよく見えるようにします。カプセルの軌道をエクスポートし、許容範囲内で胸部（腰部ではなく）に合わせてルートをフレーム単位で正確にアニメーションさせます。胴体が行き過ぎる箇所では、5 フレーム停止させます。これにより、アニメーションの不具合とシステムの不具合を切り分けられます（GASP team、Tony、mhVp_cC9MLc [00:24:25]-[00:28:43]、Dustin DeVoe、FLDXtAV7qsw [00:06:27]-[00:08:40]）。
• モーションマッチングのデータは、デザイナーが管理します。 移動状態ごとにデータベースを分割し、キャッシュ済みの列挙型に対する Chooser で選択します。現在のフレームでコア状態が変化した場合に限って割り込み、カプセル駆動の場合でも、すべてのロコモーションクリップでルートモーションを有効にします（GASP team [00:29:43]-[00:40:54]、[01:30:00]）。ウェイトは、カバー範囲が少なく、どれも完璧ではない候補の間で優先度を表します（Sam [00:49:01]）。速度やカバー範囲の不一致はウェイトで修正できません。後半の調整ではスキーマのウェイトではなく、notify-state タグを使います（Jose、tNw9lD2PW3U [00:18:28]、motion matching doc）。
• 少数のアニメーションセットなら、プロシージャルノードを使ってリリースできます。 非ストレイフのベースには 13 クリップ、ストレイフありなら 26 クリップ、状態を含めるなら 60～80 クリップが目安です。すべての開始、停止、向き直り開始について、左右両方の足のクリップを用意します（DeVoe [00:11:14]-[00:14:44]）。「すべての動きを網羅する必要があるというのは誤解です」（GASP [01:21:06]）。データが疎な場合は、ステートマシンではなく、Offset Root Bone の前に Steering を置き、足の位置調整とメッシュ空間の加算を使います（DeVoe [00:28:19]-[00:31:40]）。
• AnimBP をゲームスレッド上で実行しないようにし、ルートモーションのコストを予算化します。 スレッドセーフな更新、Property Access、すべてのノードでの fast path を使います（Matthew Lake、N_suMyUuork [00:12:44]-[00:16:53]）。Root Motion from Everything と Montages Only は、どちらも AnimGraph をゲームスレッド上で更新します（root motion doc、Lake [00:13:18]）。Montages Only が選ばれるのは、カプセル駆動のロコモーションがネットワークに適しているためであり、スレッドを節約するためではありません。そのコストを予算化してください。ルートモーションモンタージュを使わないキャラクターでは、No Root Motion Extraction を使用できます［ドキュメントの文言からの推論。Insights で確認してください］。
• 元データをクリーンアップし、見えないものの更新頻度を下げます。 ツイスト、顔、変形のトラックと Maya ヘルパーカーブを削除すると、あるクリップではストレージを 71％、メモリを 90％削減できました。インポートのデフォルト設定はアセットごとではなく、プロジェクト全体に適用します（Lake [00:05:15]-[00:07:21]）。プロジェクトのデフォルトには Tick Pose When Rendered だけを使い、budget allocator または URO のどちらかを選択します（両方は使いません）。ヒステリシスを設定した LOD Settings アセットを 1 つ使います（Lake [00:21:13]、AnimBP doc）。
• Control Rig：Construction でキャッシュし、Forwards Solve は毎フレーム実行します。 C++ に変換する前にプロファイリングします（グラフは 60 µs、リグユニットは 10～16 µs）。FBIK はポーズを調整するものであり、ポーズを作成するものではありません。ボーンをロックするのではなく、除外します。Backwards Solve があれば、リグをベイクできます（Stéphane Biava、XYMad1EutcA [00:10:08]、LEGO Fortnite tech animator、kO6pz8ADgcU [00:12:04]）。
• シネマティック用 MetaHuman を製品に含めないでください。 クック後のサイズは約 800 MB、Optimized High は約 60 MB です。PS5 クラスの環境では LOD 2 以降をゲームカメラで確認してください。Mac ではカードのみをレンダリングします（DeVoe、 tTgMafRAM7A [00:15:16]、[00:23:34]）。

まず決めること

入力	変更内容	指定がない場合のデフォルト
プラットフォーム、フレーム予算、画面上のキャラクター数	予算、LOD、アロケーター、ランタイムとオフラインのリターゲット	コンソールクラスで60 fps。アニメーションの配分は scenario-unreal-performance を参照
マルチプレイヤー、ヒーローの忠実度	カプセル駆動かルートモーション駆動か	マルチプレイヤー：カプセル駆動、モンタージュ内ではルートモーションを使用。シングルプレイヤーで、足を接地したまま向きを変える必要があるヒーロー：ルートモーション属性を介したルートモーション駆動を評価します（Jose [00:33:25]-[00:34:29]）。Mover 5.8ではChaosMoverの軌道予測が追加されていますが、引き続きExperimentalです
移動モデル：方向ごとの速度、加速、制動	すべてのクリップのタイミング	GASPのデータを再利用する場合はGASPの速度を使用します。作成前に調整してください
クリップセット：GASP、モーションキャプチャ、手付け、数	モーションマッチングかステートマシンか	プロシージャルノードを使ったモーションマッチング。明示的なステートごとの制御が必要な場合のみ、ワーピングを使ったステートマシン（Lyra）を使用します
ゲームプレイ上の要件	ストレイフとステートによってコンテンツが増加します（各ステートでほぼ倍増します。DeVoe）	移動方向に向く、歩く、走る、ジャンプする
DCCからのスケルトン仕様	チェーン、IKボーン、ルート	scenario-maya-rigging の game_skeleton_check がクリーンであること

ワークフロー

1. エンジンごとに1回、プローブを実行します。 job_00_anim_probe.py をヘッドレスで実行します。GATE：probe.json に IK Rig、リターゲッター、Pose Search、AnimPose、Interchange、MetaHuman の名前と、5.8 に BlueprintGraphEditor が存在するかどうかが記載されていること。
2. キャラクターを受け取り、監査します。 A.import_character / A.import_animations（どちらのインポーターでもオプションを明示）を実行し、その後 A.import_audit(A.skeletal_mesh_facts(mesh)) を実行します。ルートが1つであること、未使用ボーン（5.8 の Bone Count Reduction）、8を超えるインフルエンス、単位を確認します。プロジェクト全体のインポート既定値を一度設定します。レガシーインポーターには A.apply_ini_plan(cfg, A.import_defaults_plan()) を使用し、Interchange Import Content スタックにはプロジェクトパイプラインを設定します。GATE：エラーがなく、メッシュを中立的なライティングのプレビューで確認していること。
3. 転送方法を選びます。 A.transfer_method(source, target) を実行します。GATE：方法と理由を記録していること。
4. IK Rig。 A.create_ik_rig を実行します（5.8 テンプレートでは、Leg が足首で分割され、Foot チェーンが追加されます）。カスタム名には A.biped_chain_plan を使用します。GATE：A.chain_map_check に問題がないこと。
5. リターゲッターを一度構築し、テンプレート化します。 A.create_retargeter を実行します。GUI でオペレーション設定を一度行い、RTG_Template として保存します。A.ik_bone_pin_plan(bones, A.mannequin_bone_map(bones, parents)) からピン留めするボーンを設定します。GATE：A.op_stack_check(ops, proportions_differ=True, target_ik_bones=..., runtime=..., profile_ops_us=...) に問題がなく、Retarget Output Log に対する A.retarget_log_check にも問題がないこと。ランタイムリターゲッターでは、LOD しきい値と Profile Ops を確認します。
6. 一括でリターゲットし、クリーンアップします。 A.batch_retarget(..., retain_additive=True) を実行します。モーションキャプチャには専用のリターゲッターを使用します（Filter Bones、Generate From Target Pelvis）。続けて A.anim_content_audit、A.ensure_root_motion、A.strip_curves を実行します。GATE：歩行、走行、ターン、しゃがみ、ジャンプ、接地クリップ、モーションキャプチャクリップに対して A.compare_contact を実行し、A.root_motion_check を実行すること。接地フレームを側面と正面から確認していること。
7. 移動モデルと作成済みクリップ。 歩行パターンと方向ごとに移動コンポーネントを調整します。カプセルの軌道をエクスポートします（5.6 以降では Rewind Debugger > Trajectories export、それ以外では Take Recorder を使用）し、scenario-maya-animation または scenario-blender-animation に出力します。GATE：A.capsule_match（ルートが経路上にあり、胸部が許容範囲内にあり、ルートがカプセルと同時に停止すること）と、返却されたクリップに対する A.speed_parity を確認すること。
8. ロコモーションのアーキテクチャ。 A.decide_locomotion(...) を実行します。モーションマッチングの場合：GASP を移行し、A.motion_matching_coverage（足のペア、キャプチャ形状）、A.database_plan を実行し、スキーマとデータベースを複製してから、マネキンのボーン名をすべて再マッピングします。 A.schema_bone_check(A.schema_facts(s)["bones"], bones, bone_map) を実行し、GUI で Pose History のボーンを設定します。タグ、Notify のフィルタリング、繰り返し防止処理も設定します。プロシージャルノードの場合：A.procedural_order_check、A.offset_root_bone_modes を実行します。GATE：PIE で各状態を巡回した際に「no database」警告がゼロであること。Rewind Debugger で各遷移フレームを確認し、静止カメラからタイムスケール0.25で開始、停止、ピボットを確認すること。
9. ルートモーションとモンタージュ。 A.root_motion_mode_check(mode, multiplayer, montage_root_motion) と A.montage_blend_out_check を実行します。JustTraversed データベースを通じてトラバーサルの末尾を処理します。GATE：ブレンドアウト区間にルート速度がなく、show collision のカプセルがメッシュに追従し、ゲームスレッドを計測していること。
10. Foot IK。 GASP 5.4 のレッグ IK は足を IK foot bones にロックするだけで、地面への適応は行いません［現在の GASP を確認してください］。斜面や階段には Foot Placement、または FBIK を使用した Control Rig が必要です（A.fbik_foot_defaults(mannequin_like=False) で膝の軸を再導出します）。Sequencer のショットでは、マネキンに CR_GroundAlignment を適用してからリターゲットします。GATE：階段と30度の斜面をキャプチャし、フレームごとの足の隙間を確認すること。ポップやジッターがないこと。
11. パフォーマンス確認。 A.anim_ini_plan、A.animbp_settings、A.compile_and_scan、A.allocator_config_check、A.lod_settings_check を実行します。GATE：同じ経路で、前後の stat anim、stat unit、Insights を比較すること。
12. Handoffs に従って、未確認の項目を明記して引き渡します。

数値

値	対象	出典
GASP の速度：歩行は約 2、横移動は 3.5、走行は 5 m/s	移動モデルとクリップ	GASP team [01:27:17]
カプセルの停止は 5 フレーム、ルートのオフセット半径は約 30 cm	カプセル	GASP team [00:27:38], [01:52:15]
ステアリングで望ましい向きを 0.5 s 先に設定	軌道	Jose [00:29:50]
Notify Recency Time Out は 0.2 s、重みの例は Pose が 1、Trajectory が 3	Motion Matching ノード、スキーマ	motion matching doc
最小セットは 13、26、60～80 クリップ（GASP は 500 超）	ロコモーション	DeVoe
a.Budget.BudgetMs は 1.0（デフォルト）、1.5、2.0、2.5	ゲームスレッド、ViewDistanceQuality 0～3	AnimBP doc
最大ボーン影響数は 8（LOD0）、4、1（最後）	スケルタル LOD	Lake; Biava
FBIK：骨盤の剛性 0.8、膝の優先 Z は 45、足首は -70..70	マネキンの関節軸	Control Rig doc
Filter Bones：Responsiveness は 0.3～0.8、Velocity Cutoff は 15～30 Hz、フレームレートの 1/2 未満	モーションキャプチャ	retargeting doc
MetaHuman のポーズドライバーは、PS5 でキャラクターあたり 1.4 ms（5.6 ms から）、その後は約 0.4 ms	キャラクターあたり	DeVoe
接地許容誤差は 1～2 cm、カプセル上のルートは 2 cm、胸部は 30 cm	接地フレーム、作成済みクリップ	[追加] デフォルト

キャラクターあたりの ms 予算を示す出典はありません。シナリオ別の Unreal のパフォーマンスからアニメーションに割り当てられる割合を確認してください。

品質ゲート

• コード： 各 Workflow ゲートの A.* チェック。verdict(issues) で要約し、エラーがないこと。
• エンジンの数値： stat anim、stat unit、Insights（アニメーションチャネル、ゲームスレッドの AnimGraph 更新）、統計グループ PoseSearch（5.8 名）、a.Budget.Debug.Enabled 1、Retarget Profile Ops。
• ビジュアル（ue_review）： 接地フレームの側面と正面、中央のネイティブ表示、ロコモーションの 0.25 倍速、 階段と傾斜、距離に応じた LOD。スコアは references/critique.md を参照してください。

よくある間違い

間違い	症状	修正
対象のスケルトンを指定せずにアニメーションをインポートする	クリップが再生されない。<Mesh>_Skeleton が残る	必ずスケルトンを渡します
脚の IK で Blend to Source を設定しない	対象が短い場合に足が沈み込む	Blend to Source を設定します。手が届きすぎる場合は、上部で Scale Source を設定します
IK 補助ボーンをピン留めしない	脚または武器の IK が参照ポーズのボーンを読み取る	ik_bone_pin_plan に従ってボーンをピン留めします
自動生成されたリターゲッターを使ってバッチ処理する	IK が機能せず、オーバーライドセットが無視される	手動で作成したリターゲッターを使います
移動モデルの調整前にクリップを作成する	すべてのクリップの再調整が必要になり、アニメーションとシステムのバグが混在する	まずモデルを作成し、capsule_match を使います
カスタムスケルトンに GASP のスキーマを複製する	チャンネルが存在しないマネキンのボーンを読み取り、選択精度が低下する	schema_bone_check を実行し、スキーマスケルトンを使用してミラーテーブルを再構築します
ウェイトを調整しながらデータベースをひとつにまとめる	開始時の動きは改善するが、停止時の動きが崩れる	状態ごとに分割し、Chooser を使用し、コア状態の変更時に割り込みます
アニメーションセットが小さいという理由でステートマシンを選ぶ	遷移がぎこちなくなる	最小限のセットにプロシージャルノードを組み合わせます
キーボード入力で Offset Root Bone の後にステアリングを適用する、または適用しない	選択が頻繁に切り替わる	最初にステアリングを適用し、移動中または空中にいる間だけ使用します
「グラフをワーカー上で実行するため」に Montages Only を選ぶ	予算に計上されていないゲームスレッドのコストが発生する	どちらのモードもゲームスレッド上でグラフを実行します。予算を設定するか、No Root Motion Extraction を使います
ルートがまだ動いている状態で Blend Out Trigger Time を -1 にする	トラバーサル後に歩行ループのフレームが再生される	トリガーを 0 にするか、ルートモーションを早く終了させます
a.Budget.Enabled を設定せずにアロケーターノードを使う、またはアロケーターと URO を併用する	効果がなく、スロットリングの動作も分かりにくい	両方のスイッチを有効にします。2 つのシステムを併用しないでください
壁の近くでオフセットルートボーンを使う	メッシュが壁にめり込む	壁の近くでは半径を小さくするか、衝突を考慮した軌道を使います

引き継ぎ

• scenario-maya-rigging、scenario-maya-animation、scenario-blender-rigging、 scenario-blender-animation から scenario-unreal-pipeline-automation 経由で受け取ります： FBX 2020.2、cm、原点にルートが 1 つ、ジョイントのみ、ファイルごとにクリップ 1 つ、game_skeleton_check JSON。Blender ファイルは scenario-blender-export の unreal_skeletal プリセットから取得します。
• scenario-maya-animation または scenario-blender-animation に引き渡します： エクスポート済みのカプセル軌道、方向ごとの速度、加速度、制動、停止仕様、胸部の許容範囲、両足を含むクリップリスト。
• scenario-unreal-gameplay に引き渡します： キャラクターの Blueprint 子クラス（GASP または Lyra）、AnimBP の変数コントラクト（歩容、スタンス、移動モード、回転モード）、ワープターゲット付きモンタージュ、移動モデルの値、マルチプレイヤーの軌道では CMC の入力加速度に C++ のレプリケーションが必要である旨の注記。
• scenario-unreal-cinematics に引き渡します： リターゲット済みクリップ、ベイク可能な Control Rig、CR_GroundAlignment のガイダンス、プリレンダリングショット専用の MetaHuman Cine ティア。
• アニメーションの予算とターゲットキャプチャについて、scenario-unreal-performance に確認します。

UE 5.8 の注意事項

• リターゲッター：オペレーションスタック（5.6）、Override Sets が Retarget Profiles に置き換わり、足の定義と床の制約、Blend to Source、Scale Goals、Offset Goals は個別の Run IK Rig サブオペレーションになりました。5.8 より前のリターゲッターは再保存してください。
• Pose Search：DatabaseAnimationAssets（5.7）、Chooser の列データベースはデフォルトで Brute Force、...FromContext チャネルゲッター、統計情報の名称変更、「Block Transition In」。
• Blueprint グラフの編集には、5.8 では unreal.BlueprintGraphEditor を使用します。AnimGraph ノードまで編集できるかは [verify]：複製したものを試し、できなければテンプレートとコンピューター操作を使用してください。
• Interchange：アセットのインポートでは本番環境で使用可能（5.5）、FBX レベルインポートではデフォルト（5.6）、ダイアログを再設計（5.8）されました。FBX アセットインポートのデフォルト設定は [verify] のため、両方のインポーターにオプションを渡してください。
• Control Rig：Construction Event、Physics Beta、Dynamics Experimental。FSmartName と 5.0 から 5.6 までのアニメーション API は削除されました。
• MetaHuman：まず ConvertLegacyDNAAssets -DryRun を実行してください。顔の MetaHuman Animator は macOS、ボディは Windows のみです。
• 実験的な機能のため、フォールバックが必要です：Animation Mixer、Direct Mesh Controls、uFBX、MetaHuman Crowd、MotionMatchMulti。Mover は引き続き Experimental です。

参考資料

• references/procedures.md：各ステージの全コード、テストパス、ステータス。スクリプトによる手順を実行する前に確認してください。
• references/expert-notes.md：専門家による判断、意見の相違、判断条件。
• references/critique.md：セルフレビューの評価基準。各ゲートで確認してください。
• references/gui-paths.md：コンピューター操作エージェント向けのエディター、メニュー、設定。
• references/sources.md：すべての情報源、認証情報、URL、最適なタイムスタンプ、改訂履歴。