jasonjgardner/blockbench-mcp-project/blockbench-modeling

Blockbench Modeling

Build 3D models using cubes and meshes in Blockbench.

Plan the Shape and Target

Before a new model or substantial geometry redesign, resolve the user's appearance/accuracy, performance, or balanced preference through Blockbench use. Follow appearance and performance planning to set a working element/face budget and choose which details belong in geometry, UV tiles, or PBR. Prototype and count one repeated section before multiplying it; braces, infills, foot plates, and fasteners should not automatically become separate cubes.

Spend faces on silhouette, parallax, and deformation. Delete faces no required view or pose reveals, since real-time meshes need not be watertight. Let parts intersect instead of stitching edge loops around the joint, and float thin detail planes instead of cutting detail in. Keep geometry for recesses and openings whose depth must change as the camera moves. See real-time asset planning sections 4–6 for per-target budgets and face-removal rules.

Use format and delivery guidance when selecting a format or exporting. Block out the silhouette and proportions before UV layout and surface detail. Match polygon density to visible shape or deformation needs; automatic subdivision is not a quality step by itself.

For articulated parts, create a hierarchy with pivots at joints and unique, consistent bone names. Group origins are pivots, not translations added to a cube's from/to coordinates. Place cube bounds in the model's rest coordinate space; the hierarchy applies rotations around those pivots. Mesh vertices are mesh-local, as described below. Check overlapping surfaces for z-fighting and preview moving parts for hidden gaps. See the official modeling overview.

When resizing or duplicating textured geometry at a different size, re-evaluate the face UV spans rather than blindly retaining the source rectangle. Follow UV scale and distortion guidance for side/end proportions, final scale transforms, and shared-material density. Correct mapping within the chosen geometry budget; additional cubes are not the default remedy for texture stretching.

Available Tools

Cube Tools

Mesh Tools

Element Tools

Cube Modeling

place_cube supports untextured blockout in the current source plugin; use get_capabilities: include_tools=true to identify the loaded build. A new texture can be created after the silhouette is established. Supplying a texture or group requires a valid existing reference. Use returned UUIDs for later edits; the literal group="root" or add_group's parent="root" means outliner root. Name a real root bone rig_root, or use its UUID, to avoid that reserved target.

Place a Cube

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 Multiple Cubes

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

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

Cube with Texture

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

Bedrock Poles, Cylinders, and Tubes

For round primitives in Bedrock cube models, read Bedrock primitive construction. It derives polygon side widths and shared-pivot rotations for solid and hollow shapes, following the Shape Generator plugin's octagon and 16-sided constructions. Choose facets within the appearance/performance budget, distinguish flat-to-flat from corner diameter, and verify overlapping end faces and UV scale. create_cylinder creates a mesh; use calculated place_cube batches when the target requires cubes.

Mesh Modeling

Check get_capabilities before creating meshes. Use a registered format with format.features.meshes=true, normally free (Generic Model).

Create a Mesh and Retain Its IDs

The JavaScript examples below are client orchestration pseudocode: call(name, args) invokes that MCP tool and checks for isError. For JSON results, it returns structuredContent or the decoded JSON text; for plain-text results, it returns the text unchanged. It is not code for risky_eval. Variables such as panel.uuid and panel.face_keys[0] must be replaced with their returned values in actual tool arguments, never sent as literal strings.

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: [...]}

Input faces use zero-based vertex indices. Returned vertex_keys and face_keys follow input order and hold the actual runtime keys. Later selection, face creation, and UV tools need those keys. A mesh name or UUID identifies the mesh, not its vertices or faces. Retain the UUID to avoid ambiguous names. After topology edits or undo/redo, inspect again before reusing component keys.

Inspect Geometry and Read Every Page

For primitives or existing meshes, obtain keys with get_mesh_info. Vertex items contain {key, position, selected}; face items contain {key, vertices, normal, selected, texture}. Positions, bounds, and normals are mesh-local, before origin, rotation, and parent transforms.

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));
}

Each list has its own next_offset; null means complete. The default limit is 100, maximum 500 per list. Finish paging before mutating geometry because keys are sorted and edits can invalidate offsets. Inspection is read-only and does not select components.

Create Sphere

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

Create Cylinder

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

Extrude Face

For the unrotated, capped cylinder created above, select all cap triangles facing local +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});

Subdivide for Detail

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

Move Vertices

Continue from the panel creation example, before changing its topology:

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 Close Vertices

merge_mesh_vertices: mesh_id="panel", threshold=0.1

Knife Cut

The mesh Knife tool depends on interactive pointer state, so knife_tool returns an unsupported-operation error for point lists. For a scripted mesh cut, inspect with get_mesh_info, construct the intended replacement vertices/faces with place_mesh, verify them, then replace the original geometry within the user's requested scope. Use Blockbench's interactive Knife tool when the user prefers to cut manually.

Cubes can be cut headlessly. knife_cut_cube mirrors Blockbench's Knife on cubes: each cut plane is perpendicular to one axis, the original keeps the lower piece, new pieces get unique names (pole_2, pole_3), and face UVs are shared proportionally. One undo entry covers all cuts.

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

Oversized Bedrock Blocks

A Bedrock custom block's geometry must fit a 30×30×30 box whose center may sit at most 7 units from the block center, which Blockbench enforces as x/z within ±22 and y within -14…30 (Microsoft's page states the limit more loosely: https://learn.microsoft.com/minecraft/creator/documents/customblockoversized). Larger models must be divided into per-block sections.

1. inspect_block_bounds reports model, group, and cube extents against those limits, the block cell each cube sits in, and the grid cut positions that would split it.
2. slice_cubes_to_block_grid cuts every cube where it crosses a block boundary (x/z boundaries at ±8, ±24, …; y at 0, 16, 32, …) and, by default, moves the pieces into one group per block cell (bottom, top, right_top_front, top2, …) pivoted at that block's origin. Cubes rotated about the other two axes are left uncut and listed in skipped_rotated.
3. Export each cell group as its own block geometry, or slice manually with knife_cut_cube when the automatic grid is not what the model needs.

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

Organization

Create Group Hierarchy