Crate azalea

Expand description

Azalea is a framework for creating Minecraft bots.

This page is primarily meant for developers that already know they want to use Azalea. See the readme for a higher-level overview of Azalea.

§Installation

First, install Rust nightly with rustup install nightly and rustup default nightly.

Then, use one of the following commands to add Azalea to your project:

Latest bleeding-edge version (recommended): cargo add azalea --git=https://github.com/azalea-rs/azalea\
Latest “stable” release: cargo add azalea

§Optimization

For faster compile times, make a .cargo/config.toml file in your project and copy this file into it. You may have to install the LLD linker.

For faster performance in debug mode, add the following code to your Cargo.toml:

[profile.dev]
opt-level = 1
[profile.dev.package."*"]
opt-level = 3

§Documentation

The documentation for the latest Azalea crates.io release is available at docs.rs/azalea and the docs for the latest bleeding-edge (git) version are at azalea.matdoes.dev.

Note that the azalea crate is technically just a wrapper over azalea_client that adds some extra functions. Because of this, some of the documentation will refer to azalea_client. You can just replace these with azalea in your code since everything from azalea_client is re-exported in azalea.

§Examples

//! A bot that logs chat messages sent in the server to the console.

use azalea::prelude::*;
use parking_lot::Mutex;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let account = Account::offline("bot");
    // or Account::microsoft("[email protected]").await.unwrap();

    ClientBuilder::new()
        .set_handler(handle)
        .start(account, "localhost")
        .await
        .unwrap();
}

#[derive(Default, Clone, Component)]
pub struct State {}

async fn handle(bot: Client, event: Event, state: State) -> anyhow::Result<()> {
    match event {
        Event::Chat(m) => {
            println!("{}", m.message().to_ansi());
        }
        _ => {}
    }

    Ok(())
}

§Swarms

Azalea lets you create “swarms”, which are a group of bots in the same world that can perform actions together. See testbot for an example. Also, if you’re using swarms, you should also use both azalea::prelude::* and azalea::swarm::prelude::*.

§Plugins

Azalea uses Bevy ECS internally to store information about the world and clients. Bevy plugins are more powerful than async handler functions, but more difficult to use. See pathfinder as an example of how to make a plugin. You can then enable a plugin by adding .add_plugin(ExamplePlugin) in your client/swarm builder.

Also note that just because something is an entity in the ECS doesn’t mean that it’s a Minecraft entity. You can filter for that by having With<MinecraftEntityId> as a filter.

See the Bevy Cheatbook to learn more about Bevy ECS (and the ECS paradigm in general).

§Debugging

Azalea uses several relatively complex features of Rust, which may make debugging certain issues more tricky if you’re not familiar with them.

§Logging

One of the most useful tools for debugging issues is logging. The default log level is info, but you can make it show more or less information by changing the log level. Enabling logging is done with RUST_LOG=debug cargo run on Linux/bash or set RUST_LOG=debug && cargo run on Windows. The log levels are trace, debug, info, warn, and error, in ascending priority.

If it’s a crash/panic and you believe it has to do with parsing a packet, you might want to set the level to trace since that’ll make it show the first few hundred bytes of every packet received. This may produce a lot of logs, so use a command like RUST_LOG=trace NO_COLOR=1 cargo run &> azalea.log to nicely pipe it into a file (on Linux).

Note: If you get a SetLoggerError, it’s because you have multiple loggers. Azalea comes with a logger by default, see bevy_log for more information. You can disable the default logging plugin by disabling the log feature.

§Deadlocks

If your code is simply hanging, it might be a deadlock. Enable parking_lot’s deadlock_detection feature and copy the deadlock block in azalea/examples/testbot.rs to the beginning of your code and it’ll print a long backtrace if a deadlock is detected.

§Backtraces

Backtraces are also useful, though they’re sometimes hard to read and don’t always contain the actual location of the error. Run your code with RUST_BACKTRACE=1 to enable full backtraces. If it’s very long, often searching for the keyword “azalea” will help you filter out unrelated things and find the actual source of the issue.

Re-exports§

