blockbench-modeling

Blockbench モデリング

Blockbench でキューブとメッシュを使って 3D モデルを作成します。

形状と目標を計画する

新しいモデルを作成する前、またはジオメトリを大幅に再設計する前に、Blockbench の使い方を参照して、見た目と精度、パフォーマンス、またはそのバランスに関するユーザーの希望を確認します。見た目とパフォーマンスの計画に従って、要素数と面数の目安を設定し、ジオメトリ、UV タイル、PBR のどれに各ディテールを割り当てるかを決めます。同じ部分を複製する前に、まず 1 つを試作して数を確認します。補強材、充填材、ベースプレート、留め具を、安易にそれぞれ別のキューブにしてはいけません。

シルエット、視差、変形に面数を使います。リアルタイムメッシュは水密である必要がないため、必要な視点やポーズから見えない面は削除します。接合部のエッジループをつなぐ代わりにパーツを交差させ、ディテールを彫り込むのではなく、薄いディテール面を浮かせて配置します。カメラの移動に応じて奥行きが変わる必要があるくぼみや開口部には、ジオメトリを使います。対象ごとの予算と面の削除ルールについては、リアルタイムアセットの計画のセクション 4～6 を参照してください。

フォーマットの選択やエクスポートには、フォーマットと納品に関するガイダンスを使用します。UV レイアウトや表面のディテールより先に、シルエットとプロポーションを大まかに作ります。ポリゴン密度は、見た目の形状や変形の要件に合わせます。自動サブディビジョンだけでは、品質向上になりません。

関節のあるパーツでは、関節位置にピボットを置いた階層構造を作成し、一意で一貫性のあるボーン名を付けます。グループの原点はピボットであり、キューブの from／to 座標に加算される移動量ではありません。キューブの境界はモデルのレスト座標空間に配置し、階層構造によってそれらのピボットを中心に回転させます。メッシュ頂点は、以下で説明するようにメッシュローカルです。重なり合う面に Z ファイティングがないか確認し、パーツを動かして、隠れていた隙間がないかプレビューします。公式のモデリング概要を参照してください。

テクスチャ付きジオメトリのサイズを変更したり、異なるサイズで複製したりする場合は、元の矩形をそのまま使わず、面の UV 範囲を再評価します。側面と端面の比率、最終的なスケール変換、共有マテリアルの密度については、UV スケールと歪みに関するガイダンスに従います。選択したジオメトリ予算の範囲内でマッピングを調整します。テクスチャの引き伸ばしを直すためにキューブを追加するのは、基本的な解決策ではありません。

使用可能なツール

キューブツール

ツール	用途
place_cube	位置、サイズ、テクスチャを指定してキューブを作成します
modify_cube	キューブのプロパティ（位置、回転、UV など）を編集します
get_cube_uv / set_cube_uv	ボックス UV または面ごとのキューブ UV を確認／編集します。テクスチャリングスキルを参照してください

メッシュツール

ツール	用途
place_mesh	インデックス付きの面を持つメッシュを作成します。UUID とランタイムジオメトリキーを返します
get_mesh_info	メッシュローカルの位置、面、法線、選択状態、テクスチャ、任意の UV を確認します
create_sphere	球体メッシュを作成します
create_cylinder	円柱メッシュを作成します
extrude_mesh	選択した面領域を押し出します。エッジモードと頂点モードには対応していません
subdivide_mesh	選択した三角形／四角形をサブディバイドし、各辺を cuts + 1 個のセグメントに分割します
select_mesh_elements	頂点／エッジ／面を選択します
move_mesh_vertices	選択した頂点を移動します
delete_mesh_elements	ジオメトリを削除します
merge_mesh_vertices	近接する頂点を結合します
create_mesh_face	頂点から面を作成します
knife_tool	MCP 経由でのメッシュのポイントリスト切断には対応していません
knife_cut_cube	キューブ用のヘッドレス Knife ツールです。1 つの軸に沿った位置で分割します
slice_cubes_to_block_grid	Bedrock のブロック境界でキューブを切断し、ブロックごとに再グループ化します
inspect_block_bounds	キューブ／グループが 30×30×30 の大型ブロック制限内に収まっているか確認します

要素ツール

ツール	目的
add_group	ボーン／グループを作成
list_outline	モデルの階層を表示
duplicate_element	要素を複製
rename_element	要素の名前を変更
remove_element	要素を削除
find_elements_by_criteria	名前のパターン、タイプ、親、サイズで要素を検索
select_all_of_type	キューブ、メッシュ、グループを一括選択
filter_by_material	テクスチャを参照する要素を検索

キューブモデリング

