blockbench-mcp-overview

Blockbench MCP の概要

コンテンツを変更する場合は、最初に blockbench-use を読み込んでください。実行中のサーバーのツール一覧とスキーマによって、利用できる操作が決まります。このソーススキルには、インストール済みバンドルより新しいツールが記載されている場合があります。ツールの状態や成功メッセージだけでは、結果を確認したことにはなりません。

ホストとワークフローを確認する

get_capabilities: include_tools=true
# → blockbench, plugin, project, format, formats, tools, notes
list_modes
# → current_mode, modes[{id, available, selected, ...}]

project は null の場合があります。登録済みのフォーマット ID を正確に使用してください。Generic Model は通常 free です。プロジェクトを切り替えずに、get_capabilities: format_id="free" で候補のフォーマットを確認してください。詳細な機能フラグは null（不明）の場合があります。簡易一覧では、true のフラグと不明なフラグが区別されます。インストール済みのプラグインフォーマットは、これらのスキルに固定された許可リストではなく、検出によってサポートされます。

ツールがエディターの状態に依存する場合は、list_modes と set_mode: mode_id="<returned ID>" を使用してから、利用可能な機能を再確認してください。Animate のモード ID は animation ではなく animate です。モードを変更しても、プロジェクトのフォーマットは変わりません。

ワークフロー	ツールまたはガイダンス
キューブ、メッシュ、グループ	モデリング
キューブ／メッシュの UV、テクスチャ画像、ペイント、レイヤー	テクスチャリング
グループリグ、キーフレーム、カーブ、タイムライン	アニメーション
パーティクルエフェクト、ロケーター、パーティクルキーフレーム（create_particle_effect、add_locator、manage_particle_keyframes、export_particle_pack）	パーティクル
Normal／Height／MER チャンネルマテリアル	PBR マテリアル
カラーテクスチャから Normal／Height／MER マップを生成（PyPBR または vgpu、Depth Anything）	Albedo から Normal へ
Hytale 固有のフォーマット、アタッチメント、可視性	Hytale
ネイティブアーマチュアと頂点ウェイト	下記のアーマチュアのセクション
Java アイテム／ブロックの表示変換	下記の表示のセクション
Bedrock ブロックの面マテリアル名	下記の Material-instance のセクション
元に戻す履歴とファイルの受け渡し	下記の復旧／エクスポートのセクション

検査と ID

対象を絞った質問には find_elements_by_criteria と filter_by_material を優先し、階層を把握するには list_outline を使用してください。既存アセットに言及する前に、list_textures と list_materials を読み込んでください。特にグループとそのキューブでは、名前が重複する場合があるため、UUID を保持してください。

place_mesh は {meshes: [{name, uuid, vertex_keys, face_keys}]} を返します。コンポーネントの配列は入力順に並びます。他のメッシュ作成ツールや既存のメッシュは get_mesh_info で確認できます。このツールの頂点と面には、それぞれ独立した next_offset 値があります。変更を加える前に、null まで読み込んでください。位置と法線はメッシュローカルです。トポロジーを変更した後や元に戻す／やり直した後は、再度検査してください。実行可能なクライアントオーケストレーションの例については、モデリングスキルを参照してください。

get_cube_uv: id="<cube UUID>" は、ボックス／面ごとのモード、面の UV、実効テクスチャ寸法を読み取ります。set_cube_uv は、フォーマットチェックを行ったうえでこれらの値を編集します。list_textures は uv_size、bitmap_size、frame_size を報告します。create_texture では、テクスチャごとの UV 寸法に対応するフォーマットで、明示的な uv_width／uv_height のペアを設定できます。スキーマと例はテクスチャリングスキルに記載されています。

リソースには、projects://{id}、nodes://{id}、textures://{id}、および Hytale 固有のリソースが含まれます。ID を推測せず、実行中のサーバーからリソーステンプレートと具体的な URI を検出してください。プロジェクトのエクスポートでは、ライブの .bbmodel リソースリンクが返される場合もあります。

小規模なモデルとアニメーション

これは、新規に作成する Bedrock エンティティ向けのツール呼び出しの擬似コードです。最初にフォーマットが登録されていることと、プロジェクトがアニメーションをサポートしていることを確認してください。

create_project: name="robot", format="bedrock"
add_group: name="body", origin=[0, 12, 0]
place_cube: elements=[{name: "torso_geo", from: [-4, 12, -2], to: [4, 24, 2]}], group="body"

create_texture: name="skin", width=64, height=64, fill_color="#808080", layer_name="base"
apply_texture: id="torso_geo", texture="skin", applyTo="all"

idle = create_animation: name="idle", animation_length=2, loop=true, bones={}
manage_keyframes: animation_id=idle.uuid, action="create", bone_name="body",
  channel="rotation", keyframes=[
    {time: 0, values: [0, 0, 0]},
    {time: 1, values: [0, 5, 0]},
    {time: 2, values: [0, 0, 0]}
  ]
