Il formato dei file di mappa

Ogni mappa che crei viene salvata come un unico file di testo .json. Il formato è piccolo, leggibile e completamente tuo: puoi aprirlo in qualsiasi editor di testo, metterlo sotto controllo di versione, farne il backup, generarlo da uno script o spostarlo tra istanze. Questa pagina descrive esattamente cosa contiene.

La struttura di primo livello

Un file di mappa è un singolo oggetto JSON con tre chiavi: zones (la tua tavolozza di colori), layers (le mappe vere e proprie, il mondo ed eventuali interni) e layerOrder (l'ordine in cui i livelli sono elencati). Nella forma più semplice appare così:

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

Zone, la tavolozza

zones è un oggetto che associa una breve chiave di zona (un id minuscolo a tua scelta, es. forest) alla sua definizione. Le caselle fanno riferimento alle zone tramite questa chiave, quindi rinominare il nome visibile di una zona non rompe mai la mappa.

• name, l'etichetta leggibile mostrata nella tavolozza (una stringa).
• color, il colore di riempimento come codice esadecimale, es. "#3f8f4f".

Livelli, le mappe

layers associa un id di livello a un livello. La mappa principale usa sempre l'id world; i livelli aggiuntivi (sotterranei, interni di edifici, continenti separati) hanno i propri id. Ogni livello è autonomo:

• name, il nome visibile del livello (una stringa, es. "Dragon's Lair").
• tiles, le caselle dipinte (vedi sotto).
• labels, il testo dei nomi di luogo sulla mappa.
• markers, le icone posizionate sulla mappa.

Caselle, le celle dipinte

tiles associa una coordinata di cella alla zona dipinta lì. La chiave è la posizione sulla griglia scritta come "x_y" (colonna, poi riga, unite da un trattino basso). Vengono salvate solo le caselle dipinte, lo spazio vuoto non occupa nulla, quindi una mappa grande e quasi vuota resta un file piccolo. Ogni cella ha un solo campo, z, la chiave di zona della tavolozza qui sopra.

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

Etichette, nomi di luogo

labels associa un id (una qualsiasi stringa univoca) a un'etichetta di testo posizionata sulla mappa. Ogni etichetta ha una posizione sulla griglia e il suo testo:

• x, y, la cella della griglia su cui si trova l'etichetta (numeri).
• text, il testo dell'etichetta (una stringa, fino a 200 caratteri).

Marcatori, icone ed entrate

markers associa un id a un'icona posizionata sulla mappa. Un marcatore può anche fungere da entrata verso un altro livello, è così che colleghi il mondo a un sotterraneo.

• x, y, la cella della griglia su cui si trova il marcatore (numeri).
• icon, il glifo del marcatore, di solito un emoji (una stringa breve, fino a 16 caratteri).
• scale, quanto grande viene disegnata l'icona (un numero da 0.3 a 16; 1 è la dimensione predefinita).
• link, opzionale. L'id di un altro livello; cliccando il marcatore si passa a quel livello. Omettilo per un marcatore normale.

Ordine dei livelli

layerOrder è un elenco di id di livello che fissa l'ordine in cui i livelli compaiono. Include sempre "world". Qualsiasi livello che esiste ma manca dall'elenco viene semplicemente aggiunto in fondo al caricamento del file, quindi non è un problema se ne dimentichi uno.

---

Esportare e importare

Dalla tua dashboard Mappe puoi Esportare qualsiasi mappa per scaricarla come file .json e Importare un file .json per aggiungere una mappa. È il modo più semplice per spostare una mappa tra computer, condividerla con un compagno di squadra o tenere un backup esterno.

• Un'importazione non sovrascrive mai una mappa esistente, se il nome è già in uso, la nuova viene aggiunta con un nome numerato (es. my-world-2).
• I vecchi file a livello singolo che memorizzano tiles al livello superiore (anziché dentro layers) si importano comunque bene, vengono aggiornati automaticamente a un livello world.
• Il file esportato è esattamente il file sul disco, quindi copiare l'intera cartella data/ è un backup altrettanto valido.

Un esempio completo

Ecco una mappa piccola ma completa con due livelli, un mondo il cui marcatore della grotta rimanda a un livello sotterraneo:

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

Se modifichi un file a mano, mantienilo come JSON valido (una virgola fuori posto ne impedirà il caricamento) e fai prima una copia. Nel dubbio, esporta una mappa reale e usala come modello di partenza.