現在のソースプラグインでは、place_cube はテクスチャなしのブロックアウトに対応しています。読み込まれたビルドを確認するには、get_capabilities: include_tools=true を使用してください。シルエットが確定した後で、新しいテクスチャを作成できます。テクスチャまたはグループを指定するには、有効な既存の参照が必要です。以降の編集では、返された UUID を使用してください。リテラルの group="root" または add_group の parent="root" は、アウトライナーのルートを意味します。予約されたターゲットを避けるには、実際のルートボーンに rig_root という名前を付けるか、その UUID を使用してください。

キューブを配置する

place_cube: elements=[{
  name: "body",
  from: [-4, 0, -2],
  to: [4, 12, 2]
}], faces=true  # Size-based Auto UV; this does not pack a texture atlas

複数のキューブを配置する

place_cube: elements=[
  {name: "head", from: [-4, 12, -4], to: [4, 20, 4]},
  {name: "arm_left", from: [4, 4, -1], to: [6, 12, 1]},
  {name: "arm_right", from: [-6, 4, -1], to: [-4, 12, 1]}
], group="body"

キューブを変更する

modify_cube: id="body", rotation=[0, 45, 0], origin=[0, 6, 0]

テクスチャ付きキューブ

place_cube: elements=[{name: "block", from: [0,0,0], to: [16,16,16]}],
  texture="stone", faces=true

Bedrock のポール、円柱、チューブ

Bedrock のキューブモデルで丸いプリミティブを作成するには、Bedrock プリミティブの構築を参照してください。Shape Generator プラグインの八角形および16面の構築方法に従い、中実および中空の形状について、ポリゴンの辺幅と共有ピボット回転を算出します。外観とパフォーマンスの予算に合わせて面数を選び、辺間の直径と頂点間の直径を区別し、端面の重なりと UV スケールを確認してください。create_cylinder はメッシュを作成します。対象がキューブを必要とする場合は、計算した place_cube のバッチを使用してください。

メッシュモデリング

メッシュを作成する前に get_capabilities を確認してください。format.features.meshes=true を備えた登録済みフォーマットを使用します。通常は free（Generic Model）です。

メッシュを作成して ID を保持する

以下の JavaScript の例は、クライアントでのオーケストレーションを示す疑似コードです。call(name, args) は該当する MCP ツールを呼び出し、isError を確認します。JSON の結果では structuredContent またはデコード済みの JSON テキストを返し、プレーンテキストの結果ではテキストをそのまま返します。これは risky_eval 用のコードではありません。panel.uuid や panel.face_keys[0] などの変数は、実際のツール引数では返された値に置き換える必要があり、リテラル文字列として送信してはいけません。

const placed = await call("place_mesh", {
  elements: [{
    name: "panel",
    vertices: [[0, 0, 0], [4, 0, 0], [4, 4, 0], [0, 4, 0]],
    faces: [[0, 1, 2, 3]],
  }],
});
const panel = placed.meshes[0];
// panel: {name, uuid, vertex_keys: [...], face_keys: [...]}

入力面では、頂点のインデックスをゼロから数えます。返される vertex_keys と face_keys は入力順に並び、実際のランタイムキーを保持します。後続の選択、面の作成、UV ツールでは、これらのキーが必要です。メッシュ名または UUID が識別するのはメッシュであり、頂点や面ではありません。名前が曖昧になるのを避けるため、UUID を保持してください。トポロジーの編集後、または取り消し／やり直しの後は、コンポーネントキーを再利用する前に再度確認してください。

ジオメトリを調べ、すべてのページを読み取る

プリミティブまたは既存のメッシュのキーを取得するには、get_mesh_info を使用してください。頂点項目には {key, position, selected} が、面項目には {key, vertices, normal, selected, texture} が含まれます。位置、境界、法線は、原点、回転、親のトランスフォームを適用する前の、メッシュローカルの値です。

async function readMeshPages(meshId, part, offset = 0) {
  // part is "vertices" or "faces". Read one list independently.
  const info = await call("get_mesh_info", {
    mesh_id: meshId,
    include_vertices: part === "vertices",
    include_faces: part === "faces",
    [part === "vertices" ? "vertex_offset" : "face_offset"]: offset,
    limit: 500,
  });
  const page = info[part];
  if (page.next_offset === null) return page.items;
  return page.items.concat(await readMeshPages(meshId, part, page.next_offset));
}

各リストには独自の next_offset があり、null は読み取り完了を意味します。デフォルトの上限は100で、リストごとの最大値は500です。キーはソートされており、編集によってオフセットが無効になる場合があるため、ジオメトリを変更する前にページをすべて読み終えてください。確認操作は読み取り専用で、コンポーネントを選択しません。

球体を作成する

