Map Blueprint

Nível 2 · Guia avançado

A API HTTP

Sua instância pode expor uma pequena API HTTP para que scripts, motores de jogo e ferramentas procedurais leiam e gravem mapas inteiros, sem precisar de navegador. É assim que você faz o Unity gerar um mapa, faz backup de mapas de forma agendada ou os edita a partir do seu próprio pipeline. A autenticação é um único token que você controla.

Opcional: você não precisa da API para desenhar mapas. O app funciona por completo sem ela. Ative a API apenas quando quiser automatizar mapas de fora do navegador. Ela fica desativada até você criar um token.

Ativar a API

Abra Configurações, encontre API de automação e clique em Gerar token. Copie o token para um lugar seguro: é a chave dos seus mapas. Você pode regerá-lo a qualquer momento (o que invalida imediatamente o antigo) ou desativar a API por completo. Se preferir defini-lo pelo ambiente, forneça API_TOKEN e ele assume: o campo em Configurações fica somente leitura.

Autenticação

Cada solicitação leva seu token no cabeçalho Authorization. Solicitações sem um token válido são recusadas. Mantenha o token em segredo: qualquer pessoa que o tenha pode ler e sobrescrever seus mapas.

Authorization: Bearer YOUR_TOKEN

URL base

Cada endpoint fica sob /api/v1 na sua própria instância, onde quer que você a execute (por exemplo http://localhost:8080 localmente, ou o domínio do seu servidor). Os exemplos abaixo usam https://your-instance.example.com como marcador: substitua pelo seu endereço.

Endpoints

Listar mapas

GET /api/v1/maps

Retorna todos os mapas da instância com o tamanho do arquivo e a data da última modificação.

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

Ler um mapa

GET /api/v1/maps/{name}

Retorna o mapa completo como JSON, o mesmo formato que você obtém de uma Exportação. Salve-o em um arquivo, carregue-o no Unity ou compare-o no controle de versão.

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

Criar ou substituir um mapa

PUT /api/v1/maps/{name}

Envia um mapa inteiro a partir do corpo JSON. Se o mapa for novo, ele é criado (201); se já existir, é substituído (200). Quem estiver editando esse mapa em um navegador é recarregado na versão nova. É assim que um gerador, o Unity ou uma ferramenta procedural grava um mapa de volta.

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

Excluir um mapa

DELETE /api/v1/maps/{name}

Remove um mapa permanentemente. Não há desfazer, então faça um backup primeiro com uma leitura se puder querê-lo de novo.

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

Renomear e duplicar

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

Renomeie um mapa (envie { "to": "new-name" }), ou copie-o com um novo nome (envie { "to": "..." }, ou omita para um nome -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

O corpo do mapa

Leituras e gravações usam exatamente o mesmo JSON de uma Exportação: um objeto com zones, layers e layerOrder. Consulte o formato de arquivo de mapa para cada campo. Uma gravação é aceita desde que contenha layers (ou um tiles legado de nível superior).

Erros e códigos de status

Os erros retornam um pequeno objeto JSON como { "error": "..." } com um status HTTP correspondente:

Exemplo: buscar a partir do Unity

Uma corrotina C# mínima que traz um mapa para o Unity com UnityWebRequest. O texto da resposta é o JSON completo do mapa, pronto para analisar e transformar em 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);
}

Trate o token como uma senha: mantenha-o fora de repositórios compartilhados e builds públicas, e regenere-o se ele vazar. Como a API só lê e grava mapas inteiros, o padrão de automação mais seguro é ler, alterar, gravar de volta.

← Voltar para toda a documentação