Azalea: a Rust toolkit for Minecraft bots and headless clients

One version, on purpose

Azalea is a collection of Rust crates for making Minecraft bots, clients and tools, and the first line most people read past the title is the version note: currently supported Minecraft version 26.2. The README says that line is automatically read and updated by a migrate script, so you do not change it manually.

The goals section explains why it is a single version. Support everything that a vanilla Minecraft client can do, have an intuitive and easy to use API, make it easy to have many bots working at the same time, do not trigger anti-cheats, support the latest Minecraft version, and be fast and efficient.

The non-goals are equally explicit, and the first of them is supporting multiple versions of Minecraft at the same time, with a link to the azalea-viaversion project, which exists precisely to fill that gap. Graphics are a non-goal too, with a link to azalea-graphics, and Bedrock edition is the third.

So the shape of the project is: one game version, one protocol, headless only, and a plugin mechanism for everything else. That is a much narrower scope than a game client library, and it is a deliberate narrowing. The interesting part is not that Azalea speaks the protocol; it is that it speaks it as a headless ECS-driven actor that you script, which is a different kind of library from the ones most people reach for when they want to automate a game.

The warning at the top of the README is the other thing to read first. Many parts of Azalea are still unfinished and will receive breaking changes in the future, and most breaking changes will be listed in the changelog. There is a CHANGELOG.md at the repository root.

The licence is MIT, with a LICENSE.md file at the root, and the project is primarily maintained by one person as a hobby project, with sponsorship links on GitHub Sponsors and Ko-fi.

The crate workspace and what each piece does

The repository is a Cargo workspace with seventeen members, and the crate names describe the layers of the protocol stack quite directly.

At the bottom is azalea-protocol, the wire format, with a fuzz sub-crate for it. azalea-buf sits underneath as the buffer abstraction, and azalea-crypto handles the cryptography, which the dependency list shows as aes, sha1, sha2, md-5, rsa and rsa_public_encrypt_pkcs1, the last two at a release candidate version. azalea-registry holds the game data, the block and item tables, and the workspace depends on a crate called minecraft_folder_path, which suggests the registry is built from the game's own data files rather than hand transcribed.

Then the game model crates: azalea-entity for entities, azalea-inventory for inventories, azalea-world for world state, azalea-block for blocks, azalea-physics for physics, azalea-chat for chat, azalea-language for localisation, azalea-brigadier for the command grammar, and azalea-auth for authentication.

The top of the stack is azalea-client, which ties them together, and the azalea crate itself, which is the facade you depend on. The stable documentation for the main azalea crate is on docs.rs/azalea and the unstable documentation is at azalea.rs, which is a useful distinction to keep in mind, because the two will not describe the same API on any given day.

The ECS choice is the notable architectural decision. The workspace depends on Bevy components and applications, bevy_ecs 0.20.0 with default features off and the multi_threaded feature on, plus bevy_app, bevy_utils, bevy_log, bevy_tasks and bevy_time. Azalea is a Bevy application, which means your bot is an ECS world with systems, and the same model is used for swarms.

There is also a codegen directory, which is how the registry and other derived tables are produced, and a rust-toolchain.toml at the root pinning the compiler, along with rustfmt.toml and typos.toml for formatting and spell checking.

What the feature list actually claims, and what it admits

The features list is short and unusually honest, because each entry carries its own caveat.

Accurate physics is listed first, with the note that some features like entity pushing and sprint swimming are not implemented yet. The pathfinder has its own crate documentation page, and swarms do too. Breaking blocks links to the mine method on the Client struct, and block interactions and building link to block_interact, with the caveat that this does not predict the block interactions or placement on the client yet, though it is usually fine. Inventories link to the ContainerClientExt implementation for Client, and attacking entities link to the attack method. Plugins are listed as a feature of their own.

The phrase usually fine is doing real work in that entry, and it is worth understanding why. Azalea is a headless client, so it does not have the client side logic that validates a block placement against the world. It sends the interaction packet and assumes the server accepts it. In most cases the server does accept it, because the server is the authority on placement. But where the client would have predicted a failure, this library will optimistically proceed, and the difference shows up in edge cases rather than in the common path.

The physics caveat is similar. The physics model is accurate for the common cases, but the parts that require the client to have already performed a state update, pushing another entity or switching to sprint swim, are missing, which means a bot using the pathfinder will occasionally be slightly out of position.

The swarms feature deserves a mention because it is the one that makes the many-bots goal achievable. A swarm runs many clients in one process, sharing the ECS world and the event loop, and the pathfinder and other expensive operations are then amortised across the swarm rather than paid per bot.

