Blueprint Data

File location and ID

Place one definition in:

data/<namespace>/blueprints/<path>.json

Its ID is <namespace>:<path>. Subdirectories are preserved. index.json is ignored.

The root may be an object or a one-element array. Zero-entry and multi-entry arrays are rejected.

Complete example

{
  "key": {
    "W": { "item": "minecraft:oak_planks", "count": 4 },
    "I": { "item": "minecraft:iron_ingot", "count": 2 }
  },
  "result": {
    "item": "example:machine_spawner",
    "count": 1,
    "custom_data": { "Variant": 2 },
    "deployment": {
      "mode": "ground",
      "preview_entity": "example:machine"
    }
  },
  "construction": [
    {
      "section": "frame",
      "materials": [{ "key": "W", "count": 4 }],
      "hits": 8
    },
    {
      "section": "mechanism",
      "key": "I",
      "hits": 4
    }
  ]
}

key

Each entry names one material. Keys must be one character, but they are identifiers rather than drawing-grid symbols.

"W": {
  "item": "minecraft:oak_planks",
  "count": 4
}

item must be a registered item ID. count defaults to 1 and must be at least 1.

For direct blueprints, all key entries are consumed on use. For field construction, stages allocate the entries and drawing quality adjusts their totals.

result

Field	Required	Meaning
item	yes	Registered result item ID
count	no	Result stack size; defaults to 1
custom_data	no	Integer custom-data entries written to the result
deployment	no	Enables placement in the world

Without deployment, the blueprint directly crafts the result.

deployment

"deployment": {
  "mode": "ground",
  "preview_entity": "example:machine"
}

mode is ground or water and defaults to ground. Water deployment requires preview_entity. Ground deployment may infer an entity from the result item ID, but an explicit entity ID is safer and is required when the names do not match.

The current staged-construction runtime deploys entities. A deployed entity should implement UnderConstruction; otherwise it is placed already finished.

construction

Construction stages run in array order. Every usable stage needs a non-empty section name.

Choose one material form per stage:

Form	Meaning
"key": "W"	Consume the complete W ingredient
"keys": ["W", "I"]	Consume both ingredients in full
"materials": [{"key":"W","count":2}]	Consume explicit shares

materials takes precedence over keys, which takes precedence over key. A material count of 0 or an omitted count means the complete ingredient count.

hits is optional. A positive value sets base work for the stage. Otherwise work is derived from allocated item count and the server config. Drawing quality then adjusts the hit count.

Across all stages, each key should be allocated exactly once and totals should match the ingredient count. Mismatches and unknown keys are logged. A deployed blueprint without usable stages falls back to one minimum-work stage with no materials.

Reloading

Definitions are server data. Run /reload after changing a data pack. The validated catalog is synchronized to clients.