Struct Client 

pub struct Client {
    pub entity: Entity,
    pub ecs: Arc<Mutex<RawMutex, World>>,
}

A Minecraft client instance that can interact with the world.

To make a new client, use either azalea::ClientBuilder or Client::join.

Note that Client is inaccessible from systems (i.e. plugins), but you can achieve everything that client can do with ECS events.

Fields

entity: Entity

The entity for this client in the ECS.

ecs: Arc<Mutex<RawMutex, World>>

A mutually exclusive reference to the entity component system (ECS).

You probably don’t need to access this directly. Note that if you’re using a shared world (i.e. a swarm), the ECS will contain all entities in all instances/dimensions.

Implementations

impl Client

pub fn new(entity: Entity, ecs: Arc<Mutex<RawMutex, World>>) -> Client

Create a new client from the given GameProfile, ECS Entity, ECS World, and schedule runner function. You should only use this if you want to change these fields from the defaults, otherwise use Client::join.

pub async fn join( account: Account, address: impl TryInto<ServerAddress>, ) -> Result<(Client, UnboundedReceiver<Event>), JoinError>

Connect to a Minecraft server.

To change the render distance and other settings, use Client::set_client_information. To watch for events like packets sent by the server, use the rx variable this function returns.

Examples

use azalea_client::{Account, Client};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let account = Account::offline("bot");
    let (client, rx) = Client::join(account, "localhost").await?;
    client.chat("Hello, world!");
    client.disconnect();
    Ok(())
}

pub async fn join_with_proxy( account: Account, address: impl TryInto<ServerAddress>, proxy: Proxy, ) -> Result<(Client, UnboundedReceiver<Event>), JoinError>

pub async fn start_client(__arg0: StartClientOpts) -> Client

Create a Client when you already have the ECS made with [start_ecs_runner]. You’d usually want to use Self::join instead.

pub fn write_packet(&self, packet: impl Packet<ServerboundGamePacket>)

Write a packet directly to the server.

pub fn disconnect(&self)

Disconnect this client from the server by ending all tasks.

The OwnedReadHalf for the TCP connection is in one of the tasks, so it automatically closes the connection when that’s dropped.

pub fn with_raw_connection<R>(&self, f: impl FnOnce(&RawConnection) -> R) -> R

