Das Karten-Dateiformat

Jede Karte, die du erstellst, wird als eine einzige Klartext-.json-Datei gespeichert. Das Format ist klein, menschenlesbar und ganz deins: Du kannst es in jedem Texteditor öffnen, in die Versionsverwaltung legen, sichern, per Skript erzeugen oder zwischen Instanzen verschieben. Diese Seite beschreibt genau, was darin steht.

Der Aufbau auf oberster Ebene

Eine Kartendatei ist ein einzelnes JSON-Objekt mit drei Schlüsseln: zones (deine Farbpalette), layers (die Karten selbst, die Oberwelt und etwaige Innenräume) und layerOrder (die Reihenfolge, in der die Ebenen aufgelistet sind). In der einfachsten Form sieht es so aus:

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

Zonen, die Palette

zones ist ein Objekt, das einen kurzen Zonenschlüssel (eine beliebige Kleinbuchstaben-ID deiner Wahl, z. B. forest) seiner Definition zuordnet. Felder verweisen über diesen Schlüssel auf Zonen, daher bricht das Umbenennen des Anzeigenamens einer Zone die Karte nie.

• name, die lesbare Bezeichnung, die in der Palette angezeigt wird (eine Zeichenkette).
• color, die Füllfarbe als Hex-Code wie "#3f8f4f".

Ebenen, die Karten

layers ordnet einer Ebenen-ID eine Ebene zu. Die Hauptkarte nutzt immer die ID world; zusätzliche Ebenen (Verliese, Gebäudeinnenräume, eigene Kontinente) erhalten eigene IDs. Jede Ebene ist in sich abgeschlossen:

• name, der Anzeigename der Ebene (eine Zeichenkette, z. B. "Dragon's Lair").
• tiles, die gemalten Felder (siehe unten).
• labels, Ortsnamen-Text auf der Karte.
• markers, die auf die Karte gesetzten Symbole.

Felder, die gemalten Zellen

tiles ordnet einer Zellkoordinate die dort gemalte Zone zu. Der Schlüssel ist die Rasterposition, geschrieben als "x_y" (Spalte, dann Zeile, verbunden durch einen Unterstrich). Nur gemalte Felder werden gespeichert, leerer Raum belegt nichts, daher bleibt eine große, fast leere Karte eine kleine Datei. Jede Zelle hat ein einziges Feld, z, den Zonenschlüssel aus der Palette oben.

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

Beschriftungen, Ortsnamen

labels ordnet einer ID (eine beliebige eindeutige Zeichenkette) eine Textbeschriftung auf der Karte zu. Jede Beschriftung hat eine Rasterposition und ihren Text:

• x, y, die Rasterzelle, auf der die Beschriftung sitzt (Zahlen).
• text, der Beschriftungstext (eine Zeichenkette, bis zu 200 Zeichen).

Marker, Symbole und Eingänge

markers ordnet einer ID ein auf die Karte gesetztes Symbol zu. Ein Marker kann auch als Eingang in eine andere Ebene dienen, so verbindest du die Oberwelt mit einem Verlies.

• x, y, die Rasterzelle, auf der der Marker sitzt (Zahlen).
• icon, das Marker-Zeichen, meist ein Emoji (eine kurze Zeichenkette, bis zu 16 Zeichen).
• scale, wie groß das Symbol gezeichnet wird (eine Zahl von 0.3 bis 16; 1 ist die Standardgröße).
• link, optional. Die ID einer anderen Ebene; ein Klick auf den Marker führt zu dieser Ebene. Lass es weg für einen gewöhnlichen Marker.

Ebenenreihenfolge

layerOrder ist eine Liste von Ebenen-IDs, die die Reihenfolge festlegt, in der die Ebenen erscheinen. Sie enthält immer "world". Jede Ebene, die existiert, aber in der Liste fehlt, wird beim Laden der Datei einfach ans Ende gesetzt, es ist also unkritisch, wenn du eine vergisst.

---

Exportieren und importieren

In deinem Karten-Dashboard kannst du jede Karte exportieren, um sie als .json-Datei herunterzuladen, und eine .json-Datei importieren, um eine Karte einzufügen. Das ist der einfachste Weg, eine Karte zwischen Rechnern zu verschieben, sie mit einem Teammitglied zu teilen oder eine externe Sicherung aufzubewahren.

• Ein Import überschreibt nie eine vorhandene Karte, ist der Name bereits vergeben, wird die neue unter einem nummerierten Namen eingefügt (z. B. my-world-2).
• Ältere Ein-Ebenen-Dateien, die tiles auf oberster Ebene speichern (statt innerhalb von layers), lassen sich weiterhin problemlos importieren, sie werden automatisch zu einer world-Ebene aktualisiert.
• Die exportierte Datei ist genau die Datei auf der Festplatte, daher ist das Kopieren des gesamten data/-Ordners eine ebenso gültige Sicherung.

Ein vollständiges Beispiel

Hier ist eine kleine, aber vollständige Karte mit zwei Ebenen, eine Oberwelt, deren Höhlen-Marker in eine Verlies-Ebene führt:

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

Wenn du eine Datei von Hand bearbeitest, halte sie als gültiges JSON (ein falsch gesetztes Komma verhindert das Laden) und mache zuerst eine Kopie. Im Zweifel exportiere eine echte Karte und nutze sie als Ausgangsvorlage.