Map Blueprint

Niveau 2 · Guide avancé

L'API HTTP

Votre instance peut exposer une petite API HTTP pour que les scripts, moteurs de jeu et outils procéduraux lisent et écrivent des cartes entières, sans navigateur. C'est ainsi que vous faites générer une carte par Unity, que vous sauvegardez des cartes selon un planning ou que vous les modifiez depuis votre propre pipeline. L'authentification est un unique jeton que vous contrôlez.

Facultatif : vous n'avez pas besoin de l'API pour dessiner des cartes. L'application fonctionne pleinement sans elle. N'activez l'API que lorsque vous voulez automatiser des cartes depuis l'extérieur du navigateur. Elle est désactivée jusqu'à ce que vous créiez un jeton.

Activer l'API

Ouvrez Paramètres, trouvez API d'automatisation et appuyez sur Générer un jeton. Copiez le jeton en lieu sûr : c'est la clé de vos cartes. Vous pouvez le régénérer à tout moment (ce qui invalide immédiatement l'ancien) ou désactiver entièrement l'API. Si vous préférez le définir depuis l'environnement, fournissez API_TOKEN et il prend le relais : le champ des Paramètres devient en lecture seule.

Authentification

Chaque requête porte votre jeton dans l'en-tête Authorization. Les requêtes sans jeton valide sont refusées. Gardez le jeton secret : quiconque le possède peut lire et écraser vos cartes.

Authorization: Bearer YOUR_TOKEN

URL de base

Chaque endpoint se trouve sous /api/v1 sur votre propre instance, où que vous l'exécutiez (par exemple http://localhost:8080 en local, ou le domaine de votre serveur). Les exemples ci-dessous utilisent https://your-instance.example.com comme substitut : remplacez-le par votre adresse.

Endpoints

Lister les cartes

GET /api/v1/maps

Renvoie toutes les cartes de l'instance avec leur taille de fichier et leur date de dernière modification.

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

Lire une carte

GET /api/v1/maps/{name}

Renvoie la carte complète en JSON, la même forme que celle d'un Export. Enregistrez-la dans un fichier, chargez-la dans Unity, ou comparez-la dans le contrôle de version.

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

Créer ou remplacer une carte

PUT /api/v1/maps/{name}

Téléverse une carte entière depuis le corps JSON. Si la carte est nouvelle, elle est créée (201) ; si elle existe déjà, elle est remplacée (200). Quiconque modifie cette carte dans un navigateur est rechargé sur la nouvelle version. C'est ainsi qu'un générateur, Unity ou un outil procédural réécrit une carte.

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

Supprimer une carte

DELETE /api/v1/maps/{name}

Supprime une carte définitivement. Il n'y a pas d'annulation, alors sauvegardez-la d'abord avec une lecture si vous pourriez la vouloir de nouveau.

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

Renommer et dupliquer

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

Renommez une carte (envoyez { "to": "new-name" }), ou copiez-la sous un nouveau nom (envoyez { "to": "..." }, ou omettez-le pour un nom -copy automatique).

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

Le corps de la carte

Les lectures et écritures utilisent exactement le même JSON qu'un Export : un objet avec zones, layers et layerOrder. Voir le format de fichier de carte pour chaque champ. Une écriture est acceptée tant qu'elle contient layers (ou un tiles hérité au niveau supérieur).

Erreurs et codes de statut

Les erreurs renvoient un petit objet JSON comme { "error": "..." } avec un statut HTTP correspondant :

Exemple : récupérer depuis Unity

Une coroutine C# minimale qui récupère une carte dans Unity avec UnityWebRequest. Le texte de la réponse est le JSON complet de la carte, prêt à être analysé et transformé en 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);
}

Traitez le jeton comme un mot de passe : gardez-le hors des dépôts partagés et des builds publics, et régénérez-le s'il fuit un jour. Comme l'API ne lit et n'écrit que des cartes entières, le schéma d'automatisation le plus sûr est lire, modifier, réécrire.

← Retour à toute la documentation