Map Blueprint

第 2 级 · 进阶指南

HTTP API

你的实例可以提供一个小型 HTTP API，让脚本、游戏引擎和程序化工具读写整张地图，无需浏览器。你可以借此让 Unity 生成地图、按计划备份地图，或从自己的流水线中编辑它们。身份验证使用你掌控的单个令牌。

可选：绘制地图不需要用到 API。 没有它应用也能完整运行。只有当你想从浏览器之外自动化地图时才启用 API。在你创建令牌之前，它处于关闭状态。

启用 API

打开设置，找到自动化 API，点击生成令牌。将令牌复制到安全的地方：它是你地图的钥匙。你可以随时重新生成它（会立即使旧令牌失效），或彻底禁用 API。如果你更愿意通过环境设置它，请提供 API_TOKEN，它将接管，设置页中的字段会变为只读。

身份验证

每个请求都在 Authorization 标头中携带你的令牌。没有有效令牌的请求会被拒绝。请对令牌保密：拥有它的任何人都能读取并覆盖你的地图。

Authorization: Bearer YOUR_TOKEN

基础 URL

每个端点都位于你自己实例上的 /api/v1 之下，无论你在何处运行它（例如本地运行时的 http://localhost:8080，或你服务器的域名）。下面的示例使用 https://your-instance.example.com 作为占位符：请替换为你的地址。

端点

列出地图

GET /api/v1/maps

返回实例上的每张地图，附带文件大小和最后修改时间。

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

读取地图

GET /api/v1/maps/{name}

以 JSON 形式返回完整地图，格式与导出所得相同。可将其保存为文件、加载到 Unity，或在版本控制中比较差异。

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

创建或替换地图

PUT /api/v1/maps/{name}

从 JSON 请求体上传整张地图。如果地图是新的则创建它（201）；如果已存在则替换它（200）。任何正在浏览器中编辑该地图的人都会被重新加载到新版本。生成器、Unity 或程序化工具就是这样把地图写回的。

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

删除地图

DELETE /api/v1/maps/{name}

永久删除一张地图。没有撤销，所以如果你以后可能还想要它，请先通过读取做一次备份。

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

重命名与复制

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

重命名地图（发送 { "to": "new-name" }），或以新名称复制它（发送 { "to": "..." }，或省略以获得自动的 -copy 名称）。

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

地图请求体

读取和写入使用与导出完全相同的 JSON：一个包含 zones、layers 和 layerOrder 的对象。每个字段请参见地图文件格式。只要写入包含 layers（或旧版顶层 tiles），即被接受。

错误与状态码

错误返回一个类似 { "error": "..." } 的小型 JSON 对象，并带有相应的 HTTP 状态：

示例：从 Unity 获取

一个使用 UnityWebRequest 将地图拉取到 Unity 的最小 C# 协程。响应文本即完整的地图 JSON，可直接解析并转换为地形。

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

把令牌当作密码对待：不要放进共享仓库和公开构建中，一旦泄露就重新生成它。由于 API 只读写整张地图，最安全的自动化模式是读取、修改、写回。

← 返回全部文档