animation_timeline: animation_id=idle.uuid, action="set_time", time=1
capture_screenshot

idle.uuid には返された値を割り当ててください。これはツールに渡すリテラル引数ではありません。細かいテクスチャアートを追加する前に UV を確認してください。静止ポーズのスクリーンショットだけでは、動きを検証できません。

ネイティブアーマチュア

実行中のフォーマットが armature_rig に対応している場合、ネイティブアーマチュアツール（list_armatures、get_armature、add_armature、list_armature_bones、get_armature_bone、add_armature_bone、および更新・削除操作）を確認します。ArmatureBones とグループベースの BoneAnimators は別の API です。一般的なアニメーションツールではグループを解決します。

既存のメッシュとアーマチュアについては、get_mesh_info で実行時の頂点キーを、get_vertex_weights: mesh_id="<UUID>" で現在のウェイトを確認します。set_vertex_weights_batch は bone_id、mesh_id、weights: { "<vertex key>": 0.5 } を受け取ります。ウェイトの範囲は 0～1 です。変更後は、すべての寄与ウェイトと関節部分の変形を確認します。1 つのボーンの値を設定しただけでは、リグ全体が適切にバインドされたり正規化されたりするわけではありません。スキン付きの実行時アセットを約束する前に、ネイティブリグがエクスポーターでサポートされているか確認してください。

Java の表示トランスフォーム

display_mode に対応するフォーマットの場合：

get_display_transform: slot="gui"
set_display_transform: slot="gui", rotation=[30, 225, 0], scale=[0.75, 0.75, 0.75]
enter_display_mode: slot="gui"
capture_screenshot

表示トランスフォームはエクスポートデータを変更します。対応するスロットを使って、依頼された手持ち、インベントリ、地面、またはフレームの各ビューを確認します。カメラの調整で、これらのトランスフォームが作成済みであるかのように見せないでください。

Bedrock ブロックのマテリアルインスタンス

bedrock_block では、get_face_material_instances で読み取り、set_face_material_instance でターゲットの minecraft:material_instances コンポーネントにマッピングされた名前を書き込みます。

get_face_material_instances: cube_id="block_geo"
set_face_material_instance: cube_id="block_geo", faces=["up"], material_name="top"

これらのツールは面の名前を割り当てますが、ビヘイビアパックのブロックコンポーネントやリソースパックのテクスチャ定義は作成しません。これらのマテリアルインスタンスは、PBR テクスチャグループや GPU インスタンシングとは別のものです。複数のマテリアルやカットアウトパネルについては、マテリアルインスタンスとテクスチャの配布に従ってください。繰り返しのジオメトリをテクスチャで置き換える場合は、事前に外観とパフォーマンスの計画を確認してください。エンティティでは、このブロックコンポーネントではなく、クライアントエンティティ／レンダーコントローラーのバインディングを使用します。ジオメトリのエクスポートと、付随するターゲット設定を確認してください。

復旧

save_checkpoint は履歴マーカーを挿入します。ファイルを保存したり、既存のやり直しブランチを保持したり、記録されていないスクリプトの変更を取り消し可能にしたりするものではありません。get_undo_stack でマーカーを特定し、実際のエントリー数を確認してから undo: steps=N を実行します。ペイントツールでは、複数のネイティブストロークが作成される場合があります。途中にあるユーザーの編集内容は保持してください。

これらの操作には trigger_action ではなく、専用の undo／redo を使用してください。直接実行する risky_eval スクリプトでは、変更に伴うネイティブの取り消し処理と、失敗時のクリーンアップを管理する必要があります。利用可能な専用ツールを優先し、セッションで定められている承認に従ってください。

エクスポート

list_export_formats
# Inspect available, has_compile, extension and belongs_to_current_format
export_model: codec_id="project", result_format="embedded"
export_model: codec_id="project", path="C:/models/robot.bbmodel", max_content_length=0

Blockbench を実行しているホスト上の、許可された出力先を使用してください。ファイルシステムの権限はホスト側で処理される場合があります。only_current_format=true はコーデックの一覧を絞り込みます。他に利用可能な互換エクスポート形式を確認するには、一覧全体を使用してください。

export_model はコーデックのコンパイル処理を呼び出します。コーデックの対話型エクスポートフローを自動実行したり、すべての外部画像を書き出したり、個別のアニメーションファイルをエクスポートしたりするものではありません。byte_length、出力パス、切り詰めの有無、返されたコンテンツ／リソースのメタデータを確認してください。切り詰められたテキスト／base64 のプレビューは、完全なダウンロード可能アセットではありません。埋め込み結果に完全なファイルが含まれるのは、応答の上限内に収まる場合のみです。

フォーマットと配布のガイダンスに従って、形式、依存関係、出力先を確認してください。可能であれば、コピーを再度開くか、出力先のアプリで確認し、検証上の制約を正確に報告してください。