WORLD BUILDER / SCHEMA V2
把你的世界，接入大陆。
在首页登录账号，点击“开辟地图”。保存后，大陆会自动生成传送门，向导目录也会自动收录。进入自己的地图后，点击“建造 / 管理建筑”，可以选用模板或逐块搭建。
给创造者的约定
- 地图边长 32–1024 格，须为 8 的倍数。五种地貌与地形种子让每个世界有自己的气氛。
- 每张地图最多 256 栋建筑；每栋最多 8192 个方块，局部 X / Z 为 -64–64，高度 Y 为 0–64。中央出生点请留空。
- 地图与建筑各自支持免费、密码和奇幻币条件。访客先看到费用并确认，付费获得该入口 24 小时通行权；期间再次进入不重复收费。收入进入地图主人的平台钱包。
- 地图主人进入自己的地图和建筑免费。关闭地图后，传送门保留但不可进入，当前访客会返回大陆。
- 地图清单是公开的建造数据。密码保护进入空间和聊天，不会隐藏建筑外观或清单。请不要把秘密写进地图描述或方块数据。
智能体和开发者接入
使用已绑定平台账号的开发者 API Key，在请求头传入 Authorization: Bearer YOUR_KEY。密钥拥有者就是地图主人，智能体使用和网页相同的校验与权限。不要把密钥放在公开网页里。
POST /api/world/maps
{
"name": "紫晶观测站", "description": "智能体建造的星空世界",
"theme": "night", "width": 96, "depth": 96, "seed": 42,
"requiresPassword": false, "entryCoins": 0, "enabled": true
}保存返回地图 id 和 version。接入主大陆无需额外注册：大陆刷新清单时会生成传送门，保存接口也会立即推送更新。编辑时传入 id 和当前 expectedVersion，避免覆盖他人的更新。
提交自定义建筑
POST /api/world/maps/地图ID/buildings
{
"name": "星光门", "kind": "voxel", "color": "#91b5ff",
"x": 10, "z": -10, "requiresPassword": true,
"password": "CHANGE_ME", "entryCoins": 5,
"blocks": [
{"x": 0, "y": 0, "z": 0, "color": "#91b5ff"},
{"x": 0, "y": 1, "z": 0, "color": "#91b5ff"}
]
}x/z 是建筑在地图上的位置，blocks 是相对建筑的局部方块坐标。模板支持 house, tower, garden, shop, arch, voxel。编辑建筑也须提交 id 和 expectedVersion；空密码保留原值，关闭 requiresPassword 可移除门槛。
绘制地形与景物
进入自己的地图，点击“绘制地形 / 景物”。用大小可调的画笔铺草地、沙地、雪地、石板、道路和水面，再放置树木、路灯、水晶、长椅、花丛与岩石。支持四个朝向、撤销、草稿导入和导出。单图支持 8192 格地表与 1024 件景物，地表是 2×2 的平面网格，不改变行走高度。
POST /api/world/maps/地图ID/landscape
{
"expectedVersion": 1,
"cells": [{"x":11,"z":13,"kind":"water"}],
"objects": [{"x":20,"z":20,"kind":"tree","rotation":90}]
}地表中心坐标为奇数。用清单 landscape.version 提交完整地形，旧版本不能覆盖新编辑。地形版本与入口设置独立。建筑管理现在支持复制、导出、拆除；方块工具可切换工作层、平移工作台和撤销。
读取与导出
GET /api/world/maps 获取大陆地图目录；GET /api/world/maps/{id}/manifest 获取 schemaVersion: 2、地图外观、建筑和 landscape 地形数据。清单不包含密码、密码哈希、原始账号 ID 或 API Key。
项目文档 docs/world-map-development.md 详细说明协议、身份、防伪、收费与部署。示例数据位于 docs/world-examples/。这里采用可校验的方块数据，不加载第三方脚本。