scenario-blender-expert

Blender エキスパート（ルーターおよびエージェントプロトコル）

Blender でのエキスパートレベルの作業は、スクリプトではなく反復作業です。大きなところから小さなところへ進め、各段階でモデルを回転させて測定し、ディテールを加える前に修正します。このスキルは、すべての Blender タスクで従うプロトコルであり、Blender Studio のアーティスト、Blender Conference の講演、トップクラスのインストラクターからまとめたドメインスキルへの案内図です（出典は各スキルに記載）。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールのスキーマに基づいて進め、不足している点を明示してください。

1. 実行チャネル

• ライブ GUI Blender（MCP ブリッジ経由でユーザーのセッションに接続）。実際のスカルプト／ペイントブラシ、ウェイトペイント、ビューポートのスクリーンショットなど、対話的な作業に使います。各呼び出しにつき、コンパクトな結果辞書を返す短く冪等なスクリプトを 1 つ実行します。名前を使って取得または作成します。自分が作成していないオブジェクトには決して触れません。各段階の後に、ステージバックアップ bpy.ops.wm.save_as_mainfile(filepath=..., copy=True) を保存します。
• ヘッドレスヘルパー blender -b [file] --factory-startup --python-exit-code 1 -P x.py -- args。レンダリング、監査、一括処理など、ブリッジが起動していない場合に使います。ユーザーのアドオンや設定が実行に影響しないよう、--factory-startup を使います（アドオンがネットワークにアクセスしたり、デフォルト値を変更したりする可能性があります）。例外は Scenario Blender Plugin のヘッドレスサーバー blender --background scene.blend --command scenario_blender です。これは拡張機能が読み込まれている必要があります。--python-exit-code を付けない場合、スクリプトが失敗しても終了コードは 0 になります。最後に機械可読な結果の行を出力します。

ユーザーのマシンでテストするために、自分で GUI Blender ウィンドウを開いてはいけません。ウィンドウはフォーカスを奪い、次々と増えてしまいます。ライブ作業は、ユーザーがすでに起動している Blender を通して行います。それ以外の作業はすべてヘッドレスで実行し、エージェントごとに同時に起動する Blender プロセスは 1 つにします（同じマシン上でほかのセッションがレンダリングしている場合があります）。

ライブチャネル：Scenario Blender Plugin。 ユーザーの Blender で Scenario Blender Plugin が動作している場合、そのローカル MCP サーバー scenario-blender がブリッジになります。セットアップ、見積もり、生成、結果の配置は scenario-blender スキルの担当です。このセクションでは bpy 側を説明します（ガイド：blender.scenario.com）。このプラグインのツール名はほかの Blender MCP サーバーとは異なります。execute_blender_code、get_scene_info、get_viewport_screenshot、import_asset はありません。

手順	プラグインのツールと主な引数
操作前にシーンを読み取る	scene_summary を呼び出し、続けて 1 つのオブジェクトには name を指定して object_detail を、件数には datablocks_summary を呼び出します
スクリプト作成前に API を確認する	path（例：bpy.types.BevelModifier）を指定して blender_api_help を呼び出します
bpy を実行する	code を指定して execute_python を呼び出します。bpy と result = {} は事前に読み込まれているため、result に値を設定します
確認する	オーバーレイ付きビューポートには screenshot_viewport、source（CAMERA または VIEWPORT）、width、height を指定する render_still を使います。どちらも GUI が必要です
選択、タイムラインを移動する	リスト形式の names を指定して select_objects を、frame を指定して set_frame を呼び出します

最初に各ツールを呼び出す前に、サーバーから入力スキーマを読み取ってください。省略可能な引数の基準になります。

