Blenderコントロールスキル（ライブGUI + ヘッドレスCLI）

このワークスペースは、Blender 5.2.1 LTS（/Applications/Blender.app/Contents/MacOS/Blender、Python 3.13、Apple M1 Pro 16コアMetal GPU）を2つの補完的なモードで制御します。

ライブGUIモード（デフォルト、推奨）：開いているBlender.appウィンドウ内で動作するblender_control_bridge.pyに対して、127.0.0.1:9876経由でコマンドを送信します。オブジェクト、シェーダー、アニメーション、カメラフレーミングがユーザーの目の前に即座に表示されます。
ヘッドレスCLIモード：/Applications/Blender.app/Contents/MacOS/Blender --backgroundを実行し、アクティブなGUIセッションに触れることなく、分離されたバッチレンダリングや負荷の高いバックグラウンドジョブを実行します。

Blender 5.2向けにbpyスクリプトを作成する前に、blender_5_2_api_guide.mdを確認し、重要な5.2 APIの変更点（Principled BSDFソケット名、スロットアクションchannelbag、media_type = 'VIDEO'、Metal GPUのセットアップ）を把握してください。

ステップ1：開いているBlenderアプリケーションの確認と接続

常に最初にライブブリッジ接続を確認します。

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

pingが失敗した場合（例：Blenderがまだ開いていない、またはスタートアップブリッジをインストールする前に起動された場合）、インストーラー/コネクタースクリプトを実行します。

bash .agents/skills/blender-control/scripts/install_bridge.sh

blender_control_bridge.pyを~/Library/Application Support/Blender/5.2/scripts/startup/にコピーし、GUI起動時に毎回127.0.0.1:9876でブリッジが自動的に起動するようにします。
ウィンドウフォーカスを奪うことなく、Blender.appに安全に接続または起動します（open -g -a Blender）。
Blender.appにブリッジがロードされていない未保存の.blendファイルがすでに開かれている場合は、ユーザーにmacOSメニューバーからBlender -> システム -> スクリプトの再読み込みをクリックするよう依頼してください。

ステップ2：`blender_cli.py`を使用したライブシーンの検査と制御

すべてのライブ操作にはblender_cli.pyを使用します。

# 1. 現在のオブジェクト、カメラ、マテリアル、フレーム範囲、レンダーエンジンを検査
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. ライブシーンをクリーンにクリア（すべてのオブジェクトと孤立したデータブロックを削除）
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. シーンビルダーのPythonスクリプトをBlenderのメインUIスレッドでライブ実行
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. インラインのPython式/スニペットを素早く実行
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. ユーザーのライブBlender 3Dビューポートをマテリアルプレビューまたはレンダリングカメラビューに切り替え
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. ライブGUIで.blendプロジェクトファイルを保存または開く
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

ステップ3：静止画、ビューポートプレビュー、アニメーションのレンダリング

高速ビューポートプレビュー（<0.2秒）

完全なレイトレースレンダリングを実行する前に、まずビューポートのスクリーンショットを使用してカメラフレーミング、オブジェクト配置、クリッピングを確認します。

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

read_fileで/tmp/preview.pngを検査し、構図とライティングを視覚的に確認します！

高品質静止画レンダリング（Cycles Metal GPU または EEVEE）

# Cycles（自動Apple M1 Pro 16コアMetal GPUアクセラレーション）
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# EEVEEによる高速リアルタイムPBRレンダリング
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

MP4（H.264）アニメーションレンダリング

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

ヘッドレスバッチモード（分離プロセス）

ライブGUIビューポートをブロックせずに負荷の高いジョブをレンダリングする場合：

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

ステップ4：シーン構築と検証チェックリスト

自己完結型ビルダースクリプト：各プロジェクトをprojects/<project_name>/build.pyに保存します。これにより、シーンが100％再現可能になり、レンダリング出力や.blendファイルと一緒にGitに適した状態になります。
カメラエイミング（TRACK_TO またはクォータニオン）：常に(target - cam.location).to_track_quat('-Z', 'Y')を使用して、ターゲットのEmptyまたはワールド座標にカメラを確実に向け、scene.camera = camを設定します。
三点照明 / スタジオ照明とワールド：暗いデフォルトの灰色の背景のままにしないでください。ワールドシェーダーノードとエリア/サンライトを設定し、現実的なワット数（シーンスケールに応じて100W～1500W）、AgXまたはFilmicカラーマネジメント（scene.view_settings.view_transform = 'AgX'、look = 'AgX - Medium High Contrast'）を構成します。
視覚的確認：レンダリングされた.pngまたは.mp4出力をread_fileで常に検査し、フレーミング、露出、マテリアル、モーションを完了前に確認します。
GitHub同期：プロジェクト/スキルを作成または更新した後、./scripts/sync_github.sh "<コミットメッセージ>"を実行して、ローカルとorigin/mainを同期状態に保ちます。

blender-control (Blenderコントロールスキル)