text-to-blender

テキストからBlenderへのオーケストレーター

平易な英語のリクエストをBlenderの作業に変換します。あなたは指揮者です。リクエストを読み、どのサブスキルを連鎖的に読み込むかを決め、適切な順序に並べ、Blender MCPを通じて実行します。

複数スキルの調和

複数のBlenderスキルを必要とする複雑なタスク、特に参照資料、テンプレート、ブランドに関する作業では、実行順序を決める前にblender-skill-harmonizerを読み込んでください。優先順位、引き継ぎ成果物、競合時の方針を管理します。

ユーザーが出力を低品質だと指摘した場合、同じ問題が繰り返し発生していると言った場合、または再試行の前にスキルスタックの改善を求めた場合は、以降の制作作業に進む前にquality-refinement-autoloopを読み込んでください。証拠からサニタイズ済みの再利用可能な教訓を作成し、明示的に依頼された場合に限り、汎用スキル、ドキュメント、バージョン管理に修正を加えてから、Blenderの修正ループを再開します。

このスキルの仕組み

ユーザーは「石の上に置いた剣のヒーローショットをレンダリングして」のようなタスクを伝えます。あなたは次の手順で進めます。

1. 意図を特定する → 必要な機能（モデリング？マテリアル？ライティング？レンダリング？エクスポート？）。
2. 前提条件を確認する → MCP サーバーに接続できるか、シーンの状態。
3. ワールドをリセットする（常に手順3。以下のワールドのリセットを参照）— 前回の実行で残った壊れたHDRI／Environment Textureノードによるレンダリングの破損を防ぎます。
4. 対象物の実物の寸法を調べる（references/common-object-dimensions.md）— Pythonを生成する前に行います。「剣」や「椅子」にはそれぞれ固有の比率があるため、推測してはいけません。
5. サブスキルに振り分ける → Readを使って関連するサブスキルを読み込み、その指示に従います。
6. 順序を決める → プロが使う順序で作業を進めます（references/assembly-order.mdを参照）。
7. 実行する → 生成したPythonをmcp__blender__execute_blender_codeで実行します。
8. 検証する → mcp__blender__get_scene_info、get_object_info、および**get_viewport_screenshot**を使用します。以下のビジュアル検証チェックポイントを参照してください。数値による検証だけでは不十分です。APIが成功を報告していても、ジオメトリが大きく間違っていることがあります。
9. 反復する → ビジュアルチェックで明らかな問題（対象物がほとんど見えない、比率が違う、向きが違う）が見つかった場合は、成功を報告する前に修正して再レンダリングします。
10. ユーザーに報告する → 具体的な数値と、確認できるレンダリング結果のパスを伝えます。

ワールドのリセット（常に手順3。構図を作る前に実行）

前回のテストによって、シーンのワールドが壊れた状態で残ることがあります。特に、image=NoneのEnvironment TextureノードがBackgroundノードにつながったままだと、レンダリング全体がマゼンタ色になることがあります。各シーンの構築を始めるときに、ワールドをニュートラルな状態にリセットしてください。

def reset_world(scene, color=(0.04, 0.04, 0.05, 1.0), strength=0.4):
    world = scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    for n in list(nodes):
        nodes.remove(n)
    output = nodes.new('ShaderNodeOutputWorld')
    bg = nodes.new('ShaderNodeBackground')
    bg.inputs['Color'].default_value = color
    bg.inputs['Strength'].default_value = strength
    world.node_tree.links.new(bg.outputs['Background'], output.inputs['Surface'])

ユーザーがHDRIライティングを希望する場合は、これを実行した後に上書きしてください（実際の.hdrファイルを読み込み、env.image is not Noneを確認します）。

ビジュアル検証チェックポイント（常に手順8と10の間に実行）

レンダリング後は、必ず次の手順を行います。

