BLOCKFORGE BUILD SPEC

A reference for AI agents designing builds for BlockForge voxel worlds

OVERVIEW

BlockForge is an on-chain voxel world on Bitcoin. Each chunk is 32x64x32 blocks. Players can export their builds as JSON and inscribe them as child inscriptions. This spec describes the JSON format so that AI agents can generate valid build files.

The generated JSON can be pasted directly into the game via Chunk Options > Import Chunk JSON, or inscribed on-chain as a child of the chunk's parent inscription.

COORDINATE SYSTEM

• X: 0-31 (east/west within chunk)
• Y: 0-63 (height, 0 = bedrock, cannot be modified)
• Z: 0-31 (north/south within chunk)

All coordinates in the a (additions) and r (removals) arrays are local to the chunk (0-31 for X/Z, 1-63 for Y).

JSON FORMAT

Single Chunk Edit

{
  "t": "edit",
  "cx": 0,
  "cz": 0,
  "op": "erase_floor",
  "floorY": 10,
  "a": [
    [5, 11, 5, "stone"],
    [5, 12, 5, "glass"],
    [6, 11, 5, "brick"]
  ],
  "r": [
    [10, 15, 10]
  ],
  "signs": {
    "5,12,5": { "text": "Hello World", "author": "Builder" }
  },
  "tx": [],
  "author": "MyName"
}

Multi-Chunk Edit (Mega Chunks)

{
  "t": "multi-edit",
  "chunks": [
    { "cx": 0, "cz": 0, "op": "erase_floor", "floorY": 10, "a": [...] },
    { "cx": 1, "cz": 0, "a": [...], "r": [...] }
  ],
  "tx": [],
  "author": "MyName"
}

FIELD REFERENCE

CHUNK OPERATIONS

Operations are applied BEFORE additions. This lets you clear a chunk and then place your build on a clean canvas.

No operation (diff mode)

If op is omitted, the build is applied as a diff on top of the existing procedural terrain. Use a to add blocks and r to remove them.

erase

Clears all blocks above bedrock (Y=1 to Y=63). Only air remains. Then a additions are applied. Good for building in empty space.

{ "t": "edit", "cx": 0, "cz": 0, "op": "erase", "a": [...] }

erase_floor

Clears all blocks, then places a single floor layer at the specified Y level using biome-appropriate materials. This is the most common operation for builds.

{ "t": "edit", "cx": 0, "cz": 0, "op": "erase_floor", "floorY": 10, "a": [...] }

reset

Regenerates the original procedural terrain, then applies additions on top. Useful for undoing all changes and starting fresh with terrain.

{ "t": "edit", "cx": 0, "cz": 0, "op": "reset", "a": [...] }

BLOCK TYPES

Blocks are referenced by lowercase name in the a array. Here are all 90+ built-in blocks (state-managed variants of two-state blocks are shown for completeness, but you usually only need the base variant):

Terrain & Natural

Building Materials

Stained Glass

Emissive / Glowing

Bitcoin-Themed

Cyberpunk Biome

Other Biome Blocks

Special

Interactive (v1.9)

Functional blocks that react to player input or modify physics. State-managed variants (open doors, active beacons, etc.) can be placed directly via JSON to start in any state.

CUSTOM TEXTURES

You can reference Bitcoin inscription images as block textures using the tx array:

{
  "tx": [
    { "iid": "abc123...i0", "name": "my_texture" }
  ],
  "a": [
    [5, 11, 5, "my_texture"]
  ]
}

The inscription ID must point to a valid image inscription on Bitcoin. The game will fetch and render it as a block texture.

DECORATIONS (GLB MODELS & PAINTINGS)

Two optional top-level arrays attach rich media to a build. Their coordinates are local to the chunk (0-31 X/Z, 1-63 Y), the same convention as a. Both are captured when a chunk is exported/inscribed, so a build round-trips with its models and paintings intact.

gcases — GLB Display Cases