pub fn with_raw_connection_mut<R>( &self, f: impl FnOnce(Mut<'_, RawConnection>) -> R, ) -> R

pub fn component<T>(&self) -> T

where T: Component + Clone,

Get a component from this client. This will clone the component and return it.

If the component can’t be cloned, try Self::query_self instead. If it isn’t guaranteed to be present, you can use Self::get_component or Self::query_self.

You may also use Self::ecs directly if you need more control over when the ECS is locked.

Panics

This will panic if the component doesn’t exist on the client.

Examples

let world_name = client.component::<InstanceName>();

pub fn get_component<T>(&self) -> Option<T>

where T: Component + Clone,

Get a component from this client, or None if it doesn’t exist.

If the component can’t be cloned, consider using Self::query_self with Option<&T> instead.

You may also have to use Self::query_self directly.

pub fn resource<T>(&self) -> T

where T: Resource + Clone,

Get a resource from the ECS. This will clone the resource and return it.

pub fn map_resource<T, R>(&self, f: impl FnOnce(&T) -> R) -> R

where T: Resource,

Get a required ECS resource and call the given function with it.

pub fn map_get_resource<T, R>(&self, f: impl FnOnce(Option<&T>) -> R) -> R

where T: Resource,

Get an optional ECS resource and call the given function with it.

pub fn world(&self) -> Arc<RwLock<RawRwLock, Instance>>

Get an RwLock with a reference to our (potentially shared) world.

This gets the Instance from the client’s InstanceHolder component. If it’s a normal client, then it’ll be the same as the world the client has loaded. If the client is using a shared world, then the shared world will be a superset of the client’s world.

pub fn partial_world(&self) -> Arc<RwLock<RawRwLock, PartialInstance>>

Get an RwLock with a reference to the world that this client has loaded.

let world = client.partial_world();
let is_0_0_loaded = world.read().chunks.limited_get(&ChunkPos::new(0, 0)).is_some();

pub fn logged_in(&self) -> bool

Returns whether we have a received the login packet yet.

impl Client

pub fn position(&self) -> Vec3

Get the position of this client.

This is a shortcut for Vec3::from(&bot.component::<Position>()).

Note that this value is given a default of Vec3::ZERO when it receives the login packet, its true position may be set ticks later.

pub fn dimensions(&self) -> EntityDimensions

Get the bounding box dimensions for our client, which contains our width, height, and eye height.

This is a shortcut for self.component::<EntityDimensions>().

pub fn eye_position(&self) -> Vec3

Get the position of this client’s eyes.

This is a shortcut for bot.position().up(bot.dimensions().eye_height).

pub fn health(&self) -> f32

Get the health of this client.

This is a shortcut for *bot.component::<Health>().

pub fn hunger(&self) -> Hunger

Get the hunger level of this client, which includes both food and saturation.

This is a shortcut for self.component::<Hunger>().to_owned().

pub fn username(&self) -> String

Get the username of this client.

This is a shortcut for bot.component::<GameProfileComponent>().name.to_owned().

pub fn uuid(&self) -> Uuid

Get the Minecraft UUID of this client.

This is a shortcut for bot.component::<GameProfileComponent>().uuid.

pub fn tab_list(&self) -> HashMap<Uuid, PlayerInfo>

Get a map of player UUIDs to their information in the tab list.

This is a shortcut for *bot.component::<TabList>().

pub fn profile(&self) -> GameProfile

Returns the GameProfile for our client. This contains your username, UUID, and skin data.

These values are set by the server upon login, which means they might not match up with your actual game profile. Also, note that the username and skin that gets displayed in-game will actually be the ones from the tab list, which you can get from Self::tab_list.

This as also available from the ECS as GameProfileComponent.

pub fn player_uuid_by_username(&self, username: &str) -> Option<Uuid>

A convenience function to get the Minecraft Uuid of a player by their username, if they’re present in the tab list.

You can chain this with Client::entity_by_uuid to get the ECS Entity for the player.

pub fn entity_by_uuid(&self, uuid: Uuid) -> Option<Entity>

Get an ECS Entity in the world by its Minecraft UUID, if it’s within render distance.

pub fn minecraft_entity_by_ecs_entity( &self, entity: Entity, ) -> Option<MinecraftEntityId>

Convert an ECS Entity to a MinecraftEntityId.

pub fn ecs_entity_by_minecraft_entity( &self, entity: MinecraftEntityId, ) -> Option<Entity>

Convert a MinecraftEntityId to an ECS Entity.

pub fn with_registry_holder<R>(&self, f: impl FnOnce(&RegistryHolder) -> R) -> R

Call the given function with the client’s RegistryHolder.

The player’s instance (aka world) will be locked during this time, which may result in a deadlock if you try to access the instance again while in the function.

pub fn resolve_registry_name( &self, registry: &impl ResolvableDataRegistry, ) -> Option<ResourceLocation>

Resolve the given registry to its name.

This is necessary for data-driven registries like Enchantment.

pub fn with_resolved_registry<R>( &self, registry: impl ResolvableDataRegistry, f: impl FnOnce(&ResourceLocation, &NbtCompound) -> R, ) -> Option<R>

Resolve the given registry to its name and data and call the given function with it.

This is necessary for data-driven registries like Enchantment.

If you just want the value name, use Self::resolve_registry_name instead.

impl Client

pub fn query_self<D, R>( &self, f: impl FnOnce(<D as QueryData>::Item<'_, '_>) -> R, ) -> R

where D: QueryData,

A convenience function for getting components from our client’s entity.

To query another entity, you can use Self::query_entity.

Examples

let is_logged_in = client.query_self::<Option<&InstanceName>, _>(|ins| ins.is_some());

Panics

This will panic if the component doesn’t exist on the client.

pub fn query_entity<D, R>( &self, entity: Entity, f: impl FnOnce(<D as QueryData>::Item<'_, '_>) -> R, ) -> R

where D: QueryData,

A convenience function for getting components from any entity.

If you’re querying the client, you should use Self::query_self.

Panics

This will panic if the entity doesn’t exist or if the query isn’t valid for the entity. For a non-panicking version, you may use Self::try_query_entity.

pub fn try_query_entity<D, R>( &self, entity: Entity, f: impl FnOnce(<D as QueryData>::Item<'_, '_>) -> R, ) -> Result<R, QueryEntityError>

where D: QueryData,

A convenience function for getting components from any entity, or None if the query fails.

If you’re sure that the entity exists and that the query will succeed, you can use Self::query_entity.

pub fn any_entity_by<Q, F>( &self, predicate: impl EntityPredicate<Q, F>, ) -> Option<Entity>

where Q: QueryData, F: QueryFilter,

Quickly returns a lightweight Entity for an arbitrary entity that matches the given predicate function that is in the same Instance as the client.

You can then use Self::entity_component to get components from this entity.

If you want to find the nearest entity, consider using Self::nearest_entity_by instead. If you want to find all entities that match the predicate, use Self::nearest_entities_by.

Example

use azalea_client::{Client, player::GameProfileComponent};
use azalea_entity::{Position, metadata::Player};
use bevy_ecs::query::With;

let entity = bot.any_entity_by::<&GameProfileComponent, With<Player>>(
    |profile: &GameProfileComponent| profile.name == sender_name,
);
if let Some(entity) = entity {
    let position = bot.entity_component::<Position>(entity);
    // ...
}

pub fn nearest_entity_by<Q, F>( &self, predicate: impl EntityPredicate<Q, F>, ) -> Option<Entity>

where Q: QueryData, F: QueryFilter,

Return a lightweight Entity for the nearest entity that matches the given predicate function.

You can then use Self::entity_component to get components from this entity.

If you don’t need the entity to be the nearest one, it may be more efficient to use Self::any_entity_by instead. You can also use Self::nearest_entities_by to get all nearby entities.

use azalea_entity::{LocalEntity, Position, metadata::Player};
use bevy_ecs::query::{With, Without};

// get the position of the nearest player
if let Some(nearest_player) =
    bot.nearest_entity_by::<(), (With<Player>, Without<LocalEntity>)>(|_: ()| true)
{
    let nearest_player_pos = *bot.entity_component::<Position>(nearest_player);
    bot.chat(format!("You are at {nearest_player_pos}"));
}

pub fn nearest_entities_by<Q, F>( &self, predicate: impl EntityPredicate<Q, F>, ) -> Vec<Entity>

where Q: QueryData, F: QueryFilter,

Similar to Self::nearest_entity_by but returns a Vec<Entity> of all entities in our instance that match the predicate.

The first entity is the nearest one.

let nearby_players =
    bot.nearest_entities_by::<(), (With<Player>, Without<LocalEntity>)>(|_: ()| true);

pub fn entity_component<Q>(&self, entity: Entity) -> Q

where Q: Component + Clone,

Get a component from an entity.

Note that this will return an owned type (i.e. not a reference) so it may be expensive for larger types.

If you’re trying to get a component for this client, use Self::component.

pub fn get_entity_component<Q>(&self, entity: Entity) -> Option<Q>

where Q: Component + Clone,

Get a component from an entity, if it exists.

This is similar to Self::entity_component but returns an Option instead of panicking if the component isn’t present.

impl Client

pub fn attack(&self, entity: Entity)

Attack an entity in the world.

This doesn’t automatically look at the entity or perform any range/visibility checks, so it might trigger anticheats.

pub fn has_attack_cooldown(&self) -> bool

Whether the player has an attack cooldown.

Also see Client::attack_cooldown_remaining_ticks.

pub fn attack_cooldown_remaining_ticks(&self) -> usize

Returns the number of ticks until we can attack at full strength again.

Also see Client::has_attack_cooldown.

impl Client

pub fn write_chat_packet(&self, message: &str)

Send a chat message to the server.

This only sends the chat packet and not the command packet, which means on some servers you can use this to send chat messages that start with a /. The Client::chat function handles checking whether the message is a command and using the proper packet for you, so you should use that instead.

pub fn write_command_packet(&self, command: &str)

Send a command packet to the server. The command argument should not include the slash at the front.

You can also just use Client::chat and start your message with a / to send a command.

pub fn chat(&self, content: impl Into<String>)

Send a message in chat.

bot.chat("Hello, world!");

impl Client

pub fn set_client_information(&self, client_information: ClientInformation)

Tell the server we changed our game options (i.e. render distance, main hand).

If this is not set before the login packet, the default will be sent.

bot.set_client_information(ClientInformation {
    view_distance: 2,
    ..Default::default()
});

impl Client

pub fn block_interact(&self, position: BlockPos)

Right-click a block.

The behavior of this depends on the target block, and it’ll either place the block you’re holding in your hand or use the block you clicked (like toggling a lever).

Note that this may trigger anticheats as it doesn’t take into account whether you’re actually looking at the block.

pub fn entity_interact(&self, entity: Entity)

Right-click an entity.

This can click through walls, which may trigger anticheats. If that behavior isn’t desired, consider using Client::start_use_item instead.

pub fn start_use_item(&self)

Right-click the currently held item.

If the item is consumable, then it’ll act as if right-click was held until the item finishes being consumed. You can use this to eat food.

If we’re looking at a block or entity, then it will be clicked. Also see Client::block_interact and Client::entity_interact.

impl Client

pub fn menu(&self) -> Menu

Return the menu that is currently open, or the player’s inventory if no menu is open.

pub fn selected_hotbar_slot(&self) -> u8

Returns the index of the hotbar slot that’s currently selected.

If you want to access the actual held item, you can get the current menu with Client::menu and then get the slot index by offsetting from the start of azalea_inventory::Menu::hotbar_slots_range.

You can use Self::set_selected_hotbar_slot to change it.

pub fn set_selected_hotbar_slot(&self, new_hotbar_slot_index: u8)

Update the selected hotbar slot index.

This will run next Update, so you might want to call bot.wait_updates(1) after calling this if you’re using azalea.

Panics

This will panic if new_hotbar_slot_index is not in the range 0..=8.

impl Client

pub fn start_mining(&self, position: BlockPos)

pub fn left_click_mine(&self, enabled: bool)

When enabled, the bot will mine any block that it is looking at if it is reachable.

impl Client

pub fn set_jumping(&self, jumping: bool)

Set whether we’re jumping. This acts as if you held space in vanilla.

If you want to jump once, use the jump function in azalea.

If you’re making a realistic client, calling this function every tick is recommended.

pub fn jumping(&self) -> bool

Returns whether the player will try to jump next tick.

pub fn set_crouching(&self, crouching: bool)

pub fn crouching(&self) -> bool

Whether the client is currently trying to sneak.

You may want to check the Pose instead.

pub fn set_direction(&self, y_rot: f32, x_rot: f32)

Sets the direction the client is looking.

y_rot is yaw (looking to the side, between -180 to 180), and x_rot is pitch (looking up and down, between -90 to 90).

You can get these numbers from the vanilla f3 screen.

pub fn direction(&self) -> (f32, f32)

Returns the direction the client is looking.

See Self::set_direction for more details.

impl Client

pub fn walk(&self, direction: WalkDirection)

Start walking in the given direction.

To sprint, use Client::sprint. To stop walking, call walk with WalkDirection::None.

Example

// walk for one second
bot.walk(WalkDirection::Forward);
tokio::time::sleep(Duration::from_secs(1)).await;
bot.walk(WalkDirection::None);

pub fn sprint(&self, direction: SprintDirection)

Start sprinting in the given direction.

o stop moving, call bot.walk(WalkDirection::None)

Example

// sprint for one second
bot.sprint(SprintDirection::Forward);
tokio::time::sleep(Duration::from_secs(1)).await;
bot.walk(WalkDirection::None);

Trait Implementations

impl AutoToolClientExt for Client

fn best_tool_in_hotbar_for_block(&self, block: BlockState) -> BestToolResult

async fn mine_with_auto_tool(&self, block_pos: BlockPos)

impl BotClientExt for Client

fn get_tick_broadcaster(&self) -> Receiver<()>

Returns a Receiver that receives a message every game tick.

This is useful if you want to efficiently loop until a certain condition is met.

let mut ticks = bot.get_tick_broadcaster();
while ticks.recv().await.is_ok() {
    let ecs = bot.ecs.lock();
    if ecs.get::<WaitingForInventoryOpen>(bot.entity).is_none() {
        break;
    }
}

fn get_update_broadcaster(&self) -> Receiver<()>

Returns a Receiver that receives a message every ECS Update.

ECS Updates happen at least at the frequency of game ticks, usually faster.

This is useful if you’re sending an ECS event and want to make sure it’s been handled before continuing.

async fn wait_ticks(&self, n: usize)

Wait for the specified number of ticks using Self::get_tick_broadcaster.

If you’re going to run this in a loop, you may want to use that function instead and use the Receiver from it to avoid accidentally skipping ticks and having to wait longer.

async fn wait_updates(&self, n: usize)

Waits for the specified number of ECS Updates using Self::get_update_broadcaster.

These are basically equivalent to frames because even though we have no rendering, some game mechanics depend on frames.

If you’re going to run this in a loop, you may want to use that function instead and use the Receiver from it to avoid accidentally skipping ticks and having to wait longer.

fn jump(&self)

Queue a jump for the next tick.

fn look_at(&self, position: Vec3)

Turn the bot’s head to look at the coordinate in the world.

async fn mine(&self, position: BlockPos)

Mine a block.

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContainerClientExt for Client

async fn open_container_at( &self, pos: BlockPos, timeout_ticks: Option<usize>, ) -> Option<ContainerHandle>

Open a container in the world, like a chest.

async fn wait_for_container_open( &self, timeout_ticks: Option<usize>, ) -> Option<ContainerHandle>

Wait until a container is open, up to the specified number of ticks.

fn open_inventory(&self) -> Option<ContainerHandle>

Open the player’s inventory.

fn get_inventory(&self) -> ContainerHandleRef

Returns a ContainerHandleRef to the client’s currently open container, or their inventory.

fn get_held_item(&self) -> ItemStack

Get the item in the bot’s hotbar that is currently being held in its main hand.

impl PathfinderClientExt for Client

async fn goto(&self, goal: impl Goal + 'static)

Pathfind to the given goal and wait until either the target is reached or the pathfinding is canceled.

async fn goto_with_opts(&self, goal: impl Goal + 'static, opts: PathfinderOpts)

Same as Self::goto, but allows you to set custom options for pathfinding, including disabling mining and setting custom moves.

fn start_goto(&self, goal: impl Goal + 'static)

Start pathfinding to a given goal.

fn start_goto_with_opts(&self, goal: impl Goal + 'static, opts: PathfinderOpts)

Same as Self::start_goto, but allows you to set custom options for pathfinding, including disabling mining and setting custom moves.

fn stop_pathfinding(&self)

Stop calculating a path, and stop moving once the current movement is finished.

fn force_stop_pathfinding(&self)

Stop calculating a path and stop executing the current movement immediately.

async fn wait_until_goto_target_reached(&self)

Waits forever until the bot no longer has a pathfinder goal.

fn is_goto_target_reached(&self) -> bool

Returns true if the pathfinder has no active goal and isn’t calculating a path.