1. mcp__blender__get_viewport_screenshotを呼び出します（またはレンダリング済みファイルをReadで読み込みます）。
2. ユーザーのリクエストと照らし合わせて視覚的に確認します。具体的には、次の点を確認します。
   • 対象物が見えていて、何であるか認識できる（細い筋状になっていない、マゼンタ色に覆われていない、完全に影に隠れていない）
   • 比率が対象物の実物の寸法に関する参照情報と一致している
   • 構図に問題がない（対象物がフレーム内にあり、端で切れておらず、隅に極小サイズで配置されていない）
   • マテリアルに視認できる変化がある（表面が完全に均一でプラスチックのように見えない）。本番品質のシーンでは、プロシージャルテクスチャノードを追加します。
3. レンダリング結果に明らかな誤りがある場合は、成功を報告してはいけません。問題を特定し、修正して、再レンダリングし、もう一度確認します。

数値によるチェック（オブジェクト数、頂点数、ファイルサイズ、エラーメッセージなし）をすべて通過していても、レンダリング結果が完全に間違って見えることがあります。ユーザーが見るのは画像だけです。完了を宣言する前に、画像がリクエストに合っていることを確認してください。

ビューポートをマテリアルプレビューに設定する（報告前の最後のステップ）

ユーザーはレンダリング済みファイルではなく、Blender のビューポートを見ていることがよくあります。Blender のビューポートはデフォルトでソリッドシェーディングモードになっており、すべてのマテリアルが無視され、すべてが単色のグレーで表示されます。シーンの組み立て後にビューポートをマテリアルプレビューに切り替え、ユーザーが実際にマテリアルを確認できるようにします。

import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'           # or 'RENDERED' for full quality
                space.shading.use_scene_lights = True
                space.shading.use_scene_world = True

ユーザーからビューポートに触れないよう明確に依頼された場合に限り、この手順を省略します。

実寸の参照

自然言語で指定された対象のサイズを決める前に、references/common-object-dimensions.md を参照してください。よくある依頼に対する現実的な比率が記載されています。

対象	全体	備考
片手剣	長さ約95～100 cm	刃：78cm × 4.5cm × 0.8cm、鍔：20cm × 2.5cm、柄：13cm、柄頭：5.6cm
椅子	座面：約45cm × 45cm × 4cm	座面の高さ：45cm、背もたれ：約45cm
ボトル	高さ25～30cm	本体：ø8～10cm、首部：ø2～3cm

完全な参照リストは references/common-object-dimensions.md にあります。推測しないでください。

前提条件 — 必ず最初に確認する

作業を始める前に、次の項目を確認します。

1. Blender MCP に接続できること。mcp__blender__get_scene_info を呼び出します。「Could not connect to Blender」というエラーが発生した場合：

   "Blender の MCP アドオンが実行されていません。Blender を起動し、BlenderMCP アドオン（デフォルトポート9876）を有効にしてから、もう一度実行してください。"

   停止して、ユーザーに修正を依頼してください。

2. シーンの状態。get_scene_info は現在のオブジェクトを返します。次のように判断します。

   • シーンが空ですか？ → 新しく開始し、プリミティブから作成します。
   • 既存のオブジェクトがありますか？ → それらを使って作業します。依頼されない限り削除しないでください。
   • デフォルトの立方体だけですか？ → 削除しても問題ない可能性があります（bpy.ops.object.delete()）。

3. ユーザーの実際の依頼。曖昧な場合は、質問を1つだけします。それ以外の場合は、妥当なデフォルト設定で進めます。

意図 → スキルの選択表

ユーザーが示した意図ごとに、該当するサブスキルの SKILL.md を（Read を使って）読み込み、その手順に従います。複数の意図がある場合は、複数のサブスキルを順に適用します。