Each entry mounts an on-chain 3D model (a GLB or glTF model/* inscription) inside a bounded display case. Also place a glb case block (ID 125) at the same coordinate in a — that block is the physical anchor.

{
  "a": [ [15, 11, 15, "glb case"] ],
  "gcases": [
    { "x": 15, "y": 11, "z": 15, "iid": "abc...i0", "size": 5, "spin": 0 }
  ]
}

paintings — image murals

Each entry mounts an image inscription across a grid of painting cell blocks (ID 123). Place the cells in a across the wall area, then add one paintings entry anchored at the correct cell.

{
  "a": [ /* painting cell blocks filling a 3x3 area on a wall */ ],
  "paintings": [
    { "x": 15, "y": 12, "z": 5, "iid": "abc...i0", "size": 3, "facing": [0, 1] }
  ]
}

EXAMPLES

Simple Tower on Cleared Ground

{
  "t": "edit",
  "cx": 0, "cz": 0,
  "op": "erase_floor",
  "floorY": 10,
  "a": [
    [15, 11, 15, "stone"], [16, 11, 15, "stone"], [15, 11, 16, "stone"], [16, 11, 16, "stone"],
    [15, 12, 15, "stone"], [16, 12, 15, "stone"], [15, 12, 16, "stone"], [16, 12, 16, "stone"],
    [15, 13, 15, "stone"], [16, 13, 15, "stone"], [15, 13, 16, "stone"], [16, 13, 16, "stone"],
    [15, 14, 15, "stone"], [16, 14, 15, "stone"], [15, 14, 16, "stone"], [16, 14, 16, "stone"],
    [15, 15, 15, "lantern"]
  ]
}

Add Blocks to Existing Terrain (No Clear)

{
  "t": "edit",
  "cx": 2, "cz": -1,
  "a": [
    [10, 20, 10, "brick"], [11, 20, 10, "brick"], [12, 20, 10, "brick"],
    [10, 21, 10, "glass"], [11, 21, 10, "glass"], [12, 21, 10, "glass"]
  ],
  "r": [
    [10, 19, 10], [11, 19, 10]
  ]
}

Bitcoin Shrine

{
  "t": "edit",
  "cx": 0, "cz": 0,
  "op": "erase_floor",
  "floorY": 10,
  "a": [
    [14,11,14,"obsidian"],[15,11,14,"obsidian"],[16,11,14,"obsidian"],[17,11,14,"obsidian"],
    [14,11,17,"obsidian"],[15,11,17,"obsidian"],[16,11,17,"obsidian"],[17,11,17,"obsidian"],
    [14,11,15,"obsidian"],[14,11,16,"obsidian"],[17,11,15,"obsidian"],[17,11,16,"obsidian"],
    [14,12,14,"obsidian"],[17,12,14,"obsidian"],[14,12,17,"obsidian"],[17,12,17,"obsidian"],
    [14,13,14,"obsidian"],[17,13,14,"obsidian"],[14,13,17,"obsidian"],[17,13,17,"obsidian"],
    [15,13,14,"obsidian"],[16,13,14,"obsidian"],[15,13,17,"obsidian"],[16,13,17,"obsidian"],
    [14,13,15,"obsidian"],[14,13,16,"obsidian"],[17,13,15,"obsidian"],[17,13,16,"obsidian"],
    [15,13,15,"obsidian"],[16,13,15,"obsidian"],[15,13,16,"obsidian"],[16,13,16,"obsidian"],
    [15,14,15,"bitcoin"],[16,14,15,"bitcoin"],[15,14,16,"bitcoin"],[16,14,16,"bitcoin"],
    [15,15,15,"energy core"],[16,15,16,"energy core"],
    [14,11,13,"lantern"],[17,11,13,"lantern"],[14,11,18,"lantern"],[17,11,18,"lantern"]
  ]
}

TIPS FOR AI AGENTS

• Use "op": "erase_floor" with "floorY": 10 for a clean building surface
• The chunk is 32 wide (X: 0-31) and 32 deep (Z: 0-31). Center your builds around X=15, Z=15
• Maximum build height is Y=63. Most builds start around Y=11 (one above a floor at Y=10)
• Use lantern blocks for lighting. They emit actual point lights in the game
• Use emissive blocks (neon panel, crystal, energy core) for glowing accents
• Use stained glass for colored transparent surfaces
• Block names are case-insensitive in the additions array
• Keep builds under ~5,000 blocks for reasonable file sizes
• Signs support multi-line text. The key format is "x,y,z" using local chunk coordinates

BlockForge by MDV · blockforgebtc.com