Robonix Package Catalog
Back to packages

robonix.service.minecraft_navigation

Minecraft occupancy-grid navigation service.

README

Minecraft navigation service

This service consumes the existing map occupancy grid and map pose, plans an A* path, and follows it through short calls to the existing chassis move capability. It exposes the existing navigation contracts:

  • robonix/service/navigation/navigate
  • robonix/service/navigation/navigate/status
  • robonix/service/navigation/navigate/cancel
  • robonix/service/navigation/driver

Navigation is asynchronous: navigate returns a run_id, while status reports RUNNING, SUCCEEDED, FAILED, TIMEOUT, or CANCELED. A new goal cancels the previous active goal. Map and pose inputs and the chassis provider are resolved through Atlas rather than fixed provider ids or topics. While a goal reports navigating, callers must poll status rather than issue direct chassis move calls. A refined destination is another navigation goal; repeated progress results are expected and are not a reason to cancel. Each status call waits up to five seconds for a terminal change before returning progress. Cancellation is reserved for an explicit user request or a safety problem, and direct chassis control starts only after navigation is terminal. If a direct move still replaces one bounded navigation fragment, the runtime reads the latest pose, replans, and continues instead of marking the goal failed.

The planner treats unknown cells as blocked by default. It inflates occupied cells by the configured player radius, avoids diagonal corner cutting, moves an occupied goal to the nearest passable cell within a bounded radius, and replans when a newer occupancy grid blocks the remaining path.

Compatibility

  • ROS 2 Jazzy
  • Robonix development baseline 74b4ca0f7c0db3c237730321753501e12646c626

The service tracks the latest Robonix development version. Compatibility is verified again for every service release.

Build

With rbnx installed and configured against a compatible Robonix source tree:

rbnx validate .
rbnx build -p .

The build generates MCP bindings and runs the planner and runtime tests. Runtime initialization additionally requires active map occupancy-grid, map pose, and chassis move providers discoverable through Atlas.

The goal must use the frame published by the resolved map pose and occupancy grid. Leave goal.header.frame_id empty to select that frame automatically; the Minecraft provider commonly publishes minecraft_odom, so callers must not hardcode map. Empty selects a frame but does not transform coordinates: the supplied x, y, and yaw must already be expressed in the active frame. To approach a scene object, call scene/goal_near and pass its x, y, and yaw to navigation only when it reports reachable=true. The object's raw 3D centroid may be inside an occupied cell and is not a safe navigation goal.

Configuration

  • robot_radius_m: hard obstacle inflation radius, default 0.35.
  • occupied_threshold: minimum occupied cell value, default 50.
  • allow_unknown: allow planning through -1 cells, default false.
  • goal_search_radius_m: nearest-passable goal search, default 1.5.
  • max_iterations: A* work bound, default 500000.
  • linear_speed: forward velocity in blocks per second, default 2.0.
  • angular_speed: maximum yaw rate in radians per second, default 1.5.
  • command_duration_sec: duration of each closed-loop move, default 0.25.
  • heading_tolerance_rad: rotate-first threshold, default 0.20.
  • final_yaw_tolerance_rad: final orientation tolerance, default 0.15.
  • waypoint_tolerance_m: intermediate waypoint tolerance, default 0.35.
  • goal_tolerance_m: terminal position tolerance, default 0.60.
  • replan_interval_sec: minimum path validation interval, default 1.0.
  • goal_timeout_sec: per-goal timeout, default 120.
  • input_timeout_sec: Atlas and first-message timeout, default 30.

The complete accepted configuration, including units and validation ranges, is documented in config.spec.

Provenance

This service was extracted from examples/minecraft-mod/services/minecraft_navigation in syswonder/robonix at commit e30b99b4ca606d5a3463e9c42d7df2de81d680c4. It is distributed under the MulanPSL-2.0 license included in this repository.