Crate ghast_client 

Headless Minecraft Java Edition client for the ghast library.

• Client: connect (directly or through a SOCKS5 proxy, see ghast_auth::connect), handshake, login (offline; online mode with the microsoft feature), compression and encryption, then the play state: keep-alives, teleports, window confirms, health, respawn, chat.
• A fixed 50 ms tick loop with vanilla 1.8.9’s tick order (see engine for the details): inbound packets → Behavior::tick (actions written immediately) → rotation → movement → exactly one movement packet.
• A version-agnostic API: behaviours see TickContext and the types of common, never packets. The connection is generic over the protocol version (version::ClientVersion), so each supported version is monomorphised.
• Packets nobody needs are dropped before they are decoded; a behaviour opts into more with Behavior::interests.

Supported versions: 1.8.9 (protocol 47) and 1.16.5 (protocol 754).

use ghast_client::{Account, Behavior, Client, GameVersion, Interests, TickContext};

struct Echo;
impl Behavior for Echo {
    fn interests(&self) -> Interests {
        Interests::CHAT
    }
    fn tick(&mut self, ctx: &mut TickContext<'_>) {
        let lines: Vec<String> = ctx.events().chat.iter().map(|m| m.plain()).collect();
        for line in lines {
            println!("chat: {line}");
        }
        if ctx.is_dead() {
            ctx.respawn();
        }
    }
}

let client = Client::new("localhost:25565".parse()?, GameVersion::V1_8_9, Account::offline("Steve")?);
let end = client.run(&mut Echo).await?;
println!("session ended: {end:?}");

Re-exports

pub use common::ChatMessage;

pub use common::ClientSettings;

pub use common::Controls;

pub use common::Face;

pub use common::GameMode;

pub use common::Health;

pub use common::Pose;

pub use common::Vec3;

pub use hands::BlockHit;

pub use hands::Buttons;

pub use version::GameVersion;

pub use ghast_entity as entity;

pub use ghast_inventory as inventory;

pub use ghast_world as world;

Modules

common

The version-agnostic layer: what the client core receives from and sends to the server, independent of the protocol version.

connect

Re-exports of the connection setup types from ghast-auth.

hands

The mouse buttons in the world: digging, placing and using items, ported from 1.8.9 MinecraftClient.tick (doAttack, doUse, handleBlockBreaking) and ClientPlayerInteractionManager (attackBlock, updateBlockBreakingProgress, cancelBlockBreaking, onRightClick, interactItem, stopUsingItem), verified against recorded lab packet traces.

movement

The per-tick movement packet (ClientPlayerEntity.sendMovementPackets, 1.8 and 1.16) and the stand-in mover used until ghast-physics is integrated.

rotation

Rotation in whole mouse counts.

version

Per-version glue between the generated packets of ghast-protocol and the common layer.

Structs

BlockPos

A block position. x/z must fit 26 signed bits, y 12 signed bits to be encodable.

ClickTicket

A click that was sent: match it with TickEvents::inventory’s clicks on a later tick (window id and action number, as the server’s confirm carries them).

Client

A configured client: where to connect, which version, which account, and how.

Idle

A behaviour that does nothing (the player stands still).

Interests

A set of optional packet groups (see the associated constants).

RawInbound

A clientbound play packet copied for the behaviour (Behavior::raw_packets).

TickContext

The behaviour’s view of the client during one tick.

TickEvents

What happened since the behaviour’s previous tick.

Enums

Account

The account a client logs in with.

ClickRefused

Why TickContext::click (or opening / closing a window) sent nothing.

ClientError

A session failed.

ForceStepPosition

Grim compatibility (not vanilla): when to send the position on a tick whose move stayed under vanilla’s 0.03-block resend threshold. See crates/ghast-physics/GRIM_NOTES.md.

SessionEnd

How a session that reached the play state ended without an error.

Constants

TICK

Length of one client tick.

Traits

Behavior

A bot behaviour: the code that decides what the player does each tick.

WorldView

Block access for behaviours, independent of the protocol version.