El formato de archivo de mapa

Cada mapa que creas se guarda como un único archivo de texto plano .json. El formato es pequeño, legible para humanos y totalmente tuyo: puedes abrirlo en cualquier editor de texto, guardarlo en control de versiones, hacer copias de seguridad, generarlo desde un script o moverlo entre instancias. Esta página describe exactamente lo que contiene.

La estructura de nivel superior

Un archivo de mapa es un único objeto JSON con tres claves: zones (tu paleta de colores), layers (los mapas en sí, el mundo y cualquier interior) y layerOrder (el orden en que se listan las capas). En su forma más simple se ve así:

{
  "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"]
}

Zonas, la paleta

zones es un objeto que asocia una breve clave de zona (cualquier id en minúsculas que elijas, p. ej. forest) con su definición. Las casillas se refieren a las zonas mediante esta clave, así que renombrar el nombre visible de una zona nunca rompe el mapa.

• name, la etiqueta legible que se muestra en la paleta (una cadena).
• color, el color de relleno como código hexadecimal, p. ej. "#3f8f4f".

Capas, los mapas

layers asocia un id de capa con una capa. El mapa principal siempre usa el id world; las capas adicionales (mazmorras, interiores de edificios, continentes aparte) tienen sus propios ids. Cada capa es autónoma:

• name, el nombre visible de la capa (una cadena, p. ej. "Dragon's Lair").
• tiles, las casillas pintadas (ver más abajo).
• labels, texto de nombres de lugar en el mapa.
• markers, los iconos colocados en el mapa.

Casillas, las celdas pintadas

tiles asocia una coordenada de celda con la zona pintada allí. La clave es la posición en la cuadrícula escrita como "x_y" (columna y luego fila, unidas por un guion bajo). Solo se guardan las celdas pintadas, el espacio vacío no ocupa nada, así que un mapa grande y casi vacío sigue siendo un archivo pequeño. Cada celda tiene un único campo, z, la clave de zona de la paleta anterior.

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

Etiquetas, nombres de lugar

labels asocia un id (cualquier cadena única) con una etiqueta de texto colocada en el mapa. Cada etiqueta tiene una posición en la cuadrícula y su texto:

• x, y, la celda de la cuadrícula donde está la etiqueta (números).
• text, el texto de la etiqueta (una cadena, hasta 200 caracteres).

Marcadores, iconos y entradas

markers asocia un id con un icono colocado en el mapa. Un marcador también puede actuar como entrada a otra capa, así es como conectas el mundo con una mazmorra.

• x, y, la celda de la cuadrícula donde está el marcador (números).
• icon, el glifo del marcador, normalmente un emoji (una cadena corta, hasta 16 caracteres).
• scale, el tamaño con que se dibuja el icono (un número de 0.3 a 16; 1 es el tamaño por defecto).
• link, opcional. El id de otra capa; al hacer clic en el marcador se viaja a esa capa. Omítelo para un marcador normal.

Orden de capas

layerOrder es una lista de ids de capa que fija el orden en que aparecen las capas. Siempre incluye "world". Cualquier capa que exista pero falte en la lista se añade simplemente al final al cargar el archivo, así que no pasa nada si olvidas alguna.

---

Exportar e importar

Desde tu panel de Mapas puedes Exportar cualquier mapa para descargarlo como archivo .json, e Importar un archivo .json para traer un mapa. Es la forma más fácil de mover un mapa entre ordenadores, compartirlo con un compañero o mantener una copia de seguridad externa.

• Una importación nunca sobrescribe un mapa existente, si el nombre ya está en uso, el nuevo se trae con un nombre numerado (p. ej. my-world-2).
• Los archivos antiguos de una sola capa que guardan tiles en el nivel superior (en lugar de dentro de layers) también se importan bien, se actualizan a una capa world automáticamente.
• El archivo exportado es exactamente el archivo del disco, así que copiar toda la carpeta data/ es una copia de seguridad igual de válida.

Un ejemplo completo

Aquí tienes un mapa pequeño pero completo con dos capas, un mundo cuyo marcador de cueva enlaza con una capa de mazmorra:

{
  "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"]
}

Si editas un archivo a mano, mantenlo como JSON válido (una coma mal puesta impedirá que cargue) y haz una copia primero. Ante la duda, exporta un mapa real y úsalo como plantilla de partida.