O formato de arquivo de mapa

Cada mapa que você cria é salvo como um único arquivo de texto .json. O formato é pequeno, legível e totalmente seu: você pode abri-lo em qualquer editor de texto, mantê-lo sob controle de versão, fazer backup, gerá-lo a partir de um script ou movê-lo entre instâncias. Esta página descreve exatamente o que há dentro.

A estrutura de nível superior

Um arquivo de mapa é um único objeto JSON com três chaves: zones (sua paleta de cores), layers (os mapas em si, o mundo e quaisquer interiores) e layerOrder (a ordem em que as camadas são listadas). Na forma mais simples, ele se parece com isto:

{
  "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, a paleta

zones é um objeto que associa uma curta chave de zona (qualquer id em minúsculas que você escolher, p. ex. forest) à sua definição. As células se referem às zonas por essa chave, então renomear o nome visível de uma zona nunca quebra o mapa.

• name, o rótulo legível exibido na paleta (uma string).
• color, a cor de preenchimento como código hexadecimal, p. ex. "#3f8f4f".

Camadas, os mapas

layers associa um id de camada a uma camada. O mapa principal sempre usa o id world; camadas extras (masmorras, interiores de prédios, continentes separados) têm seus próprios ids. Cada camada é autossuficiente:

• name, o nome visível da camada (uma string, p. ex. "Dragon's Lair").
• tiles, as células pintadas (veja abaixo).
• labels, texto de nomes de lugares no mapa.
• markers, os ícones colocados no mapa.

Células, as casas pintadas

tiles associa uma coordenada de célula à zona pintada ali. A chave é a posição na grade escrita como "x_y" (coluna e depois linha, unidas por um sublinhado). Apenas as células pintadas são salvas, o espaço vazio não ocupa nada, então um mapa grande e quase vazio continua sendo um arquivo pequeno. Cada célula tem um único campo, z, a chave de zona da paleta acima.

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

Rótulos, nomes de lugares

labels associa um id (qualquer string única) a um rótulo de texto colocado no mapa. Cada rótulo tem uma posição na grade e seu texto:

• x, y, a célula da grade onde o rótulo fica (números).
• text, o texto do rótulo (uma string, até 200 caracteres).

Marcadores, ícones e entradas

markers associa um id a um ícone colocado no mapa. Um marcador também pode funcionar como entrada para outra camada, é assim que você liga o mundo a uma masmorra.

• x, y, a célula da grade onde o marcador fica (números).
• icon, o glifo do marcador, normalmente um emoji (uma string curta, até 16 caracteres).
• scale, o tamanho com que o ícone é desenhado (um número de 0.3 a 16; 1 é o tamanho padrão).
• link, opcional. O id de outra camada; clicar no marcador leva até essa camada. Omita-o para um marcador comum.

Ordem das camadas

layerOrder é uma lista de ids de camada que fixa a ordem em que as camadas aparecem. Ela sempre inclui "world". Qualquer camada que exista mas falte na lista é simplesmente adicionada ao fim quando o arquivo carrega, então não há problema se você esquecer alguma.

---

Exportar e importar

No seu painel de Mapas você pode Exportar qualquer mapa para baixá-lo como arquivo .json e Importar um arquivo .json para trazer um mapa. É a forma mais fácil de mover um mapa entre computadores, compartilhá-lo com um colega ou manter um backup externo.

• Uma importação nunca sobrescreve um mapa existente, se o nome já estiver em uso, o novo é trazido com um nome numerado (p. ex. my-world-2).
• Arquivos antigos de camada única que guardam tiles no nível superior (em vez de dentro de layers) ainda importam normalmente, são atualizados para uma camada world automaticamente.
• O arquivo exportado é exatamente o arquivo no disco, então copiar a pasta data/ inteira é um backup igualmente válido.

Um exemplo completo

Aqui está um mapa pequeno mas completo com duas camadas, um mundo cujo marcador de caverna leva a uma camada de masmorra:

{
  "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 você editar um arquivo à mão, mantenha-o como JSON válido (uma vírgula fora do lugar impedirá o carregamento) e faça uma cópia primeiro. Na dúvida, exporte um mapa real e use-o como modelo inicial.