# 地图工具清单

方法	用途	边界
tools.getMapGrid(map)	读取当前地图与格子快照	只读
tools.canMoveMapGrid(map, grid)	判断目标格是否可达	返回布尔值
tools.moveMapDirection(map, direction)	按方向移动	执行邻接与需求规则
tools.jumpMapGrid(map, grid)	直接传送	跳过普通邻接检查
tools.resetMap(map)	回到地图起点	会修改当前位置

地图参数支持真实 ID 或名称；稳定项目优先使用 ID。

# 当前格子快照

const current = tools.getMapGrid("世界地图");
if (!current) return;

tools.showNotify(tools.tr("当前位置：{name}", {
  name: current.name || current.gridid
}));

快照包含 mapid、mapname、gridid、name、des、startgrid 和 nextgirds。它是当前状态副本，不要直接修改字段。

# 普通移动与传送

try {
  await tools.moveMapDirection("世界地图", "right");
} catch (error) {
  tools.showToast(tools.tr("现在不能向右移动"), "warning");
}

普通移动应使用 moveMapDirection，由地图系统检查方向、邻接和目标需求。只有传送门、复活或管理员功能才使用 jumpMapGrid，并自行校验费用和权限。

# 格子生命周期

挂载点	责任
js_n	只读决定格子是否展示/可用
js_c	离开当前格子后执行清理或记录
js_g	进入目标格子后执行剧情、奖励或战斗

进入奖励和离开记录都要防重复。页面刷新不应再次获得“首次进入”奖励；可以保存已访问标记或事件版本。

# Canvas 地图交互

Canvas 节点点击应调用 canvas.emitBinding("move-east", payload)，再由绑定控件脚本调用地图 API。Canvas 不直接修改位置属性，也不根据本地动画结果假设移动成功；下一次状态快照才是权威结果。

# 常见失败

现象	原因
页面位置和地图位置不同	建了第二套位置状态
可以穿过不相邻格子	误用 jumpMapGrid
进入奖励重复发放	js_g 没有首次进入标记
Canvas 已移动但状态没变	只做了本地动画，没有 binding
地图找不到	名称重复或 ID 不存在

# 验收清单

• 起点、八方向邻接和反向连接正确。
• 普通移动遵守邻接与需求，传送只用于明确入口。
• js_n 无副作用，js_c/js_g 可重复进入而不重复奖励。
• 刷新、存档恢复和切换地图后当前位置一致。
• Canvas/渲染页面只消费权威地图快照。

继续阅读：地图插件 和 渲染布局与 Canvas。