离散瓦片地形 MCP 创作指南

离散瓦片地形 MCP 是 SCE Editor 中面向 AI 和自动化工具的离散瓦片地形创作接口。它适合编辑已经打开的离散瓦片地形场景，完成地表、TileSet、高度、台阶/斜坡、水域、裂缝、视野遮挡、手绘碰撞、道路和装饰物的可预览、可回滚修改。

当前定位为 Preview / Early Access，提供离散瓦片地形的创作与 Runtime terrain.snapshot 观测入口。操作前检查实际工具 schema；读取快照时按返回字段和能力状态判断混合 TileSet、纹理权重、水域及道路拓扑信息是否可用。

适用范围

本指南适用于：

• 使用完整 SCE Editor MCP 的 AI agent 或外部自动化工具；
• 编辑项目 scene/ 下已有的离散瓦片地形场景；
• 需要可重复的 Preview → Apply → Save → Reload 验收流程。

本指南不覆盖 Landscape 连续高度场。调用前应先用 terrain_get_scene_summary 或 terrain_get_state 确认当前场景和 backend capability。

推荐工作流

先准备项目和场景：

editor_get_context
-> editor_open_project / editor_open_scene
-> editor_lifecycle_wait
-> editor_get_context(ready_state = scene_ready)
-> terrain_get_scene_summary
-> terrain_get_state

对任何修改都使用：

查询可用选项
-> terrain_preview_*
-> 检查 preview 结果、错误和边界
-> terrain_apply_*
-> terrain_get_state / terrain_list_history
-> terrain_undo 或 terrain_redo（需要时）
-> terrain_save_scene
-> terrain_validate_scene

新建测试场景并需要跨 reload/reopen 保留时，必须额外调用项目级 data_save 或 data_save_and_generate。terrain_save_scene 保存地形源数据和 projection，但不会代替 DataManager 场景索引保存。

先确认场景能力

推荐先调用：

• terrain_get_scene_summary：确认 terrain_model、尺寸、dirty 状态和 projection 摘要；
• terrain_get_state：确认 history_state_id、保存检查点、Undo/Redo 和烘焙状态；
• terrain_list_tile_sets：列出当前已加载的 TileSet、显示名、厚度和场景瓦片计数。

离散瓦片地形的高度是离散层级：height=1 表示抬高一层，不能把 world_z_per_unit 当作高度输入。world_z_per_unit 只用于解释实际世界高度。

地表风格、纹理和 TileSet

地表采用两级语义选择：

1. terrain_list_surface_styles 列出一级地表风格；
2. terrain_list_surface_textures 列出该风格下的具体纹理；
3. terrain_preview_surface_paint 预览区域绘制；
4. terrain_apply_surface_paint 应用已确认的纹理权重。

不要把内部材质路径、纹理文件名或悬崖 prefab 路径当作用户输入。悬崖由 TileSet、地形风格和当前拓扑自动匹配。

如果需要切换整块瓦片的 TileSet：

terrain_list_tile_sets
-> terrain_preview_tile_set_paint
-> terrain_apply_tile_set_paint

TileSet 切换会校验悬崖、台阶、水域和道路拓扑；它不会修改 prefab，也不会自动保存。

不同 TileSet 可以共存。若同一次非零高度编辑跨越 TileThickness 不同的 TileSet，MCP 会返回 terrain_height_tile_thickness_inconsistent 并拒绝写入。应拆分为同一厚度区域内的独立操作，不要尝试通过选择另一个悬崖 prefab 绕过该错误。

高度编辑

高度操作支持 raise、lower 和 flatten，先预览再应用：

terrain_preview_height_edit
-> 检查 backend、离散层数、受影响瓦片、TileSet 厚度和拓扑诊断
-> terrain_apply_height_edit

对离散瓦片地形：

• height / target_height 使用离散层数；
• Preview 会生成顶点高度、边标记、地表和悬崖拓扑计划；
• Apply 通常生成一条 terrain.height_edit Undo/Redo 事务；
• Apply 不自动保存 map.acmap；
• terrain_height_topology_unsupported 或厚度不一致错误发生时，不会修改场景、dirty 或历史。