• execute_python は、プラグインの設定で 接続されたエージェントに Python の実行を許可 をユーザーが有効にするまで使用できません。PermissionError が発生した場合は、許可を求めるか、対象のツールだけを使ってください。拒否された操作（終了、工場出荷時設定へのリセット、ファイルの削除）は何も変更していません。呼び出しを書き換えてください。
• 呼び出しごとに時間を考慮してください。プラグインは 120 秒後に呼び出しを停止し、一部のエージェントクライアントは 60 秒後に待機を終了します。1 回の呼び出しにつき論理的な変更を 1 つだけ行い、1 回の取り消しで元に戻せるようにしてください。ベイク、密なメッシュでの QuadriFlow、ターンテーブル、プレイブラスト、最終レンダーは、保存済みコピー上で動作するヘッドレス Blender に任せてください。
• タイムアウトした呼び出しの結果は不明です。再試行する前にシーンを読み直し、確認せずに同じ呼び出しを再送しないでください。
• プラグインのツールがユーザー自身のファイルを保存することはありません。ライブチャネルのステージバックアップ（execute_python を通じた save_as_mainfile(..., copy=True)）は別ファイルを書き出し、開いているファイルとその未保存状態には影響しません。このファイルはヘッドレス処理の開始点となる保存済みコピーでもあります。節目ごとに、ユーザーに自身のファイルを保存するよう求めてください。確認できる相手がいない場合は、コピーを使って作業を続け、開いているファイルはまだ未保存であることをレポートに記載してください。

最初に bpy.app.version を確認してください。このスキルセットは 5.2 LTS を対象としていますが、Scenario Blender Plugin は 5.0 および 5.1 でも動作するため（scene_summary でバージョンを確認できます）、最近の API を使う前に差分にあるバージョンのタイムラインを確認してください。専門家が記録したチュートリアルの多くは UI バージョン 2.8x～4.2 を使用しています。記憶しているオペレーター、ブラシ名、API をそのまま信用する前に、references/blender-5.2-deltas.md を読んでください。

検証済みの機能マトリックス（Blender 5.2.1）：

操作	ヘッドレス	GUI セッション
ボクセルリメッシュ、QuadriFlow、マルチレゾリューションの細分化、モディファイアー、bmesh、編集モードのコンテキストを使う UV 操作、Cycles／EEVEE／Workbench のレンダー、ベイク	はい	はい
bpy.ops.brush.asset_activate、ダイナミックトポロジーの切り替え	はい	はい
ブラシストローク（sculpt.brush_stroke、paint.image_paint、paint.weight_paint）	いいえ（poll に失敗）	はい（scripts/bx_gui.py 経由）
paint.mask_flood_fill、sculpt.mesh_filter	Blender がクラッシュします	はい（bx_gui.run() 経由）
メッシュデータ上でのプログラムによるスカルプティング	はい（scenario-blender-sculpting/scripts/bx_sculpt.py）	はい

2. エキスパートの反復プロセス（すべてのドメイン）

1. ブリーフを数値で明確にします：目的（映画、ゲームエンジン、静止画、アニメーション）、予算（ポリゴン数、 テクスチャサイズ、フレーム範囲）、スタイル（様式化またはリアル）、参考資料。ブリーフに指定がない場合は、 ドメインスキルに記載されたデフォルトを選び、書き留めます。
2. ドメインスキルで定義された段階を計画します。ディテールから始めてはいけません。
3. 各段階を、小さなスクリプトで実装します。
4. 段階を評価します：測定可能なチェック（メッシュには scripts/bx_audit.py、ドメイン独自のチェック）を実行し、レビューシートも (scripts/bx_review.py：シルエット、マットキャップ、正面／側面／斜め前／低い視点からのワイヤーフレーム) レンダリングして、画像リーダーで開きます。エキスパートは常にモデルを回転させて確認します。レビューシートはエージェントにとっての回転確認です。画像の読み取りはすべてエージェントのコンテキスト内に保持します。手早く確認するには、 幅約768 pxのrender_stillまたはscreenshot_viewportを使い、レビューシートは約1600 pxにします （4つのビューと3つのモードではres=400）。ドメインの references/critique.mdに従って評価します。
5. 次に進む前に修正します。ブロックアウト時に見つかった問題はスクリプト1つで済みますが、テクスチャリング後に見つかると、その段階の作業が必要になります。
6. 根拠を添えて納品します：エクスポートまたは引き渡しの前に、アセットの各パーツに対して納品ゲート（下記のbx_audit.deliverable）を実行し、すべてのエラーを修正します。その後、最終レンダー、ゲートと監査の数値、未検証の項目を報告します。

レンダーを確認せずに、モデル、リグ、アニメーション、レンダーを完成したと報告してはいけません。

3. ペルソナ別パイプライン

