Map Blueprint

Stufe 2 · Fortgeschrittener Leitfaden

Die HTTP-API

Deine Instanz kann eine kleine HTTP-API bereitstellen, damit Skripte, Spiel-Engines und prozedurale Werkzeuge ganze Karten lesen und schreiben können, ganz ohne Browser. So lässt du Unity eine Karte erzeugen, sicherst Karten nach Zeitplan oder bearbeitest sie aus deiner eigenen Pipeline. Die Authentifizierung ist ein einzelnes Token, das du kontrollierst.

Optional: Zum Zeichnen von Karten brauchst du die API nicht. Die App funktioniert vollständig ohne sie. Aktiviere die API nur, wenn du Karten von außerhalb des Browsers automatisieren willst. Sie ist deaktiviert, bis du ein Token erstellst.

Die API aktivieren

Öffne Einstellungen, suche Automatisierungs-API und klicke Token erzeugen. Kopiere das Token an einen sicheren Ort: Es ist der Schlüssel zu deinen Karten. Du kannst es jederzeit neu erzeugen (was das alte sofort ungültig macht) oder die API ganz deaktivieren. Wenn du es lieber über die Umgebung setzt, gib API_TOKEN an, dann übernimmt es: Das Feld in den Einstellungen wird schreibgeschützt.

Authentifizierung

Jede Anfrage trägt dein Token im Authorization-Header. Anfragen ohne gültiges Token werden abgewiesen. Halte das Token geheim: Wer es hat, kann deine Karten lesen und überschreiben.

Authorization: Bearer YOUR_TOKEN

Basis-URL

Jeder Endpunkt liegt unter /api/v1 auf deiner eigenen Instanz, wo auch immer du sie betreibst (zum Beispiel http://localhost:8080 lokal, oder die Domain deines Servers). Die Beispiele unten verwenden https://your-instance.example.com als Platzhalter, ersetze ihn durch deine Adresse.

Endpunkte

Karten auflisten

GET /api/v1/maps

Liefert jede Karte der Instanz mit Dateigröße und Zeitpunkt der letzten Änderung.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps

Eine Karte lesen

GET /api/v1/maps/{name}

Liefert die vollständige Karte als JSON, in derselben Form wie bei einem Export. Speichere sie in einer Datei, lade sie in Unity oder vergleiche sie in der Versionsverwaltung.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps/world -o world.json

Eine Karte erstellen oder ersetzen

PUT /api/v1/maps/{name}

Lädt eine ganze Karte aus dem JSON-Body hoch. Ist die Karte neu, wird sie erstellt (201); existiert sie bereits, wird sie ersetzt (200). Wer diese Karte gerade im Browser bearbeitet, wird auf die neue Version neu geladen. So schreibt ein Generator, Unity oder ein prozedurales Werkzeug eine Karte zurück.

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data @world.json \
  https://your-instance.example.com/api/v1/maps/world

Eine Karte löschen

DELETE /api/v1/maps/{name}

Entfernt eine Karte dauerhaft. Es gibt kein Rückgängig, sichere sie also zuerst per Lesezugriff, falls du sie noch einmal brauchen könntest.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps/world

Umbenennen und duplizieren

POST /api/v1/maps/{name}/rename  ·  POST /api/v1/maps/{name}/duplicate

Benenne eine Karte um (sende { "to": "new-name" }) oder kopiere sie unter einem neuen Namen (sende { "to": "..." } oder lass es weg für einen automatischen -copy-Namen).

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"to":"old-world"}' \
  https://your-instance.example.com/api/v1/maps/world/rename

Der Karten-Body

Lesen und Schreiben verwenden genau dasselbe JSON wie ein Export: ein Objekt mit zones, layers und layerOrder. Siehe das Kartendateiformat für jedes Feld. Ein Schreibvorgang wird akzeptiert, solange er layers enthält (oder ein veraltetes tiles auf oberster Ebene).

Fehler und Statuscodes

Fehler liefern ein kleines JSON-Objekt wie { "error": "..." } mit einem passenden HTTP-Status:

Beispiel: aus Unity abrufen

Eine minimale C#-Coroutine, die eine Karte mit UnityWebRequest in Unity holt. Der Antworttext ist das vollständige Karten-JSON, bereit zum Parsen und Umwandeln in Terrain.

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

IEnumerator FetchMap(string baseUrl, string token, string name) {
    using var req = UnityWebRequest.Get($"{baseUrl}/api/v1/maps/{name}");
    req.SetRequestHeader("Authorization", "Bearer " + token);
    yield return req.SendWebRequest();
    if (req.result == UnityWebRequest.Result.Success)
        Debug.Log(req.downloadHandler.text);   // the full map JSON
    else
        Debug.LogError(req.responseCode + " " + req.error);
}

Behandle das Token wie ein Passwort: Halte es aus geteilten Repositorys und öffentlichen Builds heraus und erzeuge es neu, falls es je durchsickert. Da die API nur ganze Karten liest und schreibt, ist das sicherste Automatisierungsmuster: lesen, ändern, zurückschreiben.

← Zurück zur gesamten Dokumentation