Map Blueprint

Livello 2 · Guida avanzata

L'API HTTP

La tua istanza può esporre una piccola API HTTP così che script, motori di gioco e strumenti procedurali possano leggere e scrivere mappe intere, senza bisogno di un browser. È così che fai generare una mappa a Unity, esegui backup delle mappe con una pianificazione o le modifichi dalla tua pipeline. L'autenticazione è un singolo token che controlli tu.

Facoltativo: non ti serve l'API per disegnare le mappe. L'app funziona pienamente senza. Attiva l'API solo quando vuoi automatizzare le mappe dall'esterno del browser. È disattivata finché non crei un token.

Attivare l'API

Apri Impostazioni, trova API di automazione e premi Genera token. Copia il token in un posto sicuro: è la chiave delle tue mappe. Puoi rigenerarlo in qualsiasi momento (il che invalida subito quello vecchio) o disattivare del tutto l'API. Se preferisci impostarlo dall'ambiente, fornisci API_TOKEN e prende il sopravvento: il campo nelle Impostazioni diventa di sola lettura.

Autenticazione

Ogni richiesta porta il tuo token nell'intestazione Authorization. Le richieste senza un token valido vengono rifiutate. Tieni segreto il token: chiunque lo possieda può leggere e sovrascrivere le tue mappe.

Authorization: Bearer YOUR_TOKEN

URL di base

Ogni endpoint si trova sotto /api/v1 sulla tua istanza, ovunque la esegui (ad esempio http://localhost:8080 in locale, o il dominio del tuo server). Gli esempi qui sotto usano https://your-instance.example.com come segnaposto: sostituiscilo con il tuo indirizzo.

Endpoint

Elencare le mappe

GET /api/v1/maps

Restituisce tutte le mappe dell'istanza con la loro dimensione del file e la data di ultima modifica.

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

Leggere una mappa

GET /api/v1/maps/{name}

Restituisce la mappa completa come JSON, la stessa forma che ottieni da un'Esportazione. Salvala in un file, caricala in Unity o confrontala nel controllo di versione.

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

Creare o sostituire una mappa

PUT /api/v1/maps/{name}

Carica una mappa intera dal corpo JSON. Se la mappa è nuova viene creata (201); se esiste già viene sostituita (200). Chiunque stia modificando quella mappa in un browser viene ricaricato sulla versione nuova. È così che un generatore, Unity o uno strumento procedurale riscrive una mappa.

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

Eliminare una mappa

DELETE /api/v1/maps/{name}

Rimuove una mappa in modo permanente. Non c'è annullamento, quindi salvala prima con una lettura se potresti rivolerla.

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

Rinominare e duplicare

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

Rinomina una mappa (invia { "to": "new-name" }), o copiala con un nuovo nome (invia { "to": "..." }, oppure omettilo per un nome -copy automatico).

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

Il corpo della mappa

Letture e scritture usano esattamente lo stesso JSON di un'Esportazione: un oggetto con zones, layers e layerOrder. Vedi il formato del file di mappa per ogni campo. Una scrittura è accettata finché contiene layers (o un tiles legacy di primo livello).

Errori e codici di stato

Gli errori restituiscono un piccolo oggetto JSON come { "error": "..." } con uno stato HTTP corrispondente:

Esempio: recuperare da Unity

Una coroutine C# minima che porta una mappa in Unity con UnityWebRequest. Il testo della risposta è il JSON completo della mappa, pronto per essere analizzato e trasformato in terreno.

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);
}

Tratta il token come una password: tienilo fuori dai repository condivisi e dalle build pubbliche, e rigeneralo se dovesse mai trapelare. Poiché l'API legge e scrive solo mappe intere, lo schema di automazione più sicuro è leggere, modificare, riscrivere.

← Torna a tutta la documentazione