ユーザーの意図（言い換え）	読み込むサブスキル	順序
「X の3Dモデルを作って」	blender-modeling	最初
「このワイヤーフレーム図から」	wireframe-to-3d	最初
「このマテリアルを使って／X のように見せて」	blender-materials	モデリングの後
「ライティングして／スタジオセットアップ／シネマティックに」	blender-lighting	ジオメトリ作成後
「ヒーローショット／カメラアングル／被写界深度」	blender-cameras	ライティングの後
「レンダリングして／画像を作成して」	blender-rendering	ビジュアル作成の最後
「アニメーション化して／時間経過に伴って移動・回転させて」	blender-animation	ジオメトリ作成後
「glTF／FBX／OBJ／ウェブ用／Unity 用にエクスポートして」	blender-export	最後
「シーンをセットアップして／本番品質の仕上がりにして」	blender-pro-workflow	最初 — すべてを導く
「初心者なので／どこから始めればよいかわからない」	blender-pro-workflow	最初
「品質が低い／まだ違う／同じ問題がまた起きた」	quality-refinement-autoloop、次に blender-skill-harmonizer	最初 — 学習、サニタイズ、パッチ適用の後に再試行
「これらのテンプレート／ワイヤーフレーム／テクスチャに正確に合わせて」	blender-skill-harmonizer、次に参照素材に応じた適合スキル	最初 — 真実の基準となるゲートを設定

複数の意図がある場合の例：「剣をモデリングしてマテリアルを設定し、ドラマチックに照らして、glTF としてエクスポートして」 →

1. blender-pro-workflow（手順の方針）
2. blender-modeling（剣のジオメトリ）
3. blender-materials（鋼と革の柄）
4. blender-lighting（ドラマチックな1灯またはリム照明のセットアップ）
5. blender-export（glTF の設定）

プロのアセンブリ順序（迷ったときは）

この順序でやり直しを最小限に抑えられます。ユーザーから複数ステップの依頼があった場合は、次の順序で進めてください。

1. 参考資料＋計画 — 目標を確認します。
2. ブロックアウト — プリミティブ＋カメラ＋構図。最も手軽に調整できます。
3. カメラを固定 — 焦点距離を選び、ショットのフレーミングを決めます。
4. ライト v1 — マテリアル作業の前に、3点照明（キー／フィル／リム）を設定します。ライティングが雰囲気を決めます。
5. ジオメトリを仕上げる — プリミティブを実際のモデルに置き換えます。
6. マテリアル v1 — まずは単色で、明度を適切に調整します。
7. ライト v2 — 色と比率を調整します。
8. ディテールの追加 — 上記が適切になってから行います。
9. 最終レンダー — 本番用のサンプル数とデノイズを設定します。
10. コンポジット — カラーグレーディング、グレア、ビネットを適用します。
11. エクスポート — 対象プラットフォーム向けに出力します。

出典：references/assembly-order.md（詳しい理由）。

コード実行ルール — 必ず守ること

mcp__blender__execute_blender_code 用の Python を出力する場合：

• 呼び出しごとに新しい名前空間になります。 bpy のみ事前にインポートされています。呼び出しごとに math、bmesh、numpy などを再インポートしてください。
• オブジェクトは安定した名前で識別してください。 Python 変数では識別しないでください。bpy.data.objects['GEO-sword'] は呼び出しをまたいで使えますが、sword = ... という代入は使えません。
• 解析しやすいよう、構造化された出力を表示してください。 各チャンクの最後に print(f"...") を置き、変更内容（オブジェクト名、頂点数、ファイルパス）を報告します。
• 作業を分割してください。 呼び出しごとのタイムアウトは 180 秒です。500 行を一度に出力せず、約 5〜20 行のチャンクに分割してください。
• 作成するものすべてに Blender Studio の命名規則を使用してください。 GEO-、MAT-、LGT-、CAM-、ARM-、COL- を使用します。Cube.027 のような名前を残さないでください。

すべての操作で使う標準スケルトン

import bpy
# (re-import other modules here as needed)

# 1. Scope: identify or create objects by NAME
obj = bpy.data.objects.get('GEO-target') or bpy.data.objects.new('GEO-target', None)

# 2. Do the work
# ...

# 3. Report
print(f"done:GEO-target {len(obj.data.vertices) if obj.data else 0}")

命名規則（作成するすべてのものに適用）

