Pi Blockbench Skills

Create realistic, vivid, and repeatable Minecraft Blockbench models with Pi.

• Source code
• Report issues

Install

Requirements

• Pi
• Blockbench Desktop
• The official Blockbench MCP plugin
• The Pi MCP client extension

Bun is only needed to work on this repository and run its tests. End users do not need Bun to install this Pi package.

Install the Pi package

pi install npm:@dexer_matters/pi-blockbench
pi install npm:pi-mcp-extension

Pi packages are ordinary npm packages. This package declares its skills/ directory through the pi manifest and includes the pi-package keyword for Pi package discovery.

Install the Blockbench plugin

In Blockbench, open File → Plugins → Load Plugin from URL and install:

https://jasonjgardner.github.io/blockbench-mcp-plugin/mcp.js

The plugin URL is upstream mutable code. Verify its source and version under your organization’s plugin policy before loading it; this package does not provide an integrity pin.

Connect Pi to Blockbench

Configure Pi in .pi/mcp.json for one project or ~/.pi/agent/mcp.json for all projects:

{
  "mcpServers": {
    "blockbench": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:3000/bb-mcp",
      "lifecycle": "eager",
      "requestTimeoutMs": 120000
    }
  }
}

Start Pi and run /mcp to check the connection. Keep the MCP server bound to 127.0.0.1; its risky_eval tool can execute JavaScript in Blockbench.

Why use this package?

Compared to the MCP plugin alone, we provide a structured authoring method that makes modelling more deliberate and much faster to iterate:

• Less modelling time. Pi creates a complete procedural model in a small number of script runs instead of repeatedly placing and correcting individual cubes. Later geometry changes edit model.js and rerun the dependent texture phase.

• Less texture time. A canonical atlas, alpha-preserving paint pass, palette helpers, and deterministic texture detail handle the repetitive work. You spend time choosing materials, lighting, and visual direction instead of hand-painting every pixel.

• Glow-mask readiness. Any glow, emissive, or emitting-light request creates an atlas-aligned <model_name>_glowmask texture with transparent non-emissive pixels and RGBA brightness/color control; the separate asset is ready for an emissive material or resource-pack pipeline.

• Less animation time. Animation is opt-in, generated in animation.js, and built from reusable sampled motion helpers. Position and rotation tracks are additive; scale tracks use positive multiplicative factors around [1, 1, 1]. Loop endpoints, tick-grid timing, animated scaling, and animated overlaps are checked before the result is accepted.

• Better results from smaller models. The saved scripts and shared runtime carry scale conversion, geometry rules, texture conventions, and validation. A cheaper model has less state to rediscover on every revision and can make bounded changes to an existing source file.

• Elegant Minecraft geometry. Cubes earn their cost through mass, depth, occlusion, or articulation. Thin silhouettes use plates, openings use transparent mask pixels, and painted details stay in textures. The model does not become noisy just to look complex.

• Minecraft-native aesthetics. The workflow favors readable silhouettes, purposeful stepped masses, coherent material regions, directional light, clustered voxel detail, and restrained contrast. It keeps the grid visible instead of imitating smooth-rendered meshes with unnecessary geometry.

• Repeatable iteration. The saved scripts are the source of truth. Geometry, appearance, and explicitly requested motion can be revised independently without losing the design logic.

The goal is not maximum object count. It is the clearest result with the fewest meaningful parts: volume where the eye needs volume, texture where the eye needs material, and animation only where motion improves the design.

First model

Ask Pi for a model and state whether animation is wanted. For example:

Create a medium-sized Minecraft lantern with a solid metal frame,
glass panels, a warm procedural texture, and no animation.

The skill will:

1. Confirm the MCP connection and select or create a compatible project.
2. Derive a lowercase snake_case model_name from the request; if none is supplied, creatively make one out of the prompt.
3. Save model.js and texture.js under blockbench-scripts/<model_name>/.
4. Add animation.js only when you explicitly request motion.
5. Execute the scripts in order through Blockbench.
6. Read back the generated elements and textures and capture a preview.
7. Save <model_name>.bbmodel, <model_name>.png, optional <model_name>_glowmask.png, and—only for an explicitly animated model—<model_name>.animation.json.

Static models are the default; animation is created only when explicitly requested.

The saved scripts are the source of truth. A geometry change reruns model.js and then texture.js; an appearance change normally reruns only texture.js; an explicitly requested motion change reruns animation.js.

What the skill enforces

• One Minecraft block equals 16 Blockbench units.
• Cuboid spans, masks, UVs, and texture pixels stay on the integral voxel grid.
• Thin silhouettes and perforated surfaces use real zero-thickness plates with transparent mask holes.
• Paint-only details stay in textures instead of becoming unnecessary geometry.
• Rotated attachments carry explicit placement and angle reasoning.
• Static models do not receive invented animations.
• Model, texture, and animation scripts validate their own overlaps, alpha behavior, loop closure, and positive interpolated scale values before reporting success.
• Generated names are succinct lowercase snake_case: groups group_<group_id>, cubes cube_<cube_id>, animations <model_name>_animation_<animation_id>, diffuse texture <model_name>, and optional glowmask <model_name>_glowmask; no generated name uses the bbpi: prefix.
• Semantic anatomy groups use exact local names head, body, and tail when present; omit absent anatomy rather than creating placeholder groups.
• Local IDs match ^[a-z0-9]+(?:_[a-z0-9]+)*$ without reserved object keys, group parents are acyclic, and reruns remain lifecycle-scoped through the model's diffuse texture.
• Every animation track targets an existing group, and duplicate (bone, channel) tracks are rejected before keyframes mutate the project.

Read the complete authoring contract in skills/blockbench-script/SKILL.md.

When something fails

• No MCP connection: install the Blockbench plugin above, check .pi/mcp.json or ~/.pi/agent/mcp.json, then run /mcp.
• risky_eval unavailable: the official plugin is missing or has not been reloaded; do not silently fall back to per-cube construction.
• Script error after mutation: caught build, animation, and texture-finalization failures close their runtime edit but do not roll back partial state; inspect the live project with read-only MCP tools before retrying or using undo.
• Unexpected model output: edit the saved script rather than issuing a large series of corrective cube calls.