- Rust 87.6%
- Python 10.8%
- Shell 1.6%
ventoz91
f54f99f321
Navigation (M3): - goto_near(): RadiusGoal wrapper with configurable timeout; stops the bot before entering the target's block — critical for chasing players without blocking forever - swim_up_move / swim_down_move: let the pathfinder plan through fluid columns so the bot can surface from deep water or descend to an underwater goal Gremlin skill (M8 start): - `gremlin <name>` chat command: bot stalks the named player, stares at them, and places dirt in their path every 5 s - surface_above(): targets the water surface instead of diving when player is underwater - find_dirt_spot(): skips player hitbox and server-rejected positions - Exponential nav backoff: 3 s → 6 s → 12 s (cap 15 s) when player is in an inaccessible location (tree, flying); resets when player steps to a new block - 1 s deceleration wait after RadiusGoal Reached so sprint momentum clears before the next distance check Known bugs documented in CLAUDE.md: - stop_pathfinding() latency: old pathfinder keeps running during backoff sleep, causing the "goes crazy after timeout" behaviour; fix is force_stop + wait_updates - No ground-lurk for persistently elevated player: after hitting the 15 s backoff cap the bot retries indefinitely instead of navigating to ground below target Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| agent | ||
| core | ||
| docs | ||
| scripts | ||
| toolbox | ||
| .gitignore | ||
| ARCHITECTURE.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| config.example.toml | ||
| MILESTONES.md | ||
| pyproject.toml | ||
| README.md | ||
mcbot
A Minecraft bot framework built in Rust and Python. The Rust core handles the real-time engine — protocol, world model, pathfinding, and primitive actions. The Python layer hosts the AI brain: an LLM planner, a composable skill library, and (eventually) ML policies.
The near-term goal is a solid line-follower / pathfinding bot similar to Baritone. The long-term goal is a bot you can hand a natural-language task and walk away from.
MC version: 26.2
Status: M1–M4 complete · M8 in progress (gremlin)
Architecture
┌──────────────────────────────────────────────────────┐
│ Python Layer │
│ LLM planner → skill library → @skill tool registry │
└─────────────────────┬────────────────────────────────┘
│ PyO3 (mcbot_core extension)
┌─────────────────────▼────────────────────────────────┐
│ Rust Core │
│ azalea session → world model → pathfinder → actions │
└─────────────────────┬────────────────────────────────┘
│ TCP
Minecraft Server (Fabric 26.2)
See ARCHITECTURE.md for the full data-flow diagram and directory map.
Getting started
Prerequisites
- Rust (nightly) —
rustup override set nightlyinside the project root - Java 21+ — for the dev Fabric server
- Python 3.11+ — for the agent layer (M6+)
Build
git clone https://git.ventoz.ca/trevor/mcbot.git
cd mcbot
rustup override set nightly
cp config.example.toml config.toml # config.toml is gitignored
cargo build
Run a dev server
The script downloads the Fabric installer and MC 26.2 server jar on first run.
bash scripts/run_local_server.sh
Connect the bot
cargo run
Edit config.toml to change the server address, port, username, or auth mode.
For online-mode servers set [auth] mode = "microsoft" and your account email
(first run does a one-time device-code login). config.toml is gitignored, so
your address and account stay out of git — config.example.toml is the template.
Project layout
core/ Rust bot engine (azalea-based)
agent/ Python AI layer (LLM planner, skill registry)
toolbox/ Skill implementations (grows over time)
scripts/ Dev utilities
docs/ Reference docs
tests/ Rust unit + Python integration tests
config.toml Server / bot / LLM config
Milestones
| # | Milestone | Status |
|---|---|---|
| 1 | Protocol & Connection | ✅ Done |
| 2 | World Model | ✅ Done |
| 3 | Hybrid Navigation — goto wrapper, path logger, custom moves | ✅ Done |
| 4 | Primitive Action Set — break, place, equip, attack, interact, craft, inventory | ✅ Done |
| Demo | Chop & Craft — finds logs, chops, crafts planks + table, places it | ✅ Done |
| 5 | Session Telemetry — replayable traces | 🔲 |
| 6 | Python Bridge (PyO3) | 🔲 |
| 7 | LLM Agent (Claude tool-use) | 🔲 |
| 8 | Skill Library — gremlin mode (gremlin <name>): stalk, stare, place dirt |
🔶 In progress |
| 9 | ML Layer (RL policies, consumes M5 traces) | 🔲 Future |
| 10 | Self-improving Toolbox | 🔲 Future |
See docs/hybrid-navigation.md for the navigation design, and docs/dev-observation.md for how to watch the bot while developing.
Full milestone spec: MILESTONES.md
Tech stack
| Layer | Tech |
|---|---|
| MC protocol | azalea |
| Rust async | tokio |
| Rust→Python | PyO3 + maturin |
| LLM | Claude (Anthropic SDK) |
| Dev server | Fabric 26.2 |
| Python build | pyproject.toml (maturin backend) |
License
MIT