Blueprint File Format#

Specification version 2

This page documents the on-disk JSON format BentoBox uses for island blueprints (.blueprint files) and blueprint bundles (bundle .json files). It is the human-readable companion to the machine-readable JSON Schemas shipped in the BentoBox repository, which can be used to validate files in editors or CI.

If you want to make blueprints in game, see the Blueprints page. This page is for developers and power users who generate, edit, or validate blueprint files directly.

Revision history#

File types#

Both kinds of file live in a game mode addon's blueprints/ folder, e.g. plugins/BentoBox/addons/BSkyBlock/blueprints/. A bundle references its blueprints by name, and the referenced .blueprint files must sit in the same folder.

Serialization rules#

Blueprints are written with Gson. These rules apply throughout and explain the shapes you will see below:

• Only the fields listed in this specification are emitted; producers must not add other keys.
• Vectors (org.bukkit.util.Vector) are a 3-element JSON array of numbers: [x, y, z]. Block positions customarily hold integers, but the underlying type is double.
• Maps keyed by a Vector use Gson's complex-map-key form: a JSON array of pairs — [[<vector>, <value>], ...] — not a JSON object. This applies to blocks, attached, and entities.
• Maps keyed by an enum (e.g. a bundle's blueprints map) are ordinary JSON objects with the enum name as the key.
• Maps keyed by an integer (inventory slot → item) are JSON objects with stringified integer keys ("0", "13", …).
• ItemStacks are serialized to Bukkit YAML (via ConfigurationSerializable) and stored as a JSON string. Treat the value as an opaque YAML document parseable by YamlConfiguration#loadFromString.
• Enums are serialized by their Java name().
• Colors (org.bukkit.Color) are serialized as {"ALPHA": int, "RED": int, "GREEN": int, "BLUE": int}.
• Files are pretty-printed by the writer; consumers must not rely on whitespace.
• All field names are case sensitive.

Blueprint#

The top-level object of a .blueprint file. It describes a block volume, attached blocks, and entities relative to an anchor (bedrock).

A minimal example:

{
  "name": "island",
  "displayName": "&aStarter island",
  "icon": "GRASS_BLOCK",
  "description": ["A tiny island"],
  "bedrock": [2.0, 1.0, 2.0],
  "xSize": 5, "ySize": 3, "zSize": 5,
  "blocks": [
    [[2.0, 1.0, 2.0], {"blockData": "minecraft:bedrock"}],
    [[2.0, 2.0, 2.0], {"blockData": "minecraft:grass_block[snowy=false]"}]
  ],
  "attached": [
    [[2.0, 3.0, 2.0], {"blockData": "minecraft:oak_sign[rotation=0,waterlogged=false]", "signLines": ["[spawn_here]", "", "", ""]}]
  ],
  "entities": [
    [[1.0, 2.0, 1.0], [{"type": "COW", "adult": true}]]
  ]
}

BlueprintBlock#

One block cell. Only blockData is required; every other field is applied only when the block type supports it.

BlueprintCreatureSpawner#

Vanilla (non-trial) mob spawner configuration.

BlueprintTrialSpawner#

Trial spawner configuration (Minecraft 1.21+). Use spawnedType or potentialSpawns, not both.

BlueprintEntity#

One entity to spawn. Only type is required. Unset fields mean "leave the Bukkit default alone"; each field is applied only when the entity class supports it.

General

Mobs

Plugin integrations (only meaningful when the plugin is installed)

Display entities and item frames

TextDisplay payload fields: text (legacy § codes accepted), alignment (CENTER/LEFT/RIGHT), bgColor (Color object), face (a BlockFace name), lWidth (line-wrap width in pixels), opacity (signed byte, −1 = default), isShadowed, isSeeThrough, isDefaultBg.

DisplayRec#

BlueprintBundle#

A bundle groups up to three blueprints — one per world environment — into a single option in the island-creation UI, and controls that option's cost, permission, GUI slot, usage cap, and post-creation commands. Persisted as <uniqueId>.json in the game mode's blueprints/ folder; the filename stem must equal uniqueId.

Example default.json:

{
  "uniqueId": "default",
  "displayName": "Default Island",
  "icon": "GRASS_BLOCK",
  "description": ["A standard island", "with grass and dirt"],
  "blueprints": {
    "NORMAL": "island",
    "NETHER": "nether",
    "THE_END": "end"
  },
  "requirePermission": false,
  "slot": 0,
  "times": 0,
  "cost": 0.0,
  "commands": ["[SUDO] me has arrived!"]
}

Validating files#

The BentoBox repository publishes two JSON Schemas (draft 2020-12):

• schemas/blueprint.schema.json — validates a .blueprint file or a bundle
• schemas/blueprint-bundle.schema.json — validates a bundle file on its own

Point your editor or CI validator at them, e.g. with ajv:

ajv validate --spec=draft2020 -s blueprint.schema.json -d island.blueprint

Note that YAML-encoded ItemStack strings and a few Bukkit ConfigurationSerializable objects (transformations, spawn rules) are opaque to the schema — a schema-valid file can still fail to load if those embedded documents are malformed.