接頭辞	意味
GEO-	ジオメトリ／メッシュオブジェクト
MAT-	マテリアル
LGT-	ライト
CAM-	カメラ
ARM-	アーマチュア（リグ）
COL-	コレクション
WGT-	カスタムボーンシェイプ／ウィジェット

左右には接尾辞 .L／.R を付けます。例：GEO-sword_blade、MAT-steel_brushed、LGT-key。

検証時の目安

大きな作業の後は、mcp__blender__get_scene_info を呼び出し、次の項目を確認してください。

• 期待するオブジェクトが正しい名前で存在する。
• オブジェクト数が妥当である（重複が大量に発生していない）。
• ポリゴン数がおおむね目標に合っている。

レンダーやエクスポートの成功を報告する前に、ファイルが実際に存在することを確認してください（Bash を使って ls -la /path/to/output を実行します）。

詳細なリファレンスを読み込むタイミング

• references/assembly-order.md — シーン構築の標準手順、時間配分、復旧パターンを記載しています。複数ステップのパイプラインを計画するときや、ユーザーから「適切な順序は？」と尋ねられたときに読み込みます。
• references/intent-routing.md — エッジケースを含む、インテントとスキルの対応関係を詳しく記載しています。依頼が曖昧で、意図を明確にする必要があるときに読み込みます。
• references/code-execution-rules.md — execute_blender_code の詳細なルール（名前空間、タイムアウト、標準出力の取得）を記載しています。実行エラーの原因を調べるときに読み込みます。

ユーザーへの報告

作業が完了したら、具体的に報告してください。

• ✅ 作成：オブジェクトとポリゴン数の一覧。
• ✅ ライティング：ライトとそれぞれの役割の一覧。
• ✅ レンダー：ファイルパス、サイズ、解像度、レンダー時間。
• ⚠️ 警告：自動デシメーション、命名の競合、代替マテリアルなど。

例：

GEO-sword_blade（1 240 頂点）、GEO-sword_grip（320 頂点）を作成しました。
マテリアル：MAT-steel_brushed、MAT-leather_dark。
LGT-key（暖色 3200K）、LGT-fill（寒色 5500K）、LGT-rim（寒色の青）でライティングしました。
/tmp/sword_hero.png にレンダーしました（1920×1080、2.3 MB、256 サンプル＋OptiX デノイズで 38 秒）。

失敗のパターン — このような場合の対処方法…

