DOCSEARCHbyAlgolia
Submit Docs

azalea

repository·main·Indexed 20 days ago

https://github.com/azalea-rs/azalea

A Rust-based framework for building Minecraft bots and clients, featuring high-fidelity physics, pathfinding, and swarm management. The ecosystem includes specialized crates such as azalea-protocol for packet handling, azalea-client for Bevy-based clients, azalea-auth for authentication, and azalea-brigadier for command parsing.

Tokens
79.4K
Snippets
295
Records
368
Agent score
72%

What's inside azalea

  1. Overview of Azalea

    main

    Azalea is a collection of Rust crates designed for creating Minecraft bots, clients, and tools. It aims to provide an intuitive API that supports vanilla Minecraft capabilities, efficient multi-bot management (Swarms), and accurate physics, all while remaining efficient and avoiding anti-cheat triggers.

    Key Capabilities:

    • Movement & Physics: Accurate physics-based movement and a built-in Pathfinder.
    • Interaction: Breaking blocks (mine), block interaction/building (block_interact), and attacking entities (attack).
    • Management: Support for Swarms (multiple bots working together) and Inventory management.
    • Extensibility: Support for Bevy plugins to extend functionality.

    Important Limitations:

    • Does not support Bedrock edition.
    • Does not include graphics (it is a headless framework).
    • Does not support multiple Minecraft versions simultaneously (unless using the azalea-viaversion plugin).
    • Many parts are still unfinished and subject to breaking changes.

  3. Use `azalea-protocol` for Minecraft packet handling

    main

    azalea-protocol is a low-level crate designed for sending and receiving Minecraft packets. It is intended for use when you need direct control over the protocol layer. Note that this crate only supports the latest Minecraft version.

    For high-level usage and connection management, refer to crate::connect::Connection instead.

  6. What is `azalea-buf`?

    main

    azalea-buf is an implementation of Minecraft's FriendlyByteBuf. It is used for the serialization and deserialization of data, which is a frequent requirement when interacting with Minecraft protocols.

    Note on implementation differences: azalea-buf uses unsigned integers in certain places where vanilla Minecraft uses signed integers. While this typically does not cause functional issues, it means that azalea-buf usage is technically detectable by servers, as it may not trigger errors in scenarios where a vanilla Minecraft client would.

  7. Extend Azalea with Bevy plugins

    main

    Azalea supports Bevy plugins, which allow you to significantly alter or enhance the bot's functionality.

    Useful existing plugins include:

    • azalea-viaversion: Provides multi-version compatibility using ViaProxy.
    • azalea-hax: Provides anti-knockback capabilities.

  9. Use Swarms to manage groups of bots

    main

    Swarms allow you to create a group of bots in the same world that can perform coordinated actions. When working with swarms, you should import both the standard prelude and the swarm prelude:

    use azalea::prelude::*;
use azalea::swarm::prelude::*;
    use azalea::prelude::*;
use azalea::swarm::prelude::*;

  10. Implement bot logic as a Bevy plugin for performance

    main
    If your bot code interacts heavily with the system, implementing your logic as a Bevy plugin can improve performance. This allows your code to run in parallel with Azalea's internal systems and helps avoid unnecessary clones and locks. Avoid accessing the Client directly from within the plugin if possible, as this often requires spawning new threads or tasks, which can negate the performance benefits.

  11. Understand Minecraft registries in Azalea

    main

    Azalea uses a registry system to provide identifiers for Minecraft enums. Registries are categorized into two types based on how they are populated:

    1. Static Registries: Defined in crate::builtin, these are static for both the client and the server. Examples include blocks and items.
    2. Data Registries: Defined in crate::data, these are sent to the client by the server. Examples include enchantments and biomes.

  12. Avoid concurrency issues with `tokio::task::spawn_local`

    main

    When spawning tasks that move a bot into them, do not use tokio::spawn. Using tokio::spawn can cause the handler or Minecraft ticks to run at unexpected moments, breaking assumptions like bot.ticks_connected() == bot.ticks_connected().

    Instead, use tokio::task::spawn_local. Alternatively, you can mark your main function with #[tokio::main(flavor = "current_thread")].

    Note: This does not apply if you are spawning tasks inside ECS systems; for that, use TokioRuntimeHandle.

    tokio::task::spawn_local(async move {
    // bot logic here
});