地图文件格式

你制作的每张地图都保存为一个纯文本 .json 文件。该格式小巧、易读且完全归你所有：你可以用任何文本编辑器打开它、纳入版本管理、备份、用脚本生成，或在不同实例之间移动它。本页准确说明其中的内容。

使用本应用并不需要了解这些内容。 Map Blueprint 会替你读写这些文件。本参考仅面向想要手动编辑地图、用工具生成地图，或想准确了解导出内容的人。如果你只想画地图，完全可以跳过它。

顶层结构

地图文件是一个 JSON 对象，包含三个键：zones（你的调色板）、layers（地图本身，主世界和任何内部区域）以及 layerOrder（图层列出的顺序）。最简单的形式如下所示：

{
  "zones": {
    "forest": { "name": "Forest", "color": "#3f8f4f" },
    "water":  { "name": "Water", "color": "#3a6ea5" }
  },
  "layers": {
    "world": {
      "name": "Overworld",
      "tiles":   { "10_8": { "z": "forest" }, "11_8": { "z": "water" } },
      "labels":  { "L1": { "x": 10, "y": 8, "text": "Greenwood" } },
      "markers": { "M1": { "x": 11, "y": 8, "icon": "🏰", "scale": 1.5 } }
    }
  },
  "layerOrder": ["world"]
}

区域，调色板

zones 是一个对象，将一个简短的区域键（任意你选择的小写 id，例如 forest）映射到它的定义。格子通过该键引用区域，因此重命名区域的显示名称绝不会破坏地图。

name，在调色板中显示的可读标签（字符串）。
color，填充颜色，使用十六进制代码，例如 "#3f8f4f"。

图层，地图

layers 将一个图层 id 映射到一个图层。主地图始终使用 id world；额外的图层（地牢、建筑内部、独立大陆）拥有各自的 id。每个图层都是独立的：

name，图层的显示名称（字符串，例如 "Dragon's Lair"）。
tiles，已绘制的格子（见下文）。
labels，地图上的地名文字。
markers，放置在地图上的图标。

格子，已绘制的单元格

tiles 将一个单元格坐标映射到在该处绘制的区域。键是写作 "x_y" 的网格位置（先列后行，用下划线连接）。只有已绘制的格子才会被保存，空白处不占用任何空间，因此一张大而几乎空白的地图仍然是个小文件。每个单元格只有一个字段 z，即上面调色板中的区域键。

"tiles": {
  "45_44": { "z": "plains" },
  "46_44": { "z": "plains" },
  "46_45": { "z": "water" }
}

标签，地名

labels 将一个 id（任意唯一字符串）映射到放置在地图上的文字标签。每个标签都有一个网格位置和它的文字：

x、y，标签所在的网格单元格（数字）。
text，标签文字（字符串，最多 200 个字符）。

标记，图标与入口

markers 将一个 id 映射到放置在地图上的图标。标记还可以充当通往另一图层的入口，这就是你把主世界与地牢连接起来的方式。

x、y，标记所在的网格单元格（数字）。
icon，标记字形，通常是一个表情符号（短字符串，最多 16 个字符）。
scale，图标绘制的大小（从 0.3 到 16 的数字；1 为默认大小）。
link，可选。另一图层的 id；点击该标记会前往那个图层。普通标记则省略它。

图层顺序

layerOrder 是一个图层 id 列表，用于固定图层出现的顺序。它始终包含 "world"。任何存在但未出现在列表中的图层，在文件加载时会被直接追加到末尾，所以即使你漏掉一个也没关系。

导出与导入

在你的地图面板中，你可以导出任意地图，将其下载为 .json 文件，也可以导入一个 .json 文件来引入地图。这是在不同电脑间移动地图、与队友分享地图或保留异地备份的最简单方式。

导入绝不会覆盖已有地图，如果名称已被占用，新地图会以带编号的名称引入（例如 my-world-2）。
把 tiles 存放在顶层（而非 layers 内部）的旧式单图层文件仍可正常导入，它们会被自动升级为一个 world 图层。
导出的文件与磁盘上的文件完全相同，因此复制整个 data/ 文件夹同样是一种有效的备份。

一个完整示例

下面是一张小而完整、包含两个图层的地图，一个主世界，其洞穴标记链接到一个地牢图层：

{
  "zones": {
    "water":   { "name": "Ocean", "color": "#2f5e94" },
    "plains":  { "name": "Plains", "color": "#9fc46a" },
    "forest":  { "name": "Forest", "color": "#3f8f4f" },
    "mountain":{ "name": "Mountain", "color": "#8a7560" },
    "dungeon": { "name": "Dungeon", "color": "#7a52b0" }
  },
  "layers": {
    "world": {
      "name": "Overworld",
      "tiles": {
        "20_14": { "z": "plains" },
        "21_14": { "z": "forest" },
        "22_14": { "z": "mountain" },
        "22_15": { "z": "water" }
      },
      "labels": {
        "L1": { "x": 20, "y": 14, "text": "Eldermoor" }
      },
      "markers": {
        "M1": { "x": 20, "y": 14, "icon": "🏯", "scale": 2.0 },
        "M2": { "x": 22, "y": 14, "icon": "🕳️", "scale": 1.4, "link": "lair" }
      }
    },
    "lair": {
      "name": "Drake's Lair",
      "tiles": {
        "10_10": { "z": "dungeon" },
        "11_10": { "z": "dungeon" },
        "11_11": { "z": "dungeon" }
      },
      "labels": {
        "D1": { "x": 10, "y": 10, "text": "Entrance Hall" }
      },
      "markers": {
        "D1": { "x": 11, "y": 11, "icon": "🐲", "scale": 2.2 }
      }
    }
  },
  "layerOrder": ["world", "lair"]
}

如果你手动编辑文件，请保持它是有效的 JSON（一个放错位置的逗号会导致无法加载），并先做一份副本。拿不准时，导出一张真实的地图，把它当作起始模板。