Azalea是一个用于创建Minecraft机器人的框架。

此页面主要面向已经确定要使用Azalea的开发者。有关Azalea的高级概述，请参阅readme。

安装

首先，使用rustup install nightly和rustup default nightly安装Rust的nightly版本。

然后，使用以下命令之一将Azalea添加到您的项目中

• 最新版（推荐）：cargo add azalea --git=https://github.com/azalea-rs/azalea\
• 最新版“稳定”发布：cargo add azalea

优化

为了加快编译时间，在您的项目中创建一个.cargo/config.toml文件并将此文件复制进去。您可能需要安装LLD链接器。

为了在调试模式下获得更快的性能，将以下代码添加到您的Cargo.toml中

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

文档

最新Azalea crates.io版本的文档可在docs.rs/azalea找到，最新 bleeding-edge (git) 版本的文档在azalea.matdoes.dev。

请注意，azalea 库实际上只是在 azalea_client 的基础上添加了一些额外功能的包装器。因此，一些文档中可能会提到 azalea_client。在您的代码中，只需将这些替换为 azalea，因为 azalea 中重新导出了 azalea_client 的所有内容。

示例

//! 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(())
}

集群

Azalea 允许您创建“集群”，这是在相同世界中执行共同行动的机器人群。请参阅 testbot 以获取示例。此外，如果您正在使用集群，还应使用 use 以下两个 azalea::prelude::* 和 azalea::swarm::prelude::*。

插件

Azalea 在内部使用 Bevy ECS 来存储有关世界和客户端的信息。Bevy 插件比异步处理函数更强大，但使用起来更困难。请参阅 pathfinder 以了解如何创建插件。然后您可以通过在客户端/集群构建器中添加 .add_plugin(ExamplePlugin) 来启用插件。

请注意，尽管某物在 ECS 中是实体，但这并不意味着它是 Minecraft 实体。您可以通过将 With<MinecraftEntityId> 作为过滤器来实现这一点。

请参阅 Bevy Cheatbook 以了解有关 Bevy ECS（以及 ECS 范式）的更多信息。

调试

Azalea 使用了一些相对复杂的 Rust 特性，如果您不熟悉这些特性，可能会使调试某些问题变得更加棘手。

日志记录

日志记录是调试问题最有用的工具之一。默认日志级别为 info，但您可以通过更改日志级别来显示更多信息或更少信息。在 Linux/bash 上启用日志记录使用 RUST_LOG=debug cargo run，在 Windows 上使用 set RUST_LOG=debug && cargo run。日志级别包括 trace、debug、info、warn 和 error，优先级递增。

如果是一个崩溃/恐慌，并且您认为它与解析数据包有关，您可能想将级别设置为 trace，因为它将显示每个接收到的数据包的前几百字节。这可能会生成大量日志，因此请使用 &> azalea.log（在 Linux 上）将其重定向到文件。

注意：如果您收到 SetLoggerError 错误，那是因为您有多个日志记录器。Azalea 默认附带一个日志记录器，有关更多信息，请参阅 bevy_log。您可以通过禁用 log 功能来禁用默认的日志记录插件。

死锁

如果您的代码只是挂起，可能是死锁。将 azalea/examples/testbot.rs 中的死锁块复制到您的代码的开头，如果检测到死锁，它将打印出长回溯。

回溯

回溯也很有用，尽管它们有时难以阅读，并且并不总是包含错误的实际位置。使用 RUST_BACKTRACE=1 运行您的代码以启用完整回溯。如果它非常长，通常通过搜索关键字 "azalea" 帮助您过滤掉不相关的内容，并找到问题的实际来源。