Apply 应携带最近 Preview 返回的 preview_token / preview_hash。只有在明确掌握当前 history_state_id 时，才使用 skip_preview=true 的受控路径。

水域

水域使用 TileCalc 规划水陆点、高度、岸线和完整瓦片拓扑：

terrain_preview_water_edit
-> terrain_apply_water_edit

支持绘制、擦除和高度调整。Apply 只修改内存并生成历史事务；需要持久化时继续调用 terrain_save_scene。

台阶斜坡

先按目标 TileSet 查询台阶斜坡风格：

terrain_list_ramp_styles(tile_set_id?)
-> terrain_preview_ramp_edit
-> terrain_apply_ramp_edit

输入世界坐标 polyline、width、operation=paint/erase 和 style_id。风格绑定所属 TileSet；跨 TileSet 时应拆分。Preview 规划地形边、坡面和关联高度变化。旧 terrain_list_path_styles、terrain_preview_path_edit、terrain_apply_path_edit 保留相同台阶斜坡语义。

道路

terrain_list_road_styles 列出场景编辑器道路画笔的样式。terrain_preview_road_edit / terrain_apply_road_edit 使用 region、operation=paint/erase、paint 时必填的 style_id，以及可选 density=0..100，默认100。

道路编辑复用原生道路画笔，处理道路标识、地表纹理和边缘装饰物。擦除会移除道路标识及边缘装饰物，保留已经绘制的地表纹理；需要恢复纹理时另用地表纹理画笔。道路不会生成台阶坡面。

裂缝、碰撞与视野遮挡

以下工具都支持世界坐标圆形或矩形 region 和 operation=paint/erase，并沿用 Preview → Apply → Undo/Redo → 显式保存流程：

画笔	Preview / Apply	区域选择及语义
裂缝	terrain_preview_crack_edit / terrain_apply_crack_edit	选择地形边中点；规划裂缝拓扑、高度以及相连水域转陆地，实际影响可超出选定区域
手绘碰撞	terrain_preview_collision_edit / terrain_apply_collision_edit	选择碰撞格中心；paint 按位添加，erase 使用原生画笔擦除全部碰撞类型
视野遮挡	terrain_preview_sight_edit / terrain_apply_sight_edit	选择视野格中心；paint 仅添加未遮挡格，erase 减少一层

手绘碰撞 paint 可传 collision_flags，默认4094。使用场景原生位值：不可行走2、不可飞行4、不可建造8、不可漂浮64、不可两栖128、不可放置物品256、悬崖512、高障碍1024、低障碍2048；组合时按位或。

terrain_query_collision / terrain_query_sight 使用 region 读取网格尺寸与格子原值，最多返回256格；cells_truncated=true 时拆成小区域查询。碰撞查询只读取手绘层。Surface2D 的运行时静态碰撞还包含场景保存时烘焙的地形、装饰物碰撞；擦除手绘层不会移除这些烘焙碰撞。

装饰物

装饰物资源和场景实例要分开理解：

• terrain_list_decoration_resources 查询可放置资源；
• terrain_query_decorations 查询用户显式放置的实例；
• 自动 Tile proxy 不是可编辑装饰物实例。

小批量修改：

terrain_preview_decoration_edit
-> terrain_apply_decoration_edit

支持 place、move、remove、rename。rename 只改地图实例在左侧树上的名称，不改 prefab。同一实例可以在一次命令中合并一次 move 和一次 rename，仍生成一个原子 mutation。

确定性散布：

terrain_preview_decoration_scatter
-> 检查 seed、候选拒绝原因、间距和坡度诊断
-> terrain_apply_decoration_scatter

保留 seed 和区域参数，后续才能复现相同实例 ID 和变换。

手绘碰撞示例与运行时验收

例如在矩形内添加不可行走的手绘格，先调用 terrain_preview_collision_edit：

{
  "operation": "paint",
  "region": {"shape": "rectangle", "min": {"x": 320, "y": 320}, "max": {"x": 448, "y": 448}},
  "collision_flags": 2
}

