blender-animation

アニメーション

実行モデルは blender-core にあります（references/bpy-patterns.md には、検証済みのキーフレームとドライバーのスニペットがあります）。リグについては blender-character-rigging を参照してください。

5.x のデータモデル（変更点）

• アクションには、スロット（アニメーション対象の ID ごとに 1 つ）と、レイヤー → ストリップ → チャンネルバッグ → F カーブが含まれます。1 つのアクションで、異なるスロットを通じて複数のオブジェクト（たとえばリグとそのカメラ）をアニメーション化できます。
• 割り当てるには、ob.animation_data.action = act を設定し、続いて ob.animation_data.action_slot が設定されていることを確認します（適切なスロットがあれば自動的に選択されます。ない場合は act.slots.new(id_type="OBJECT", name=ob.name) を使います）。
• F カーブ：cb = anim_utils.action_ensure_channelbag_for_slot(act, slot) を実行し、続いて cb.fcurves.ensure(path, index=i, group_name=...) を使います。action.fcurves は存在しなくなりました。
• 最も簡単な方法は、引き続き pb.keyframe_insert("rotation_quaternion", frame=f) を使うことです。これにより、アクション、スロット、チャンネルバッグが作成されます。

ワークフロー（キーフレームアニメーション、スタジオスタイル）

1. ブロッキング：重要なフレーム（歩行の場合は接地、下降、通過、上昇）で、すべてのチャンネルにキーとなるポーズを設定します（補間は CONSTANT、bpy.context.preferences.edit.keyframe_new_interpolation_type）。
2. ブレークダウン：弧と間隔を定義する中割りを追加します。
3. スプライン：BEZIER に切り替え、グラフエディターで間隔を調整し、オーバーシュートを修正します。自動クランプハンドルを使うとオーバーシュートを防げます。
4. 仕上げ：オフセット／オーバーラップ（髪、しっぽ、布のボーンのフォロースルー）、弧、動きのある静止（キャラクターを完全に停止させない）、接地の安定性（IK で足を固定）を調整します。
5. レビュー：MCP の look(mode="frames", frame_count=8) または Workbench のプレイブラスト（blender-rendering）を使います。

ゲームアニメーションのルール

• クリップごとに 1 つのアクションを作成し、名前は <Rig>_<Clip> または <Clip> にして、保存後も保持されるようフェイクユーザーを設定します。
• ループ：最初と最後のフレームを同一にします。フレーム 1..N をエクスポートしてエンジン側で重複フレームを削除するか、最後のフレームを除外します（UE/Unity の「ループポーズ」オプション）。F カーブの CYCLES モディファイアーはプレビューには便利ですが、エクスポートされないため、ベイクしてください。
• FPS：30（または 24）で作成し、エンジン側でリサンプリングします。モーションキャプチャをインポートする前に scene.render.fps を設定してください。
• ルートモーション：ルートボーンに移動（およびヨー）を持たせます。ヒップには上下動と揺れを残します。scripts/bake_action.py --root-motion xy は、ヒップの地面上の動きをルートに移します。その場でのクリップでは、ルートは原点に置いたままにします。
• 加算／オーバーレイクリップ（エイムオフセット、呼吸など）は通常のクリップとしてエクスポートし、エンジン側で加算としてマークします。
• エンジンが想定するボーンのトランスフォームチャンネルを維持します。エンジンが対応していない限り、ボーンのスケールはアニメーション化しないでください（Roblox や多くのモバイル向けパイプラインでは対応していません）。

コントロールリグをエクスポート用スケルトンにベイク

scripts/bake_action.py -- --list
scripts/bake_action.py -- --source RIG_Body --target GAME_RIG_Body [--actions Walk Run] [--root-motion xy --hips spine]

これにより、クリーンアップ済みでフェイクユーザーが設定された、クリップごとのベイク済みアクション（GAME_RIG_Body|Walk）が作成されます。また、クリップごとにミュートされた NLA トラック（CLIP_Walk）も作成されるため、FBX（bake_anim_use_nla_strips／全アクション）と glTF（ACTIONS モード）で全クリップをエクスポートできます。ベイク後はターゲットのコンストレイントがミュートされ、ベイク済みデータが再生されます。再びライブで動かすには --follow を実行します。セルフベイク（IK／コンストレイントから同じリグのキーへ）：--source X --target X。

モーションキャプチャとリターゲット

• インポート：bpy.ops.import_anim.bvh(filepath=..., global_scale=0.01 if cm else 1, rotate_mode="NATIVE", update_scene_fps=True)、import_scene.fbx（Mixamo、automatic_bone_orientation=True）。
• アドオンなしでリターゲットするには：ターゲットリグを同じレストポーズに設定します（T ポーズか A ポーズかが最も重要です）。各ターゲットボーンに COPY_ROTATION 制約を追加し、一致するソースボーンから回転をコピーします（ワールド空間または親を基準にしたローカル空間）。さらに、ヒップ／ルートに COPY_LOCATION を追加し、脚の長さの比率でスケーリングします。その後、bake_action.py --source TARGET --target TARGET で自身にベイクし、制約を削除します。
• モーションキャプチャをクリーンアップするには、キーを間引き（graph.decimate、比率は 0.3～0.5）、F カーブの SMOOTH モディファイアまたは Butterworth フィルター（graph.butterworth_smooth）を使用し、IK ピンで足滑りを修正してからベイクします。
• プロダクション向けのリターゲットツール：Auto-Rig Pro（有料）、Rokoko（無料）、エンジン側のリターゲッター（UE IK Retargeter、Unity Humanoid）。

NLA とポーズライブラリ

• NLA：アクションをストリップとして下段に配置し（track.strips.new(name, start, action)）、クリップをレイヤー化／ブレンドします（ブレンドタイプ REPLACE／ADD／COMBINE）。編集には Tweak モードを使用します。アクションに複数のスロットがある場合は、ストリップにアクションスロットを設定する必要があります（strip.action_slot）。
• ポーズライブラリ（同梱の pose_library）はポーズをアセットとして保存します：poselib.create_pose_asset(pose_name=...)、poselib.apply_pose_asset／blend_pose_asset。手の形、顔のポーズ、T／A レストポーズに使用します。

シェイプキーとその他のプロパティ

任意のプロパティにキーを設定できます：kb.keyframe_insert("value", frame=f)（シェイプキー）、mat.node_tree.nodes[...].inputs[...].keyframe_insert("default_value")（マテリアル。通常、各エンジンでは無視されます）、カスタムプロパティ ob.keyframe_insert('["prop"]')。

注意点

• pb.matrix = ... の後に keyframe_insert を実行する場合は、先に正しい scene.frame_set(f) を設定する必要があります。そうしないと、評価によってポーズが上書きされます。
• 接続されたボーン（use_connect）は移動できません。ヒップ／骨盤はルートから切り離す必要があります。
• ビジュアルキーイングを使った bake_action は、評価済みのポーズを読み取るため、制約、IK、ドライバーがすべて反映されます。その後、ターゲット自身の制約をミュートしてください（スクリプトが実行します）。そうしないと、キーが上書きされ続けます。
• クォータニオンとオイラー角：ゲームのボーンには QUATERNION を使用します（ジンバルロックがなく、スムーズに補間されます）。単一軸のコントロールにはオイラー角で問題ありません。キー間でモードを混在させないでください。
• glTF のサンプリング：export_force_sampling はすべてのフレームをベイクします（安全なデフォルト設定です）。非線形 F カーブモディファイアとドライバーは、サンプリング時にのみエクスポートされます。