building-with-schematics

Building with Schematics

Why Schematics?

Schematics are the PREFERRED building method because:

• You describe WHAT to build, not HOW to execute commands
• Full block state support (facing, axis, half, etc.)
• COMPACT FORMAT saves ~70% tokens with run-length encoding
• Automatic rotation of entire builds
• Optimizes commands automatically

COMPACT FORMAT (Recommended)

Use this format for token efficiency:

{
  "a": [x, y, z],
  "p": {"S": "stone", "P": "oak_planks", ".": "air"},
  "l": [
    [0, "S*10|S P*8 S~8|S*10"]
  ]
}

Compact Syntax:

• Short keys: "a" (anchor), "p" (palette), "l" (layers), "f" (facing)
• Layers: [y_offset, "row|row|row"] - pipe separates rows
• Layer range: ["1-3", "pattern"] - same pattern at y=1, y=2, y=3 (great for walls!)
• Run-length: S*5 = 5 S blocks in a row
• Row repeat: S P*3 S~8 = repeat this row pattern 8 times

Compact Examples:

10x10 floor with border (verbose: ~500 tokens, compact: ~50 tokens):

{"a": [0,64,0], "p": {"S": "stone", "P": "planks"}, "l": [[0, "S*10|S P*8 S~8|S*10"]]}

5x5x4 hollow room (with layer range for walls):

{
  "a": [100, 64, 200],
  "p": {"W": "oak_planks", ".": "air"},
  "l": [
    [0, "W*5~5"],
    ["1-2", "W*5|W .*3 W~3|W*5"],
    [3, "W*5~5"]
  ]
}

Note: ["1-2", "..."] creates identical layers at y=1 AND y=2. Great for multi-story walls!

Verbose Format (Backward Compatible)

{
  "anchor": [x, y, z],
  "facing": "north",
  "mode": "replace",
  "palette": {"<symbol>": "<block>[states]{nbt}"},
  "layers": [
    {"y": 0, "grid": [["S","S"],["S","S"]]}
  ]
}

Grid Convention

        North (-Z)
           ^
    Row 0  |
    Row 1  |
    Row 2  v
        South (+Z)

    Col0 Col1 Col2
    <--- West    East --->
    (-X)         (+X)

• grid[row][col] = grid[z][x]
• Row 0 is the NORTH edge
• Column 0 is the WEST edge
• Rows increase going SOUTH
• Columns increase going EAST