Map Blueprint

Nivel 2 · Guía avanzada

La API HTTP

Tu instancia puede exponer una pequeña API HTTP para que scripts, motores de juego y herramientas procedurales lean y escriban mapas completos, sin necesidad de navegador. Así es como haces que Unity genere un mapa, respaldas mapas de forma programada o los editas desde tu propia canalización. La autenticación es un único token que tú controlas.

Opcional: no necesitas la API para dibujar mapas. La aplicación funciona por completo sin ella. Activa la API solo cuando quieras automatizar mapas desde fuera del navegador. Está desactivada hasta que creas un token.

Activar la API

Abre Configuración, busca API de automatización y pulsa Generar token. Copia el token en un lugar seguro: es la llave de tus mapas. Puedes regenerarlo en cualquier momento (lo que invalida al instante el anterior) o desactivar la API por completo. Si prefieres definirlo desde el entorno, proporciona API_TOKEN y tomará el control: el campo de Configuración pasa a ser de solo lectura.

Autenticación

Cada solicitud lleva tu token en la cabecera Authorization. Las solicitudes sin un token válido se rechazan. Mantén el token en secreto: cualquiera que lo tenga puede leer y sobrescribir tus mapas.

Authorization: Bearer YOUR_TOKEN

URL base

Cada endpoint vive bajo /api/v1 en tu propia instancia, dondequiera que la ejecutes (por ejemplo http://localhost:8080 en local, o el dominio de tu servidor). Los ejemplos siguientes usan https://your-instance.example.com como marcador: reemplázalo por tu dirección.

Endpoints

Listar mapas

GET /api/v1/maps

Devuelve todos los mapas de la instancia con su tamaño de archivo y su fecha de última modificación.

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

Leer un mapa

GET /api/v1/maps/{name}

Devuelve el mapa completo como JSON, con la misma forma que obtienes de una Exportación. Guárdalo en un archivo, cárgalo en Unity o compáralo en el control de versiones.

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

Crear o reemplazar un mapa

PUT /api/v1/maps/{name}

Sube un mapa completo desde el cuerpo JSON. Si el mapa es nuevo se crea (201); si ya existe se reemplaza (200). Cualquiera que esté editando ese mapa en un navegador se recarga con la versión nueva. Así es como un generador, Unity o una herramienta procedural vuelve a escribir un mapa.

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

Eliminar un mapa

DELETE /api/v1/maps/{name}

Elimina un mapa de forma permanente. No hay deshacer, así que haz una copia primero con una lectura si podrías quererlo de nuevo.

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

Renombrar y duplicar

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

Renombra un mapa (envía { "to": "new-name" }) o cópialo con un nombre nuevo (envía { "to": "..." }, u omítelo para un nombre -copy automático).

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

El cuerpo del mapa

Las lecturas y escrituras usan exactamente el mismo JSON que una Exportación: un objeto con zones, layers y layerOrder. Consulta el formato de archivo de mapa para cada campo. Una escritura se acepta siempre que contenga layers (o un tiles heredado de nivel superior).

Errores y códigos de estado

Los errores devuelven un pequeño objeto JSON como { "error": "..." } con un estado HTTP correspondiente:

Ejemplo: obtener desde Unity

Una corrutina de C# mínima que trae un mapa a Unity con UnityWebRequest. El texto de la respuesta es el JSON completo del mapa, listo para analizar y convertir en 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);
}

Trata el token como una contraseña: mantenlo fuera de repositorios compartidos y compilaciones públicas, y regéneralo si alguna vez se filtra. Como la API solo lee y escribe mapas completos, el patrón de automatización más seguro es leer, modificar, volver a escribir.

← Volver a toda la documentación