Robonix Package Catalog
Back to robots

robonix.robot.syswonder.minecraft_bot

Robonix deployment for an autonomous Minecraft player.

README

Robonix Minecraft bot deployment

This repository assembles a Minecraft Forge client primitive, Minecraft costmap and navigation services, the frontier exploration skill, and Robonix system components into one autonomous Minecraft player deployment. It owns the player body description, runtime configuration, and selected package versions.

This is a community integration and is not an official Mojang or Microsoft product.

Supported versions

  • Minecraft Java 1.20.4
  • Forge 49.2.0
  • Eclipse Temurin OpenJDK 17.0.19+10
  • ROS 2 Jazzy with Fast DDS
  • Robonix development baseline 74b4ca0f7c0db3c237730321753501e12646c626

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

Packages

  • syswonder/primitive-syswonder-minecraft_bot-rbnx provides camera, chassis, exact perception, inventory, block breaking, and item deposit.
  • syswonder/service-minecraft-costmap-rbnx converts depth and exact odometry into an occupancy grid and map pose.
  • syswonder/service-minecraft-navigation-rbnx plans and follows bounded A* paths through the occupancy grid.
  • syswonder/skill-minecraft-explore-rbnx explores reachable frontiers and observes the surroundings.

All runtime dependencies are selected by capability contracts through Atlas; the repository names above identify the implementations chosen by this deployment.

Prerequisites

Install a Rust toolchain, ROS 2 Jazzy, JDK 17, a Forge-compatible OpenGL environment, and Git. The bot also needs access to a Minecraft 1.20.4 server. NVIDIA unattended rendering additionally requires a usable NVIDIA driver and permission to start the configured Xorg display.

Quick start

1. Install Robonix

The following commands install the Robonix revision validated for this deployment. Skip this step when that revision is already installed and registered with rbnx setup.

git clone --recursive https://github.com/syswonder/robonix.git
cd robonix
git fetch origin 74b4ca0f7c0db3c237730321753501e12646c626
git checkout 74b4ca0f7c0db3c237730321753501e12646c626
git submodule update --init --recursive
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
make install
cd ..

2. Clone and configure the deployment

Only this repository is required. rbnx build downloads the four selected primitive, service, and skill packages at their published v0.1.0 tags.

git clone https://github.com/syswonder/robot-syswonder-minecraft_bot.git
cd robot-syswonder-minecraft_bot
cp .env.example .env

Edit .env before continuing. At minimum, set VLM_API_KEY, point JAVA17_HOME at a Temurin 17 installation, and set MC_HOST and MC_PORT to the Minecraft server. Keep the provided ROS 2 Jazzy setup path unless ROS is installed elsewhere. Select the NVIDIA launcher only when its Xorg requirements are available.

Load the environment and check the two required runtime installations:

set -a
. ./.env
set +a
"$JAVA17_HOME/bin/java" -version
test -f "$RBNX_MINECRAFT_ROS_SETUP"

3. Build and start

Build the deployment from the four remote package tags, then start it:

rbnx build -f robonix_manifest.yaml
rbnx boot -f robonix_manifest.yaml

The build succeeds when its summary reports zero failed packages. The Forge client then joins MC_HOST:MC_PORT; the framebuffer viewer is available at http://127.0.0.1:8765, and Scene is available at http://127.0.0.1:50107.

4. Verify and stop

In another terminal with the same .env loaded, inspect the registered capabilities or start a chat session:

rbnx caps -v
rbnx chat

Press Ctrl-C in the boot terminal for an orderly lifecycle shutdown. If that terminal was lost, load .env and run:

rbnx shutdown -f robonix_manifest.yaml

Local development

To test unpublished changes, place all five repositories as siblings under one directory and use the local manifest:

rbnx build -f robonix_manifest.local.yaml
rbnx boot -f robonix_manifest.local.yaml

Stop that deployment with its matching manifest:

rbnx shutdown -f robonix_manifest.local.yaml

Acceptance checks

Before publishing a release, verify:

  • the Minecraft client joins the selected world and the Mod command port is reachable only on loopback;
  • RGB, depth, camera calibration, odometry, and exact block observations are available;
  • the occupancy grid and map pose update while the player moves;
  • navigation reaches a free goal and supports status and cancellation;
  • exploration starts, reports status, expands the map, and cancels cleanly;
  • inventory, supported block breaking, and supported item deposit succeed;
  • Ctrl-C stops the client, viewer, primitive, services, skill, and system components without leaving their ports occupied.

Build and runtime logs are written under rbnx-boot/logs/ and are intentionally ignored by Git.

Repository layout

.
├── robonix_manifest.yaml        # Published remote package selection
├── robonix_manifest.local.yaml  # Local sibling-repository development
├── soma.yaml                    # Minecraft player body and capability ownership
├── minecraft_player.urdf        # Complete player URDF
├── .env.example                 # Non-secret environment template
└── README.md

Provenance and license

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