pub use azalea_auth as auth;
pub use azalea_block as blocks;
pub use azalea_brigadier as brigadier;
pub use azalea_buf as buf;
pub use azalea_core as core;
pub use azalea_entity as entity;
pub use azalea_physics as physics;
pub use azalea_protocol as protocol;
pub use azalea_registry as registry;
pub use azalea_world as world;
pub use bevy_app as app;
pub use bevy_ecs as ecs;

Modules§

accept_resource_packs
attack
auto_respawn
auto_tool
brand
chat: Implementations of chat-related features.
chunks: Used for Minecraft’s chunk batching introduced in 23w31a (1.20.2). It’s used for making the server spread out how often it sends us chunk packets depending on our receiving speed.
container
disconnect: Disconnect a client from the server.
events: Defines the Event enum and makes those events trigger when they’re sent in the ECS.
interact
inventory
mining
movement
nearest_entity
packet
pathfinder: A pathfinding plugin to make bots able to traverse the world.
ping: Ping Minecraft servers.
pong
prelude: The Azalea prelude. Things that are necessary for a bare-bones bot are re-exported here.
raw_connection
respawn
swarm: Swarms are a way to conveniently control many bots.
task_pool: Borrowed from bevy_core.
tick_end: Clients send a ServerboundClientTickEnd packet every tick.

Macros§

declare_packet_handlers

Structs§

Account: Something that can join Minecraft servers.
BlockPos: The coordinates of a block in the world. For entities (if the coordinate have decimals), use Vec3 instead.
Bot: A component that clients with BotPlugin will have. If you just want to check if an entity is one of our bots, you should use LocalEntity.
BotPlugin
Client: Client has the things that a user interacting with the library will want.
ClientBuilder: A builder for creating new Clients. This is the recommended way of making Azalea bots.
ClientInformation: A component that contains some of the “settings” for this client that are sent to the server, such as render distance. This is only present on local players.
DefaultBotPlugins: A [PluginGroup] for the plugins that add extra bot functionality to the client.
DefaultPlugins: This plugin group will add all the default plugins necessary for Azalea to work.
GameProfileComponent: A component only present in players that contains the GameProfile (which you can use to get a player’s name).
Hunger
InConfigState: A marker component for local players that are currently in the configuration state.
InGameState: A marker component for local players that are currently in the game state.
InstanceHolder: A component that keeps strong references to our PartialInstance and Instance for local players.
JoinOpts: Optional settings when adding an account to a swarm or client.
JoinedClientBundle: A bundle for the components that are present on a local player that is currently in the game protocol state. If you want to filter for this, use InGameState.
JumpEvent: Event to jump once.
LocalPlayerBundle: The bundle of components that’s shared when we’re either in the configuration or game state.
LookAtEvent: Make an entity look towards a certain position in the world.
NoState: A marker that can be used in place of a State in ClientBuilder or SwarmBuilder. You probably don’t need to use this manually since the compiler will infer it for you.
PhysicsState: Component for entities that can move and sprint. Usually only in LocalEntitys.
PlayerInfo: A player in the tab list.
ResourceLocation
StartClientOpts
StartSprintEvent: An event sent when the client starts sprinting. This does not get sent for non-local entities.
StartWalkEvent: An event sent when the client starts walking. This does not get sent for non-local entities.
TabList: A component that contains a map of player UUIDs to their information in the tab list.
TickBroadcast: A resource that contains a [broadcast::Sender] that will be sent every Minecraft tick.
Vec3: Used to represent an exact position in the world where an entity could be.

Enums§

AccountOpts: The parameters that were passed for creating the associated Account.
Event: Something that happened in-game, such as a tick passing or chat message being sent.
FormattedText: A chat component, basically anything you can see in chat.
JoinError: An error that happened while joining the server.
SprintDirection: The directions that we can sprint in. It’s a subset of WalkDirection.
StartError
WalkDirection

Traits§

BotClientExt

Functions§

direction_looking_at: Return the look direction that would make a client at current be looking at target.
jump_listener

Type Aliases§

BoxHandleFn
HandleFn

Crate azaleaCopy item path