問題	対処方法
MCP のタイムアウト	失敗したチャンクをより小さな単位に分割します
Code execution error: <line>	エラーを確認し、その行だけを修正して再試行します
次の呼び出しでオブジェクトが見つからない	bpy.data.objects['name'] ではなく、Python 変数を使用しています
レンダリングに時間がかかりすぎる	サンプル数を減らし、適応型サンプリングを有効にして、解像度を下げます
ファイルが想定したパスにない	絶対パスを使用し、Bash の ls で確認します
エクスポート後にマテリアルがおかしく見える	Principled BSDF 以外のノードを使用しています。Principled のみでマテリアルを作り直します
'Action' object has no attribute 'fcurves'	Blender 5.x では Action がレイヤー化されています。代わりに action.layers[].strips[].channelbags[].fcurves をたどってください。互換性ヘルパーについては blender-animation Recipe 3 を参照してください。
BLENDER_EEVEE_NEXT が拒否される	Blender 5.x では名前が BLENDER_EEVEE に戻っています。try/except のフォールバックについては blender-rendering Recipe 3 を参照してください。
KeyError: 'Subsurface IOR'（またはほかの入力名）	Blender 5.x では、一部の BSDF 入力（現在は Weight、Subsurface IOR）が enabled=False に設定されています。イテレーションでアクセスできますが、文字列キーによる検索ではアクセスできません。set_input ヘルパーについては blender-materials Recipe 9 を参照してください。
Error: Cannot render, no camera	scene.camera is None です。レンダリングの前には必ず ensure_camera() ガードを実行してください。詳しくは blender-rendering Recipes 5 / 6 を参照してください。ユーザーのプロンプトでカメラが明示的に求められていない場合でも、オーケストレーターはレンダリングにつなぐ前にこれを確認する必要があります。
Blender のビューポートを見ているユーザーから「シーンがグレーで、マテリアルが表示されない」と報告された	Blender のビューポートはデフォルトでソリッドシェーディングモードになっており、マテリアルが反映されません。レンダリングは正しく、ビューポートだけがグレーに見えています。シーンの組み立て後は必ず、ビューポートをマテリアルプレビューに設定します：space.shading.type = 'MATERIAL'; space.shading.use_scene_lights = True; space.shading.use_scene_world = True
ユーザーから「マテリアルが平坦で、テクスチャがない」と報告された	平坦な PBR カラーには表面の変化がありません。スチールの傷、ハンマードメタル、レザーの粒などには、プロシージャルテクスチャ（Noise/Voronoi → ColorRamp → Roughness または Bump）を追加します。パターンについては blender-materials Recipe 12（プロシージャルな木材）を参照してください。
対象のプロポーションがおかしい（例：刃が短すぎる、椅子の幅が狭すぎる）	オーケストレーターが寸法の参照を省略しています。モデリングコードを生成する前に、必ず references/common-object-dimensions.md を読みます。推測しないでください。
ユーザーが「人間」／「キャラクター」／「顔」／「人物」を求めている	プリミティブだけを使うレシピで生成できるのは、認識可能なシルエットだけであり、人間の顔ではありません。次のいずれかを提案してください：（a）mcp__blender__download_polyhaven_asset / download_sketchfab_model / generate_hyper3d_model_via_text を使って実際の人間のベースメッシュを用意し、その後マテリアル、ライティング、レンダリングへとつなぐ。（b）Blender のキャラクターアーティストに依頼する（prompts/04-blender-workflow.md を参照）。球体に特徴を付けただけで人間のように見えると装わないでください。実際にはそう見えません。references/common-object-dimensions.md の「キャラクター／アバター」セクションを参照してください。
細長い対象が、認識可能な形状ではなく細い棒のようにレンダリングされる	カメラが細長いオブジェクトの細い軸を向いています。広い軸がカメラを向くよう、オブジェクトを回転させてください。blender-modeling の「重要：細長いオブジェクトの軸の向き」を参照してください。
刃やスパイクの先端が尖らず、「ノミで削ったように平ら」になる	上部の頂点がゼロに近づくようスケールされましたが、結合されていません。blender-modeling の正しいテーパー処理のレシピ（「重要：一点に向けてテーパーする」）を使い、上部の頂点を中心線に集約してから remove_doubles を実行します。
色付きガラスが「ガラスらしく」ならず、平坦または金属的にレンダリングされる	Principled BSDF の Base Color だけに色を設定しています。本物の色付きガラスには、深さに応じた色合いを出すためのボリューム吸収が必要です。blender-materials Recipe 6b を参照してください。また、Roughness=0.0 では鏡のように平坦なハイライトになり、金属的に見えます。代わりに 0.02–0.05 を使用します。
ガラスの内側が黒くレンダリングされる	transmission_bounces が低すぎます。厚いガラスや多層ガラスでは、デフォルトの 12 では不十分です。scene.cycles.transmission_bounces = 24 に設定します。

このスキルの対象外

• 大規模なカスタム GPU 作業やレンダリングエンジンの作成（Blender の既存エンジンを使用してください）
• リアルタイムのゲームロジック（Unity／Unreal を直接使用してください）
• 自然言語によるスカルプトストロークの作成（スカルプトはジェスチャーを使う作業です。ブラシを使って対話的に作業してください）
• Blender の機能範囲外の作業（CAD の高精度モデリングには FreeCAD を、CFD シミュレーションには VFX 品質の用途に限って Blender の Mantaflow を使用し、工学用途には使用しないでください）

これらをユーザーから依頼された場合は、丁寧に別の手段を案内し、その理由を説明してください。