检查返回的格子 before / after 和变更数量，再把原参数与返回的 preview_token、preview_hash 一起传入 terrain_apply_collision_edit。用 terrain_query_collision 查询同一区域，随后显式保存场景。视野遮挡沿用相同区域结构，使用 terrain_*sight_edit 和 terrain_query_sight，不传 collision_flags。

擦除完成后查询格子，或再次预览擦除以确认零变更，再撤销并读回原数据；只检查历史游标不足以验证恢复。对已没有裂缝的区域预览/应用擦除，会成功返回零变更而不新增事务。水域覆盖台阶/斜坡时可返回 terrain_water_path_conflict，应调整区域，或先明确擦除台阶。

Surface2D 的静态碰撞需按保存后的地形、装饰物和手绘碰撞验收。可见模型或 StaticMesh 不等于该场景中的有效静态遮挡。配置单位冲锋遇障碍停止时，参考 冲锋静态碰撞 Skill；运行时 StaticCollisionMask 使用枚举名，不直接套用这里的场景原生位值。

保存、验证和重载

Terrain 修改完成后，推荐：

terrain_get_state
-> terrain_save_scene
-> terrain_validate_scene
-> editor_reload_scene
-> editor_lifecycle_wait
-> terrain_get_scene_summary

保存成功应同时确认：

• 当前文档 save_dirty=false；
• 保存检查点与 history_state_id 一致；
• projection 严格校验通过；
• 源 map.acmap 与 projection hash 一致。

如果是 editor_create_scene 新建的场景，还要执行：

data_save 或 data_save_and_generate

否则场景目录可能已经存在，但 DataManager 场景索引尚未落盘。

Undo/Redo 与过期状态

不要通过 UI 文案或 dirty 状态猜测是否产生了事务。使用：

• terrain_list_history 查看稳定的 operation_type、游标和影响对象；
• terrain_get_state 获取当前 history_state_id；
• terrain_undo / terrain_redo 携带 expected_state_id。

如果返回 terrain_history_state_stale，先重新读取状态，不要盲目重试旧命令。

常见错误

错误	处理
terrain_map_not_loaded	先用 Editor 生命周期工具打开项目和场景。
terrain_height_topology_unsupported	缩小区域、调整目标高度或更换可表达拓扑。
terrain_height_tile_thickness_inconsistent	按 TileSet/厚度拆分高度编辑。
terrain_path_mixed_tile_set	道路按所属 TileSet 区域拆分。
terrain_history_state_stale	重新读取 terrain_get_state，重新 Preview。
unsaved_changes	明确保存或放弃修改后，再重复危险操作的 Preview。
scene_not_ready / editor_busy	等待对应 lifecycle operation，再检查 editor_get_context。

当前已知边界

• 本 Skill 只覆盖 Editor 中的离散瓦片地形 MCP，不等同于 Landscape 连续高度编辑 Skill。
• Runtime terrain.snapshot 是部分运行时观测：先检查 observation.unsupported_fields、observation.incomplete_fields、sampling、tile_sets、water 和 roads，再解释空值。tile_sets.status=catalog_available 时，tile_sets.items 返回客户端已加载的 TileSet/style 配置目录；tile_sets.distribution_status=available 时，tile_sets.distribution 返回实际运行时 tile style 的计数和 TileSet 映射，并通过 map_size_tiles 给出地图瓦片尺寸；无法读取逐瓦片数据时返回 no_data。当前客户端也明确不支持详细水域/道路拓扑；water.classification=texture_label_inferred 表示水域点是根据运行时纹理标签推断的，不代表完整水域覆盖。sampling 区分请求、成功采样和无数据点，采样点内的 texture_weights_status / texture_label_status 区分可用与无数据。完整 TileSet 分布与拓扑校验仍以 Editor Terrain 工具和 terrain_validate_scene 为准。
• terrain_save_scene 与项目级 data_save 具有不同保存范围；新建场景的自动化闭环不能省略后者。
• 所有写操作应串行执行，不要并行发送多个 Terrain mutation。