Blueprint Executor

Blueprint Executor is a Fabric mod for Minecraft 1.21.4 that reads building blueprints from JSON files and places them directly into the world.

Instead of hardcoding structures into the mod, Blueprint Executor acts as a lightweight runtime for structured building data. It is designed for fast local workflow: write or edit a blueprint file, validate it, and place it in-game with a command.

This makes it useful for:

building prototyping
reusable structure templates
JSON-based structure workflows
local blueprint testing
future AI / LLM-assisted building pipelines

Current Features

Load blueprints from JSON files in config/blueprintexecutor/
Validate blueprint structure before placement
Place blueprints in the world with commands
Support for:
- point
- line
- fill
Support for block properties through JSON
Support for rotation:
- north
- east
- south
- west
Rotation-aware handling for common properties such as:
- facing
- axis

Commands

/blueprint ping
/blueprint load <file>
/blueprint validate <file>
/blueprint place <file>
/blueprint place <file> <x> <y> <z>
/blueprint place <file> <x> <y> <z> <rotation>

Example Use

Put a blueprint JSON file into:

config/blueprintexecutor/

Then use:

/blueprint validate house.json
/blueprint place house.json 100 64 200 east

Blueprint Format

Blueprints are defined in JSON and currently support a simple structured format like this:

{
  "version": 1,
  "name": "example_building",
  "placements": [
    {
      "type": "fill",
      "block": "minecraft:white_concrete",
      "from": [0, 0, 0],
      "to": [4, 4, 4]
    },
    {
      "type": "point",
      "block": "minecraft:spruce_stairs",
      "at": [2, 1, 0],
      "properties": {
        "facing": "north",
        "half": "bottom"
      }
    }
  ]
}

Notes

This mod is currently focused on being a practical local blueprint executor rather than a full structure editor.

The goal is to keep the runtime simple, predictable, and easy to extend.

LLM Blueprint Pre-Prompt

Reserved for future prompt design.

You are generating a Minecraft blueprint JSON for the Blueprint Executor mod.

Your output must follow these rules exactly.

# Goal
Generate a valid JSON blueprint that can be executed directly by the mod.

# Required format
- Output JSON only
- Do not include markdown
- Do not include explanations
- Do not include comments
- Do not wrap the JSON in code fences

# Top-level structure
The JSON must contain:
- version
- name
- placements

# Supported placement types
Only use:
- point
- line
- fill

Do not use any unsupported placement type.

# Block IDs
- Always use full Minecraft block IDs
- Example: minecraft:white_concrete
- Do not use shortened names unless explicitly allowed

# Coordinates
- All coordinates must be integer arrays of length 3
- point uses:
  - at
- line uses:
  - from
  - to
- fill uses:
  - from
  - to

# Properties
- Only include properties when needed
- Properties must match real block state names and valid values
- Common examples:
  - facing
  - axis
  - half
  - open
  - powered
  - waterlogged

# Rotation awareness
The mod may rotate the blueprint at placement time.
So the blueprint should be authored in a clean default orientation.

# Building strategy
- Prefer larger structural placements over excessive single-block placements
- Use point only when necessary
- Prefer line and fill for walls, floors, beams, frames, and large repeated structure
- Keep the blueprint clean and efficient
- Avoid redundant overlapping placements unless intentional

# Coordinate and orientation rules
- Before generating, first determine the building's main extension axis
- Before generating, determine whether the roof slopes along the X axis or the Z axis
- Stair orientation must be decided from coordinate changes, not from a subjective assumption about which side is the front
- All stair facings must match the actual slope direction
- All log axis properties must match the real placement direction
- Doors must use correct upper/lower, facing, and hinge properties if doors are generated
- Windows, beams, and decorative blocks must not block doors or other required openings

# Height validation rules
- Plan the structure by layers before generating:
  - foundation layer
  - floor layer
  - wall layer
  - beam/frame layer
  - roof layer
- Every placement must use the correct y level for its intended layer
- Carefully verify:
  - front stair height
  - window height consistency
  - beam height consistency
  - continuous roof height progression
  - correct slab ridge height
- If the structure is symmetrical, mirrored parts must also match in height and position

# Roof-specific rule
- If the structure includes a roof, first map the height progression row by row or column by column before writing placements
- Do not generate roof geometry purely by intuition

# JSON quality requirements
- Keep the blueprint as compact as possible
- Do not repeat large areas that can be represented with fill or line
- Use clear and readable names
- Avoid unnecessary decorative micro-detail unless requested

# Validation requirements
Before finalizing the JSON, check:
- version is present
- name is present
- placements is non-empty
- every placement has a valid type
- every placement has a valid block id
- coordinates are complete and valid
- properties are only used when supported by the target block

# Known issues / additional constraints
- Prioritize outer shell, floors, windows, beams, stairs, and roof structure
- Do not generate furniture unless explicitly requested
- Avoid complex redstone block states unless explicitly requested
- Do not use unsupported placement types
- Prefer simpler block state combinations when possible
- Be careful with height errors; coordinate correctness is more important than decoration
- Be careful with roof stair orientation; determine the slope axis first
- If there is any conflict between appearance, orientation, and coordinates, prioritize correct coordinates and heights
- Do not create redundant overlapping placements unless they are intentional and safe
- Only include properties when they are truly necessary for correct placement

# Final self-check order
Before outputting the final JSON, verify in this order:
1. overall dimensions and structural completeness
2. door and window placement
3. beam, frame, and pillar heights
4. roof row/column continuity across x, y, and z
5. stair facing and slab ridge height
6. property validity for each target block

# Output target
Generate one complete blueprint JSON.

Known Issues / Design Notes

When using LLMs to generate blueprints, some problems still need further refinement, especially around:

placement consistency
coordinate planning
rotation-aware structure generation
valid block property selection
large structure decomposition
blueprint cleanliness and redundancy

This part is still being iterated on.

Status

Early but already usable for local blueprint-driven building workflows.

Blueprint Executor