create_sphere: elements=[{
  name: "ball",
  position: [0, 8, 0],
  diameter: 16,
  sides: 12
}]

円柱を作成する

create_cylinder: elements=[{
  name: "pillar",
  position: [0, 0, 0],
  diameter: 8,
  height: 24,
  sides: 12,
  capped: true
}]

面を押し出す

上で作成した、回転していないキャップ付き円柱について、ローカル +Y を向くすべてのキャップ三角形を選択します。

const pillarFaces = await readMeshPages("pillar", "faces");
const capKeys = pillarFaces.filter(face => face.normal[1] > 0.99).map(face => face.key);
if (capKeys.length === 0) throw new Error("No upward cap faces found; inspect the mesh.");
await call("select_mesh_elements", {mesh_id: "pillar", mode: "face", elements: capKeys});
await call("extrude_mesh", {mesh_id: "pillar", mode: "faces", distance: 4});

細部を追加するために細分化する

select_mesh_elements: mesh_id="ball", mode="face"  # Select all faces explicitly
subdivide_mesh: mesh_id="ball", cuts=2

頂点を移動する

トポロジーを変更する前に、panel の作成例から続けてください。

await call("select_mesh_elements", {
  mesh_id: panel.uuid, mode: "vertex", elements: panel.vertex_keys.slice(2, 4),
});
await call("move_mesh_vertices", {mesh_id: panel.uuid, offset: [0, 2, 0]});

近接する頂点を結合する

merge_mesh_vertices: mesh_id="panel", threshold=0.1

ナイフカット

メッシュのナイフツールはインタラクティブなポインターの状態に依存するため、knife_tool にポイントリストを渡すと、未対応の操作エラーが返されます。スクリプトでメッシュをカットする場合は、get_mesh_info で確認し、place_mesh で意図した置き換え用の頂点と面を作成して検証したうえで、ユーザーが指定した範囲内で元のジオメトリを置き換えてください。ユーザーが手動でのカットを希望する場合は、Blockbench のインタラクティブなナイフツールを使用してください。

キューブはヘッドレスでカットできます。knife_cut_cube はキューブに対する Blockbench のナイフツールと同様に動作します。各カット面は一つの軸に対して垂直で、元のキューブには下側のピースが残り、新しいピースには一意の名前（pole_2、pole_3）が付けられ、面の UV は比率を保って共有されます。すべてのカットは一つの取り消しエントリにまとめられます。

knife_cut_cube({ cubes: ["pole"], axis: "y", positions: [16, 32, 48] })

Bedrock の大きすぎるブロック

Bedrock のカスタムブロックのジオメトリは、中心がブロックの中心から最大 7 ユニットまでの位置にある 30×30×30 のボックスに収まる必要があります。Blockbench ではこれを x/z が ±22 以内、y が -14…30 の範囲として適用しています（Microsoft のページでは、より大まかな制限として記載されています：https://learn.microsoft.com/minecraft/creator/documents/customblockoversized）。これより大きなモデルは、ブロックごとのセクションに分割する必要があります。

1. inspect_block_bounds は、モデル、グループ、キューブの範囲をこれらの制限と照合して報告します。また、各キューブが配置されるブロックのセルと、分割位置となるグリッドのカット位置も報告します。
2. slice_cubes_to_block_grid は、ブロック境界をまたぐ位置ですべてのキューブをカットします（x/z の境界は ±8、±24、…、y の境界は 0、16、32、…）。また、デフォルトでは各ピースをブロックセルごとに一つのグループ（bottom、top、right_top_front、top2、…）へ移動し、各グループのピボットをそのブロックの原点に設定します。他の 2 軸を中心に回転したキューブはカットせず、skipped_rotated に一覧表示します。
3. 各セルグループを個別のブロックジオメトリとしてエクスポートするか、自動グリッドがモデルに適さない場合は knife_cut_cube で手動でスライスしてください。

inspect_block_bounds({})
slice_cubes_to_block_grid({ regroup: true, group_prefix: "goal_" })

構成

グループ階層を作成する

add_group: name="rig_root", origin=[0, 0, 0], rotation=[0, 0, 0]
add_group: name="body", parent="rig_root", origin=[0, 12, 0]
add_group: name="head", parent="body", origin=[0, 24, 0]

グループにキューブを追加する

place_cube: elements=[{name: "torso", from: [-4, 12, -2], to: [4, 24, 2]}],
  group="body"

要素を複製する

duplicate_element: id="arm_left", newName="arm_right", offset=[-8, 0, 0]

階層を表示する

list_outline  # Returns all groups and elements

選択とフィルタリング

アウトライン全体を読み込まずにモデルを検索できます。select_all_of_type を除き、これらのツールは読み取り専用です。

条件で要素を検索する

