---

name: navigation-realtime description: "Guides MaaNTE map teleport, local route navigation, online map WebSocket, coordinate capture, realtime assistance, movement tests, and dataset collection." disable-model-invocation: true metadata: disco-role: operating license: AGPL 3.0

Navigation and Realtime

Use This When

Use this sub-skill for MaaNTE's realtime and navigation systems:

• RealTime auto loot / skip-story / auto teleport loops.
• OnlineMapNavigation WebSocket service and route ingestion.
• local_route_navigation CustomAction and LocalRouteNavigation Python class.
• Map teleport and teleport-required distance checks.
• Coordinate capture backends, route JSON schemas, map calibration, and route validation.
• Movement tests and autonomous-driving dataset collection.

If the task is only a gameplay task that happens to call navigation (for example fountain or FishNew auto-navigation), read this for the navigation portion and return to ../gameplay-tasks/SKILL.md for task-specific behavior.

Read First

1. references/navi-workflows.md for local route navigation, OnlineMapNavigation, coordinate capture, and map teleport APIs.
2. references/route-data-formats.md for route and teleport JSON schemas.
3. references/troubleshooting.md for DirectML/CPU, coordinate backend, WebSocket, and route-convergence failures.
4. Use scripts/validate_route_json.py to validate route JSON without a game window.

Core Runtime Boundaries

• Visual position backend uses screenshots, map template matching, and the ONNX angle predictor.
• Coordinate backend uses an encrypted Windows coordinate module plus packet/capture backend and can skip visual screenshot work when active.
• Online map navigation and route following share one custom action because MaaFramework runs one action at a time.
• Route execution needs a live Maa Context, controller, current game state, and stopping signal; it cannot be fully unit-tested from an ordinary script.

Safe Static Checks

python sub-skills/navigation-realtime/scripts/validate_route_json.py path/to/route.json
python ../../scripts/check_maante_environment.py --summary

These checks validate data shape and imports only. They do not prove that coordinate capture, DirectML inference, game movement, or WebSocket clients work in a real run.

Editing Priorities

• Keep route parsers permissive only where source code supports it: pixelX/pixelY, target_x/target_y, raw x/y/z, and online-map lat/lng are supported.
• Keep frame_interval minimum behavior at 0.05 seconds for visual modes and 60 Hz for active network coordinate mode.
• Keep position_backend values to auto, coordinate, and map.
• Keep angle_backend values to auto, directml, and cpu.
• Preserve WebSocket message compatibility: top-level type, version, position, angle, pitch, angleConfidence, route, and timestamp.