ペルソナ／概要	スキルチェーン	成果物
キャラクターアーティスト（スタイライズまたはリアル）	scenario-blender-sculpting, scenario-blender-retopology, scenario-blender-uv-baking, scenario-blender-texturing-shading, scenario-blender-hair	スカルプト、アニメーション対応のローポリ、UV、ベイク済みマップ、マテリアル
AI メッシュ仕上げ担当（Scenario 3D 出力から本番制作まで）	生成アセットの品質を確認し、scenario-blender-retopology（またはクリーンアップ＋リメッシュ）、scenario-blender-uv-baking（生成された高ポリゴンメッシュからベイク）、scenario-blender-texturing-shadingを使用。生成自体にはscenario-3dを使用	指定された予算内のクリーンなアセット（UV 作成済み、ベイク済み）
ゲームアセットアーティスト	scenario-blender-hard-surfaceまたはscenario-blender-sculpting、scenario-blender-retopology（ゲーム向け予算）、scenario-blender-uv-baking、scenario-blender-texturing-shading、scenario-blender-export	ローポリ＋PBR セット、glTF/FBX でエクスポート済み
リガー／キャラクター TD	scenario-blender-rigging	コントローラー付きリグ、ウェイト、変形テスト
アニメーター	scenario-blender-previs-storyboard（ショット計画）、scenario-blender-animation	ブロッキング、スプライン化、仕上げ済みのショット＋プレイブラスト
ストーリー／プリビズアーティスト	scenario-blender-previs-storyboard、scenario-blender-grease-pencil	ショット、カメラ、アニマティック
ルック開発・ライティングアーティスト	scenario-blender-texturing-shading、scenario-blender-lighting-rendering	ライティング済み、カラー管理済み、コンポジット済みのレンダー
テクニカルアーティスト／プロシージャル担当	scenario-blender-geometry-nodes	ノードグループアセット、プロシージャルシステム
2D／2.5D アニメーター	scenario-blender-grease-pencil	GP アニメーション

このセット以外の関連スキル：scenario-3d（生成したメッシュをここで仕上げます）、scenario-textures（AI テクスチャ）。

4. 共通ツールキット（scripts/、すべて 5.2.1 でテスト済み）

• bx_audit.py：audit(obj, high=None) は、四角形面の割合、N ゴン、ポール（価数 3／5 以上／6 以上）、 非多様体、孤立要素、重複、反転した面、自己交差、境界ループ、対称性の割合、 エッジ長の変動係数、高ポリゴンモデルへの忠実度を返します。verdict(report) は問題点を列挙します。CLI： blender -b f.blend --python bx_audit.py -- --object Name [--high Sculpt] [--json out.json]。
• bx_audit.deliverable(objs, profile="game")：納品ゲートです。audit はトポロジーを評価しますが、こちらは 1 つのアセットを構成するパーツ全体を対象に、エンジン、レンダラー、スライサーが受け取るデータを評価します。
  • すべてのプロファイルでエラーとなるもの：モディファイアー適用後に面がなくなるメッシュ、浮遊するパーツや断片、内側を向いた閉じたパーツ、負のスケール、print 以外のすべてのプロファイルにおけるパーツ間の Z ファイティング。
  • プロファイル別（game、render、print、roblox）：未適用のスケール、パーツの内側を向いている面（表面の 0.1% からエラー、それ未満は警告。ただし print を除く）、重複面、画像テクスチャ使用時に UV マップがないこと、print と roblox における開いた境界、print におけるパーツ間のあらゆる隙間、Roblox のメッシュ上限である 20,000 トライアングル（2026-10-18 に確認）。
  • {pass, errors, warnings, per_object} を返します。許容誤差はアセットの対角線に応じて変わります。 glTF インポート時の UV シームの分割はチェック時に溶接されるため、シームが穴として判定されることはありません。
  • 個別のプロップは 1 つずつゲートにかけてください。最も大きいもの以外はすべて浮遊していると判定されます。
  • CLI。失敗時の終了コードは 2 です： blender -b --factory-startup --python-exit-code 1 -P bx_audit.py -- --deliverable [--import model.glb | --objects A B] --profile game [--json out.json]。
  • 修正方法：スケールを適用します（obj.data.transform(Matrix.Diagonal(obj.scale).to_4x4()) を実行してから obj.scale = (1, 1, 1) とします。メッセージに表示されたスケールが親オブジェクトに設定されている場合は、親とその子を選択し、 bpy.ops.object.transform_apply(scale=True) を実行します）。内側を向いたパーツには bmesh.ops.recalc_face_normals、 内側を向いた面には bmesh.ops.reverse_faces（per_object[name]["inward_faces_at"]）を使います。Z ファイティングするペアの隠れた面を削除するか、位置をずらし、浮遊するパーツを結合するか移動し、断片を削除します。
  • エンジンは裏面をカリングします。エンジンで描画される状態を確認するには、 bx_review.review(parts, out, culling=True) をレンダリングします（マゼンタ色は内側を向いた面越しに表示されます）。カリングなしのシートと比較してください。
