The map file format

Every map you make is stored as one plain-text .json file. The format is small, human-readable and entirely yours, you can open it in any text editor, keep it in version control, back it up, generate it from a script, or move it between instances. This page describes exactly what's inside.

You don't need any of this to use the app. Map Blueprint reads and writes these files for you. This reference is only for people who want to hand-edit a map, generate one from a tool, or understand exactly what gets exported. If you just want to draw maps, you can safely skip it.

The top-level shape

A map file is a single JSON object with three keys: zones (your colour palette), layers (the maps themselves, the overworld and any interiors), and layerOrder (the order layers are listed in). At its simplest it looks like this:

{
  "zones": {
    "forest": { "name": "Forest", "color": "#3f8f4f" },
    "water":  { "name": "Water", "color": "#3a6ea5" }
  },
  "layers": {
    "world": {
      "name": "Overworld",
      "tiles":   { "10_8": { "z": "forest" }, "11_8": { "z": "water" } },
      "labels":  { "L1": { "x": 10, "y": 8, "text": "Greenwood" } },
      "markers": { "M1": { "x": 11, "y": 8, "icon": "🏰", "scale": 1.5 } }
    }
  },
  "layerOrder": ["world"]
}

Zones, the palette

zones is an object that maps a short zone key (any lowercase id you choose, e.g. forest) to its definition. Tiles refer to zones by this key, so renaming a zone's display name never breaks the map.

name, the human-readable label shown in the palette (a string).
color, the fill colour as a hex code like "#3f8f4f".

Layers, the maps

layers maps a layer id to a layer. The main map always uses the id world; extra layers (dungeons, building interiors, separate continents) get their own ids. Each layer is self-contained:

name, the layer's display name (a string, e.g. "Dragon's Lair").
tiles, the painted cells (see below).
labels, place-name text on the map.
markers, the icons dropped on the map.

Tiles, the painted cells

tiles maps a cell coordinate to the zone painted there. The key is the grid position written as "x_y" (column, then row, joined by an underscore). Only painted cells are stored, empty space takes up nothing, so a big mostly-blank map stays a small file. Each cell holds a single field, z, the zone key from the palette above.

"tiles": {
  "45_44": { "z": "plains" },
  "46_44": { "z": "plains" },
  "46_45": { "z": "water" }
}

Labels, place names

labels maps an id (any unique string) to a text label placed on the map. Each label has a grid position and its text:

x, y, the grid cell the label sits on (numbers).
text, the label text (a string, up to 200 characters).

Markers, icons and entrances

markers maps an id to an icon dropped on the map. A marker can also act as an entrance into another layer, that's how you link the overworld to a dungeon.

x, y, the grid cell the marker sits on (numbers).
icon, the marker glyph, usually an emoji (a short string, up to 16 characters).
scale, how big the icon is drawn (a number from 0.3 to 16; 1 is the default size).
link, optional. The id of another layer; clicking the marker travels to that layer. Leave it out for an ordinary marker.

Layer order

layerOrder is a list of layer ids that fixes the order layers appear in. It always includes "world". Any layer that exists but is missing from the list is simply added to the end when the file loads, so it's safe if you forget one.

Exporting and importing

From your Maps dashboard you can Export any map to download it as a .json file, and Import a .json file to bring a map in. This is the easiest way to move a map between computers, share one with a teammate, or keep an off-site backup.

An import never overwrites an existing map, if the name is already taken, the new one is brought in under a numbered name (e.g. my-world-2).
Older single-layer files that store tiles at the top level (instead of inside layers) still import fine, they're upgraded to a world layer automatically.
The exported file is exactly the file on disk, so copying the whole data/ folder is an equally valid backup.

A complete example

Here's a small but complete map with two layers, an overworld whose cave marker links into a dungeon layer:

{
  "zones": {
    "water":   { "name": "Ocean", "color": "#2f5e94" },
    "plains":  { "name": "Plains", "color": "#9fc46a" },
    "forest":  { "name": "Forest", "color": "#3f8f4f" },
    "mountain":{ "name": "Mountain", "color": "#8a7560" },
    "dungeon": { "name": "Dungeon", "color": "#7a52b0" }
  },
  "layers": {
    "world": {
      "name": "Overworld",
      "tiles": {
        "20_14": { "z": "plains" },
        "21_14": { "z": "forest" },
        "22_14": { "z": "mountain" },
        "22_15": { "z": "water" }
      },
      "labels": {
        "L1": { "x": 20, "y": 14, "text": "Eldermoor" }
      },
      "markers": {
        "M1": { "x": 20, "y": 14, "icon": "🏯", "scale": 2.0 },
        "M2": { "x": 22, "y": 14, "icon": "🕳️", "scale": 1.4, "link": "lair" }
      }
    },
    "lair": {
      "name": "Drake's Lair",
      "tiles": {
        "10_10": { "z": "dungeon" },
        "11_10": { "z": "dungeon" },
        "11_11": { "z": "dungeon" }
      },
      "labels": {
        "D1": { "x": 10, "y": 10, "text": "Entrance Hall" }
      },
      "markers": {
        "D1": { "x": 11, "y": 11, "icon": "🐲", "scale": 2.2 }
      }
    }
  },
  "layerOrder": ["world", "lair"]
}

If you hand-edit a file, keep it valid JSON (a misplaced comma will stop it loading) and make a copy first. When in doubt, export a real map and use it as a starting template.