Azalea

A collection of Rust crates for making Minecraft bots, clients, and tools.

Currently supported Minecraft version: 1.21.10.

Warning

Many parts of Azalea are still unfinished and will receive breaking changes in the future. Most breaking changes will be listed in the changelog.

Features

• Accurate physics (but some features like entity pushing and elytras aren't implemented yet)
• Pathfinder
• Swarms
• Breaking blocks
• Block interactions & building (this doesn't predict the block interactions/placement on the client yet, but it's usually fine)
• Inventories
• Attacking entities
• Plugins

Graphics

Azalea includes an experimental graphics client (azalea-graphics) that provides Vulkan-based rendering for visual debugging and development.

Prerequisites

• Vulkan-compatible graphics driver
• Python 3.7+ with requests package (for asset extraction)

Generating Assets

Before running the graphics client, you need to extract Minecraft assets:

# Install required Python dependency
pip install requests

# Extract assets
cd codegen
python genassets.py

This will download the Minecraft client JAR and extract all assets (textures, models, blockstates, etc.) to azalea-graphics/assets/.

Running the Graphics Client

# Run with default server (localhost:25565)
cargo run --example testbot

# Run with custom port
cargo run --example testbot -- 25566

# Run with custom server address
cargo run --example testbot -- "myserver.com:25565"

The graphics client supports:

• Real-time chunk rendering with biome-accurate colors
• Block state visualization
• Texture mapping and colormap support (grass, foliage)
• Camera controls for navigation

Current Limitations

The graphics client is experimental and has several limitations:

• Entities: Players, mobs, and other entities are not rendered
• Block colors: Not all blocks have block colors implemented, and most are still broken.
• Block geometry: Simple cube rendering only - no proper rotation, UV mapping, or complex models
• Special blocks: No support for animated or special rendering (water, lava, transparent blocks, connected textures)
• Lighting: No dynamic lighting or shadows
• Particles: No particle effects

Some blocks may appear with incorrect textures or orientations due to these limitations.

Note

The graphics client is experimental and primarily intended for development and debugging purposes.

Docs

The "stable" documentation is available at docs.rs/azalea and the unstable docs are at azalea.matdoes.dev (recommended).

Matrix/Discord

If you'd like to chat about Azalea, you can join the Matrix space at #azalea:matdoes.dev (recommended) or the Discord server at discord.gg/FaRey6ytmC (they're bridged so you don't need to join both).

Goals

• Do everything a vanilla client can do.
• Be intuitive and easy to use.
• Make it easy to have many bots working at the same time.
• Don't trigger anticheats.
• Support the latest Minecraft version.
• Be fast and memory efficient.

Non-goals

• Supporting several versions of Minecraft on the same branch*.
• Bedrock edition.

Real-world bots using Azalea

Here's an incomplete list of bots built using Azalea, primarily intended as a reference in addition to the existing documentation and examples:

• ShayBox/ShaysBot - Pearl stasis bot featuring a Discord bot, an HTTP API, and more.
• EnderKill98/statis-bot - This bot can automatically detect thrown pearls and later walk there and pull them for you.
• as1100k/aether - Collection of Minecraft bots and plugins.
• mat-1/potato-bot-2 - Hardened Discord chat bridge created for the LiveOverflow SMP.
• ErrorNoInternet/ErrorNoWatcher - A Minecraft bot with Lua scripting support.

You can see more projects built with Azalea in the GitHub dependency graph.

Plugins

Azalea has support for Bevy plugins, which can significantly alter its functionality. Here are some plugins that you may find useful:

• azalea-rs/azalea-viaversion - Multi-version compatibility for your Azalea bots using ViaProxy.
• azalea-rs/azalea-hax - Anti-knockback.

If you've created your own plugin for Azalea, please create a PR to add it to this list :).

Funding

Azalea is currently maintained primarily by one person (mat) as a hobby project. If you appreciate Azalea, consider donating on Ko-fi.

FAQ

• There's too many console messages, how do I disable them?

  You can disable all console messages by setting the RUST_LOG environment variable to off, or you can filter log messages by setting specific log levels. For example, to disable only pathfinding logs, you can set RUST_LOG=azalea::pathfinder=off.

  See the env_logger crate documentation for more information.