• bx_review.py：review(objs, out_dir, views, modes, culling=False) はオブジェクトまたは名前を受け取り、一時シーンで 1 枚のコンタクトシート（行＝モード、列＝ビュー）を作成します。ユーザー設定は変更されません。playblast(out_path, res_pct=50)、turntable(obj, out_path, frames=72, res=720) もあります。コマンドラインに対応しているのは review のみです。ほかの関数は短いラッパースクリプトから呼び出してください。
• bx_gui.py：ライブセッションで実際のブラシを操作します：set_view、activate_brush(mode, name)、 stroke(mode, world_points, size, strength)、run(op, **kw)、set_paint_color、screenshot。

インポートパターン：import sys; sys.path.append("<this skill>/scripts"); import bx_audit, bx_review。 <this skill> は、インストール済みスキルフォルダーの絶対パスに置き換えてください。Blender の Python は エージェントの作業ディレクトリを共有せず、ライブブリッジ経由ではコードがユーザーの Blender 内で実行されます。最初の呼び出しでパスを確認し（result["ok"] = os.path.isdir(path)）、 スキルの更新後は importlib.reload でモジュールを再読み込みしてください。

5. 記憶しているコードが動かなくなる、よくあるバージョンの落とし穴

• ブラシはアセットです（4.3）： bpy.ops.brush.asset_activate(asset_library_type='ESSENTIALS', asset_library_identifier="", relative_asset_identifier="brushes/essentials_brushes-mesh_sculpt.blend/Brush/Clay Strips")； ブラシサイズは直径です（5.0）。Flatten／Fill／Scrape は Plane タイプに統合されました。
• Auto Smooth は削除されました（4.1）：mesh.shade_smooth()／Smooth by Angle モディファイアーを使用します。ボクセルリメッシュの出力は、 shade_smooth() を呼び出すまでフラットシェーディングになります。
• Principled BSDF v2（4.0）：ソケットは名前で指定します。Emission strength のデフォルト値は 0 です。
• 5.x では BLENDER_EEVEE が EEVEE Next の識別子です（BLENDER_EEVEE_NEXT は機能しません）。
• コンポジターはノードグループです（5.0）：scene.node_tree ではなく、scene.compositing_node_group を使用します。
• 動画の出力：file_format = 'FFMPEG' を設定する前に、image_settings.media_type = 'VIDEO' を設定します（5.0）。
• スロット付きアクション（4.4）では、action.fcurves は削除されました（5.0）。代わりに bpy_extras.anim_utils.action_get_channelbag_for_slot(action, slot) を使用します。
• アーマチュアレイヤーはボーンコレクションに置き換えられました（4.0）。Grease Pencil v3 は GREASEPENCIL で、演算子には bpy.ops.grease_pencil.* を使用します（4.3）。
• 演算子に位置引数で渡すコンテキスト辞書は廃止されました。with bpy.context.temp_override(...) を使用します。
• 位置やスケールを設定した直後は、view_layer.update() を呼び出すまで obj.matrix_world は古い値のままです。

参考資料

• references/bpy-reliability.md：信頼性の高い bpy のためのチェックリストと検証済みの手順 （演算子とデータ API、古い参照、評価済みデータと元データ、冪等なヘッドレスジョブ、numpy による一括アクセス、ノードツリー、永続化）。複雑なスクリプトを書く前に読み込んでください。
• references/blender-5.2-deltas.md：ドメインごとに、2.8x から 5.2 までの変更点を出典付きで網羅した一覧 （記憶を頼りにコードを書く前、または古いチュートリアルに従う前に読み込んでください）。