正規表現による名前の照合、部分文字列による照合、種類、親グループの範囲、キューブのサイズ範囲、選択範囲を組み合わせられます。

# All cubes under "body" named like "arm_*"
find_elements_by_criteria: type="cube", parent_group="body", name_pattern="^arm_"

# Small cubes (under 4 units on any axis) in the currently selected elements
find_elements_by_criteria: selected_only=true, max_size=[4, 4, 4]

# Groups whose name contains "hand" (case-insensitive)
find_elements_by_criteria: type="group", name_contains="hand"

{ count, truncated, matches: [{ uuid, name, type, parent }] } を返します。

種類を指定してすべて選択する

# Replace selection with every cube in the project
select_all_of_type: type="cube"

# Add all meshes under "head" to the current selection
select_all_of_type: type="mesh", parent_group="head", add_to_selection=true

マテリアルでフィルタリングする

特定のテクスチャを参照するキューブまたはメッシュをすべて検索します。キューブの場合は、正確な面のキーが返されます。

filter_by_material: texture="skin"
# → { texture, count, matches: [{ uuid, name, type: "cube", faces: ["north", "up"] }] }

テクスチャをリファクタリングする際に便利です。テクスチャを差し替えたり廃止したりする前に、使用箇所をすべて検索できます。

よく使うパターン

Minecraft のキャラクター

この例では、ボーンリグを備えたキューブ形式と、高さ 32 ユニットのレストポーズを想定しています。プレイヤースキンのテンプレートを指定するものではありません。キューブの境界にはキャラクター内での位置がすでに含まれているため、グループのピボットによって位置が変わることはありません。

# Create hierarchy
add_group: name="rig_root", origin=[0, 0, 0]
add_group: name="body", parent="rig_root", origin=[0, 24, 0]
add_group: name="head", parent="body", origin=[0, 24, 0]
add_group: name="arm_left", parent="body", origin=[5, 22, 0]
add_group: name="arm_right", parent="body", origin=[-5, 22, 0]
add_group: name="leg_left", parent="rig_root", origin=[2, 12, 0]
add_group: name="leg_right", parent="rig_root", origin=[-2, 12, 0]

# Add geometry
place_cube: elements=[{name: "head_geo", from: [-4, 24, -4], to: [4, 32, 4]}], group="head"
place_cube: elements=[{name: "body_geo", from: [-4, 12, -2], to: [4, 24, 2]}], group="body"
place_cube: elements=[{name: "arm_left_geo", from: [4, 12, -1], to: [6, 22, 1]}], group="arm_left"
place_cube: elements=[{name: "arm_right_geo", from: [-6, 12, -1], to: [-4, 22, 1]}], group="arm_right"
place_cube: elements=[{name: "leg_left_geo", from: [0, 0, -2], to: [4, 12, 2]}], group="leg_left"
place_cube: elements=[{name: "leg_right_geo", from: [-4, 0, -2], to: [0, 12, 2]}], group="leg_right"

滑らかな有機形状

要求された形状に追加の頂点が必要な場合にのみ細分化してください。細分化によってトポロジーは増えますが、それだけでシルエットが滑らかになるわけではありません。

await call("create_sphere", {
  elements: [{name: "base", position: [0, 8, 0], diameter: 16, sides: 16}],
});
await call("select_mesh_elements", {mesh_id: "base", mode: "face"});
await call("subdivide_mesh", {mesh_id: "base", cuts: 1});
const vertices = await readMeshPages("base", "vertices");
const upperKeys = vertices.filter(vertex => vertex.position[1] > 0).map(vertex => vertex.key);
await call("move_mesh_vertices", {mesh_id: "base", offset: [0, 4, 0], vertices: upperKeys});

この述語はローカル Y を使用するため、原点がワールド Y=8 にあっても、> 0 はこの球体の上半分を選択します。他の形状では、確認したジオメトリに適した述語を使用してください。

ヒント

• 現在のモデル構造を確認するには、list_outline を使用します
• 対象を絞った検索には、list_outline の結果をクライアント側でフィルタリングする代わりに find_elements_by_criteria を使用します
• アニメーションでは、関節やピボットの位置にグループの原点を設定します
• サイズベースのキューブ UV には faces=true を使用し、細かく描画する前に UV を確認して配置します
• ジオメトリを追加する前に、ボーン階層を作成します
• オフセットを指定した duplicate_element は、移動したコピーを作成します。形状や UV レイアウトをミラーリングするものではありません
• メッシュ編集はより柔軟ですが、Minecraft 風のモデルではキューブのほうがシンプルです
• 大幅な作り直しでは、save_checkpoint の履歴マーカーが復旧に役立ちます。undo の前に、実際の履歴エントリを確認してください