My personal Minecraft bot written in Rust built with Azalea.
Primarily designed to be a pearl bot, allowing for quick travel to different locations with multiple accounts.
Also featuring a Discord bot, an HTTP API for local integrations, a Docker image, and support for No Chat Reports encryption.
Choose your preferred Installation Method below, then run the bot once to create files.
Open the global-settings.toml file and change the server_address to your desired server.
Rename the ExampleBot*.toml in local-settings to your desired accounts Minecraft Username,
Then open the local settings file and change the auth_mode to online.
You can check the global and local source files for documentation.
You can optionally use ZenithProxy between my bot and your desired server,
This can be useful if you want to keep your place in queue with non-priority accounts.
Add server_address = "127.0.0.1:ZENITH PORT HERE" to the top of your local settings file.
Note: This is intended for proxies only, do not use it to connect accounts to different servers.
To enable debug logging you must set the environment variable:RUST_LOG=shaysbot=debug,info (error, warn, info, debug, trace)
The first is the log level of the bot, the second is of dependencies.
Compiled with GitHub Actions using the Debug profile.
Pull from the image ghcr.io/ShayBox/ShaysBot. Available tags are listed
here.
All configuration files are in the container's working directory, /config. If using a bind mount
for this directory, make sure config mount point on the host has the proper permissions and
ownership set for the application to be able to access it inside the container.
For an example compose.yaml file for use with Docker Compose, see
compose.example.yaml.
Prerequisites:
- 2GIB of RAM/SWAP (To build locally, much less to run)
- Update
- LLVM (Clang/LLD)
- Windows:
winget install -e --id LLVM.LLVMor Visual Studio - ArchLinux:
sudo pacman -S base-devel clang lld - Debian/Ubuntu:
sudo apt install build-essential clang lld - Fedora:
sudo dnf install clang lld - Other: Ask Google, ChatGPT, or Deepseek
- Windows:
- Rust (Cargo/Rustup)
- Windows:
winget install -e --id Rustlang.Rustup - ArchLinux:
sudo pacman -S rustup - Debian 13+:
sudo apt install rustup - Ubuntu 24.04+:
sudo apt/snap install rustup - Other: Rustup
- Windows:
Troubleshooting:
- No space left on device - Your /tmp directory is too small or full
sudo mount -o remount,size=1G /tmp && rm -rf /tmp/cargo-install*
Tmux Helper Script:
You may want to use tmux or screen to keep it running,
Here's a helper script I use to make it easier.
#!/usr/bin/env bashif! tmux has-session -t ShaysBot 2>/dev/null
then
tmux new -d -s ShaysBot "RUST_LOG=shaysbot=debug,info ~/.cargo/bin/shaysbot"fi
tmux attach -t ShaysBotrustup toolchain install nightlycargo +nightly install --git https://github.com/ShayBox/ShaysBotmkdir pearl-botshaysbot
git clone git@github.com:ShayBox/ShaysBot.gitcd ShaysBot- Run:
cargo run - Build:
cargo build(target/debug/shaysbot) - Install:
cargo install --path .(shaysbot)
Run and Build use Debug while Install uses Release.
You can manually override with either: --debug or --release
Debug includes debug symbols which makes it easier to debug and decompile.
Release has more optimizations, runs faster, and uses less disk space.
Debug: Settings are relative to the binary executable directory.
Release: Settings are relative to the current working directory.
- Interact - Send an interact block packet at the given coordinates
- Join - Connect an account to the server by enabling
AutoReconnect - Leave - Disconnect an account from the server and disable
AutoReconnect - Pearl - Automatically pull the closest stasis chamber at a
location - Playtime - Fetch a players play time using
2b2t.vc - Seen - Fetch a players first and last seen time using
2b2t.vc - Whitelist - Add or remove players from the whitelist or link their Discord
- AntiAfk - Automatically swing arm to avoid being kicked
- AutoEat - Automatically eat food to avoid starving to death
- AutoKill - Automatically swap and attack nearby monsters
- AutoLeave - Automatically leave the server when in danger
- AutoLook - Automatically look at the closest player in range
- AutoPearl - Automatically goto and pull player stasis chambers
- AutoTotem - Automatically equip totems of undying to avoid dying
- AutoWhitelist - Automatically whitelist players that enter range
- Logger - Log game events to Discord via webhooks with round-robin URL distribution
The logger sends game events to Discord using webhook URLs. Configure it in global-settings.toml:
[logger]
# Global fallback webhook URLs (round-robin across multiple URLs for rate limit distribution)webhooks = [
"https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN",
]
[logger.event.player_join]
enabled = true# Log when a bot joins the game
[logger.event.player_leave]
enabled = true# Log when a bot leaves the game
[logger.event.player_enter]
enabled = true# Log when players enter visual range (join + add_entity)
[logger.event.player_exit]
enabled = true# Log when players leave visual range (remove + player_info_remove)
[logger.event.player_command]
enabled = true# Log all commands run by any source (Minecraft, Discord, API)
[logger.event.player_pearl]
enabled = true# Log ender pearl stasis chamber pulls# Block events use a separate config with block filtering
[logger.event.player_break]
enabled = true# Log blocks broken in visual range (see block filter below)
[logger.event.player_place]
enabled = true# Log blocks placed in visual range (see block filter below)# Pearl events
[logger.event.pearl_missing]
enabled = true# Log when pearl inventory is depleted at a stasis chamber
[logger.event.pearl_path_failed]
enabled = true# Log when pearl goto pathfinding fails (pathfinder busy)
[logger.event.pearl_return]
enabled = true# Log when bot returns to idle goal after pearl pull# Auto-whitelist events
[logger.event.auto_whitelist_add]
enabled = true# Log when a player is auto-added to the whitelist# Chat events
[logger.event.player_chat]
enabled = true# Log chat messages received from other players# Server connection events
[logger.event.server_disconnect]
enabled = true# Log server-side disconnects (reason from server)
[logger.event.server_reconnect]
enabled = true# Log successful reconnections after disconnect
[logger.event.server_error]
enabled = true# Log disconnect/error packets from server (e.g. kick reasons)Each event type can optionally specify its own webhook URLs to send to a different Discord channel:
# Send pearl events to a separate "pearls" channel
[logger.event.player_pearl]
enabled = truewebhooks = [
"https://discord.com/api/webhooks/PEARL_WEBHOOK_ID/PEARL_WEBHOOK_TOKEN",
]
# Disable player join notifications entirely
[logger.event.player_join]
enabled = falseBlock break/place events support a configurable filter to control which blocks are logged. By default, it logs high-value blocks:
Default block list: All shulker box colors, netherite_block, gold_block, diamond_block, emerald_block, lapis_block, redstone_block
To customize the block list for break or place events:
# Only log netherite and diamond breaks
[logger.event.player_break]
enabled = trueblocks = [
"netherite_block",
"diamond_block",
]
# Log all blocks placed (override with empty list to disable filtering)
[logger.event.player_place]
enabled = trueTo log all block types, set an empty blocks list or use a wildcard pattern:
# Log every block break/place
[logger.event.player_break]
enabled = trueblocks = [""] # Empty string matches everything| Event | Description |
|---|---|
player_join | When a bot joins the game |
player_leave | When a bot leaves the game (with disconnect reason) |
player_enter | When players enter visual range (both tab-list join and add-entity packets) |
player_exit | When players leave visual range (both remove-entities and player-info-remove packets) |
player_command | All commands run, with source attribution (console, discord:<user_id>, or api) |
player_pearl | Ender pearl stasis chamber pulls (with remaining count / over-limit warnings) |
player_break | Block break events in visual range (configurable block filter) |
player_place | Block place events in visual range (configurable block filter) |
pearl_missing | Ender pearl inventory depleted at a stasis chamber |
pearl_path_failed | Pearl goto pathfinding failed (pathfinder already busy) |
pearl_return | Bot returned to idle goal after pearl pull |
auto_whitelist_add | Player auto-added to whitelist via whitelist_in_range |
player_chat | Chat messages received from other players |
server_disconnect | Server-side disconnect with reason |
server_reconnect | Successful reconnection after disconnect |
server_error | Disconnect/error packets from server (e.g. kick reasons) |
When multiple webhook URLs are provided for an event type, messages are distributed across them using round-robin ordering. This helps avoid rate limits and provides redundancy if one webhook URL becomes invalid.
- Discord - Discord chat command parsing integration
- HttpApi - Local HTTP API command parsing integration
- Minecraft - Minecraft chat command parsing integration
- GlobalSettings - Global Swarm Settings that apply to every account
- LocalSettings - Local Account Settings that apply per-account
- StasisChambers - Global Stasis Chambers
- BlockStates - Tracks block states for trapdoor closes
- EnderPearls - Tracks ender pearls for new chambers
- GameTicks - Tracks game ticks for counting intervals
- PlayerProfiles - Tracks player profiles for visual range