MaaNTE在线地图实时定位寻路：Navi WebSocket如何同步位置坐标与自动规划路线
【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE
MaaNTE 是面向《异环》的免费开源自动助手（Nevertheless to Everless automatic assistant），其 Navi 导航模块通过Navi WebSocket把游戏内的实时位置坐标同步到在线地图，并支持从网页端下发路径点、自动规划路线逐个到达——一套双向通道搞定"我在哪、往哪走"两件事 🗺️。
工作原理：一个组合 Action 完成定位 + 寻路
在线地图导航由名为online_map_navigation的自定义 action 驱动，它在同一个截图循环中连续完成三件事：
- NCC 视觉定位：用游戏画面在异环全图（11264×11264 底图，如上所示）上做模板匹配，算出世界坐标；
- 方向预测：预测角色朝向角度，用于在线地图上绘制朝向；
- 路径寻路：收到网页端下发的路径点后，操控角色依序移动，到达一个点再前往下一个点。
由于 Maa 同时只能运行一个 action，实时定位和路径寻路就合并在这一个组合 action 里，由 route_websocket_service.py 把两者粘合成一个 WebSocket 双向通道。核心源码都在 agent/custom/action/Navi/ 目录下：
- online_map_navigation_action.py — action 入口，读取配置并启动服务
- navigation_server.py — WebSocket 服务端，负责状态广播与消息接收
- route_runner.py — 按顺序执行可变路线会话中的路径点
- map_locator.py / angle_predictor.py — 视觉定位与方向预测
- waypoint_navigator.py / nte_coordinate_api.py — 路径点导航与坐标接口
快速上手：三步启用在线地图导航
第 1 步 · 找到任务入口
在线地图导航的 Pipeline 入口位于 OnlineMapNavigation.json，任务设置位于 OnlineMapNavigation.json，在 MaaNTE 任务列表中找到并启用即可。
第 2 步 · 配置参数
任务设置支持覆盖端口、采样间隔、到达容差、定位方式和调试模式：
| 参数 | 默认值 | 说明 |
|---|---|---|
port | 14514 | WebSocket 监听端口 |
tolerance | 5 | 到达路径点的判定容差 |
frame_interval | 0.1 | 采样间隔（秒），最低0.05 |
position_backend | auto | 定位方式：auto/coordinate/map |
angle_backend | auto | 方向推理后端：auto/cpu/directml |
debug | false | 调试模式 |
第 3 步 · 连接在线地图客户端
服务固定监听0.0.0.0，网页端或自写客户端连接本机地址即可：
ws://127.0.0.1:14514连上后页面会自动重连；即使没有下发任何路径点，任务也会持续广播实时定位状态，在线地图上就能看到角色位置实时跳动。
实时定位消息解析：navi-state 长什么样
服务端每帧都会向所有已连接客户端广播一条navi-state状态消息，格式如下（摘自 NaviWebSocket.md）：
{ "type": "navi-state", "version": 1, "position": { "x": -134394.56, "y": 199913.53, "z": 11416.17, "pixelX": 4090, "pixelY": 6750, "sourceWidth": 11264, "sourceHeight": 11264, "score": 1.0, "mode": "coordinate" }, "angle": 123.4, "angleConfidence": 0.96, "timestamp": 1770000000.0 }几个关键字段的含义：
position.x / y / z：游戏原始世界坐标。网络定位直接发送x、y、z；视觉定位通过标定变换逆算，只发送x、y；pixelX / pixelY：定位点在全图底图上的像素位置（配合sourceWidth / sourceHeight使用），兼容旧版网页，新客户端应优先用原始坐标字段；mode：定位来源模式。网络坐标暂时中断时保留最后一次坐标，mode变为coordinate_stale；完全没有可转换位置时position为null；angle / angleConfidence：角色朝向及置信度，未识别时angle为null；score：视觉定位的匹配得分，越高越可靠。
自动规划路线：把路径点"发"给 MaaNTE
Navi WebSocket 是双向的：除了广播状态，服务端还会接收在线地图工具发送的路径点消息。收到后，RouteRunner会在 route_runner.py 中依序处理：
取出当前路径点 → 调用
navigator.move_to(target)操控角色前往 → 到达后自动推进到下一个路径点，直到全部走完（状态变为arrived）。
客户端还能在navi-state消息的route字段中实时看到寻路进度：
"route": { "waypoints": [], "active": false, "currentIndex": 0, "status": "idle" }active：是否有正在执行的路线；currentIndex：当前正在前往的第几个路径点；status：路线状态，如idle（空闲）、arrived（已到达）、cleared、empty、stopped。
消息解析逻辑集中在 route_model.py 的handle_route_message中，路径点集合支持随时增删——路线是"可变会话"，改完立刻生效，无需重启任务 🔄。
常见问题排查
| 现象 | 原因与解决 |
|---|---|
| 网页连不上 WebSocket | 确认 MaaNTE 中已启用在线地图导航任务；服务端启动失败时会写入日志，可打开debug排查端口占用 |
| 地图上不显示位置 | 检查position_backend：coordinate依赖网络坐标，map依赖视觉定位；建议保持auto自动切换 |
| 定位偶尔"卡住不动" | mode为coordinate_stale时是网络坐标短暂中断，服务端保留最后一次坐标继续发送，属正常现象 |
| 方向箭头乱转 | 尝试在任务设置中把angle_backend从auto改为cpu或directml |
更多细节可查阅官方文档 NaviWebSocket.md 与 本地路径导航说明。
小结
MaaNTE 的 Navi 模块用一条ws://127.0.0.1:14514的双向 WebSocket，把"实时定位、方向预测、路径寻路"整合进同一个截图循环：向下广播navi-state让在线地图实时显示角色位置与朝向，向上接收路径点让角色自动规划路线并逐个到达 🎯。对于想在地图上"指哪走哪"的玩家，这是目前最直接的接入方式。
【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
