# Blueprinter

> Turns a Minecraft build plan into named, reusable structure definitions saved inside the world, so build elements can be placed, copied, and iterated later without any external state. Use after planning, to create or update the structure library for a build. Part of the minecraft-builder workflow.

- Skill: `chapmanjw/blueprinter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chapmanjw/blueprinter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chapmanjw/blueprinter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: chapmanjw (https://skillmd.com/u/chapmanjw)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/chapmanjw/blueprinter

---


# Blueprinter

You create the **reusable structure library** for a build. A blueprint is a
named Minecraft structure file living in the world — once defined, it can be
stamped anywhere, copied, and re-saved. This is what lets a build be iterated
later with no memory outside the world.

## Connection

If an `mc_*` call fails because the MCP server is unreachable, stop and tell
the user to run the `minecraft-mcp-setup` agent.

## Inputs

- `.minecraft-builder/<project>/plan.toon` — its `blueprints` list names every
  reusable element you must define.
- `research.toon` — dimensions and materials, if a real reference is involved.
- The `mcbuilder:registry` world property — to see what structures already
  exist and whether you are creating or revising one.

## Naming

Name every structure **`mcb:<project>_<element>`** — lowercase, consistent,
project-scoped, with the **colon namespace**. This is the canonical form
across the whole plugin: in `plan.toon`, in `mcbuilder:registry`, and in
every `mc_structure_*` call.

The colon is required, not optional. `mc_structure_create_from_blocks` and
its sibling create tools **reject** underscore-only IDs (e.g.
`mcb:<project>_<element>`) with `invalid or missing namespace` and force a
plan-wide find/replace. Cape Aurelia hit this once and had to reconcile the
plan and registry together — don't repeat it.

## Create each blueprint

For every element in the plan's `blueprints` list:

1. **Decide the method:**
   - **Capture from the world** — if the element can be built in-world first,
     construct it once in a clear staging area (or at its final spot), then
     capture it with `mc_structure_create_from_world` over its exact bounds.
   - **Block by block** — for small or precise pieces, use
     `mc_structure_create_empty` and `mc_structure_set_block`.
   - **Generate a block grid** — if the element is easier to describe with a
     formula or script than to lay by hand (pixel-art murals, voxelized
     models, anything image-mapped or parametric), generate a run-length-encoded
     block grid and build it with `mc_structure_create_from_blocks`. See
     `reference/generated-structures.md`.
2. Build it from the plan's exact materials and dimensions.
3. Save it under the `mcb:<project>_<element>` name.
4. Verify with `mc_structure_get` / `mc_structure_list` that it saved with the
   expected size.

If you build prototypes in a staging area, clean them up afterward so the only
trace is the saved structure file.

## Iteration

To revise an existing blueprint: `mc_structure_place` it into a staging area,
edit the blocks, capture it again under the **same name** (bumping its
revision in the registry). Because the structure lives in the world, anyone in
a later session can do this — no project files needed.

## Register

Record every blueprint in the **`mcbuilder:registry`** world dynamic property
(TOON — see <https://toonformat.dev/>). Read the current value with
`mc_property_get`, add or update the structure's row, and write it back with
`mc_property_set`:

```toon
builds[1]{project,element,structure,x,y,z,status,revision}:
  lakeside-village,table-set,mcb:lakeside-village_table-set,0,0,0,blueprint,1
```

Use `status: blueprint` for a defined-but-not-yet-placed structure; the
`worker` updates it to `built` with real coordinates when it stamps it.

## Hand off

Report the structure names you created or revised and their sizes. The plan is
now ready for the `worker` to execute — every `place-structure` step in
`plan.toon` references a structure you have now defined.