The plugin system is what makes the rest extensible. Azalea supports Bevy plugins that can significantly alter its functionality, and the README points at two: azalea-viaversion for multi-version compatibility through ViaProxy, which is the officially recommended answer to the single version limitation, and azalea-hax for anti-knockback. The azalea-hax example is a good indication of the project's centre of gravity.

Reading the source: workspace version and build tooling

The workspace manifest is where the version relationship is stated most precisely, and it is worth looking at because the crate version and the game version are tied together in a way that matters for your Cargo.toml.

The workspace package version reads 0.16.0+mc26.2, the edition is 2024 and the resolver is set to version 3. The build metadata suffix, mc26.2, ties the release to the Minecraft version, so a dependency that asks for a particular version is implicitly asking for a particular game version. If the game updates and Azalea releases a new mc suffix, your lock file will not resolve to the old one, which is exactly what you want but also means you should expect version churn in your own dependency tree.

The dependency list also tells you about the network and platform assumptions. reqwest 0.13.5 with default features off, hickory-resolver for DNS, flate2 with the zlib-rs feature for compression, and chrono for time. There is a compact_str crate for string handling, indexmap and rustc-hasher for ordered and fast hashing, and nohash-hasher for the cases where you want to skip hashing entirely. The minecraft_folder_path dependency and simdnbt for NBT parsing both point to the same conclusion, which is that the game data and the save format are read from the real thing rather than reimplemented from documentation.

On the build side, the repository has a .cargo directory, a codegen directory and a docs-rs directory, which is the conventional layout for a project that generates part of its source and publishes rustdoc from a special configuration.

The README does not document an install command, so there is nothing to copy here. The project is used as a library: you add the azalea crate as a dependency, and the getting started pages are in the crate documentation on docs.rs and on the project site, azalea.rs, with the stable and unstable distinction described earlier.

For a quick orientation without writing anything, the README lists real bots built with Azalea as references: a pearl stasis bot with a Discord bot and an HTTP API, a bot that detects thrown pearls and walks to them, a collection of bots and plugins, a hardened Discord chat bridge for the LiveOverflow SMP, a bot with Lua scripting support, a project originally written as a Mineflayer bot and ported to Azalea, and a multi-task lightweight botting tool. The Lua scripting one is the most interesting reference if you want to script behaviour without writing Rust.

The anti-cheat goal, and where the real limits are

One of the stated goals is not triggering anti-cheats, and it deserves a careful reading rather than a promotional one.

The honest position is that a headless client that speaks the protocol will look different from the official client in some observable ways. The physics caveat and the block interaction caveat in the feature list are the concrete instances, and the azalea-hax plugin for anti-knockback exists because vanilla knockback behaviour is a signal that some servers look for. The project treats these as solvable problems, with plugins and patches, rather than as a guarantee.

The second limit is version lag. The library supports the latest Minecraft version and the migrate script updates the version line automatically, which means every Minecraft update is a release window during which you are either out of date or rebuilding against a new protocol. The azalea-viaversion project exists to let you run one bot against several versions through ViaProxy, which is the answer for a fleet that cannot all upgrade at once.

The third limit is the scope of what a headless client can do. There is no rendering, so a bot cannot see, and the project says so. It also does not support Bedrock edition, which is a different protocol entirely, and the multi-version support is explicitly a non-goal rather than a missing feature.

The fourth is the maintenance situation. The project is primarily maintained by one person as a hobby project, which is a real risk for anything you depend on in production, and the README itself is candid about it. The changelog and the breaking change warning are the mitigation, and a stable release channel exists alongside the unstable docs, but a hobby project with breaking changes is a hobby project.

The alternatives differ in kind. A higher level botting library in another language, with an existing community of plugins, will get you a working bot sooner and will not require you to implement the protocol at all, at the cost of the API and the control. A full Minecraft client library with rendering gives you everything, and it is a much larger dependency with a much larger API. And a different Rust approach, building on a lower level protocol crate, gives you control over the wire format at the cost of doing all the game logic yourself. Azalea sits deliberately in the middle, with a high level API over a complete protocol implementation, and the boundary it occupies is the reason to pick it.

Editorial conclusion

Adopt Azalea if you want to write a Minecraft bot or a headless tool in Rust and you are willing to target exactly one game version, since the library explicitly does not support multiple versions at once. Do not adopt it for a client with a rendered world, since graphics are a non-goal and live elsewhere, and treat the anti-cheat goal as a design intention rather than a guarantee. Verify first that the crate version you depend on matches the Minecraft version you intend to play against, that the Bevy plugin API you need is in the current release, and that the specific features you rely on, such as entity pushing or sprint swimming, are not on the unimplemented list.

Frequently asked questions

Official sources

1. azalea-rs/azalea on GitHub
2. Issues
3. License: MIT
4. Project website
5. README