ghast-protocol 0.4.0

Minecraft Java Edition network protocol for the ghast client library: generated per-version packets, framing, compression, encryption, NBT
Documentation

ghast-protocol

Minecraft Java Edition network protocol for the ghast client library: generated packet types per protocol version, framing, compression, encryption, NBT. No game logic.

Module / feature What it is
v1_8 (feature v1_8) Protocol 47 (1.8 – 1.8.9)
v1_12_2 (feature v1_12_2) Protocol 340 (1.12.2)
v1_16_5 (feature v1_16_5) Protocol 754 (1.16.4 – 1.16.5)
v26_1 (feature v26_1) Protocol 775 (26.1 – 26.1.2), with the configuration state
defs every generated definition once, shared by the versions whose code for it is identical (see below)
versions the protocol table: number → module, feature, game versions, layout, configuration state
codec Reader (bounds-checked, zero-copy over Bytes), McWrite, VarInt/VarLong, Decode/Encode
types BlockPos (both bit layouts), slots (slot::legacy 1.8–1.12, slot::modern 1.13.2–1.20.4), Holder/HolderSet (registry id or inline value), LpVec3 (1.21.9+ velocity), chunk (26.1 chunk sections and paletted containers, zero-copy), angle/fixed-point helpers
nbt RawNbt (named root, up to 1.20.1) and AnonNbt (unnamed root, 1.20.2+): validated raw bytes, lazily parsed; NamedTag/Tag tree, Modified UTF-8
chat JSON chat stays a raw string (to_plain_text/parse with feature chat-json); NBT chat (1.20.3+) is AnonNbt (nbt_to_plain_text)
frame FrameDecoder/FrameEncoder: length prefix, zlib, CFB8 hook, PacketFilter
crypto AES-128-CFB8 (Cfb8Encryptor, batched Cfb8Decryptor)
io (feature tokio) FramedReader/FramedWriter over AsyncRead/AsyncWrite halves
feature libdeflate (default) whole-packet inflate/deflate with libdeflate; off = pure Rust (flate2 + zlib-rs)
feature testgen random value generators for every type (test support)

Using it (client side)

use ghast_protocol::{FramedReader, FramedWriter, PacketFilter, PacketSet};
use ghast_protocol::v1_8::{self, play::clientbound::{self as cb, ClientboundPlayPacket}};

let (rd, wr) = tcp.into_split();
let mut reader = FramedReader::new(rd);
let mut writer = FramedWriter::new(wr);

// Login: after Set Compression (login::clientbound::Compress) call on both halves
reader.decoder().set_compression(threshold);
writer.encoder().set_compression(threshold);
// after sending the encryption response (secret from ghast-auth):
writer.encoder().enable_encryption(&secret);
reader.decoder().enable_encryption(&secret);

// Play: drop what the bot does not need before it is decoded (or even inflated).
reader.decoder().set_filter(
    PacketFilter::all().without(cb::id::PLAYER_INFO).without(cb::id::WORLD_PARTICLES),
);
while let Some(raw) = reader.read_packet().await? {
    match raw.id {
        cb::id::KEEP_ALIVE => { let p: cb::KeepAlive = raw.decode_as()?; /* ... */ }
        _ => match ClientboundPlayPacket::decode_raw(&raw)? { /* ... */ _ => {} },
    }
}
// One tick: queue the actions and the movement packet, then write them in one syscall.
writer.queue(&v1_8::play::serverbound::KeepAlive { keep_alive_id: 1 })?;
writer.flush().await?;

Since 1.20.2 (here: v26_1) a configuration state sits between login and play: after login::clientbound::Success the client sends LoginAcknowledged and switches to configuration (answer SelectKnownPacks, KeepAlive, Ping; finish with FinishConfiguration), and a server can send play StartConfiguration at any time, which the client answers with ConfigurationAcknowledged before switching back. examples/login_26_1.rs is a complete, minimal client loop.

Each generated module has, per state and direction: one struct per packet (implementing Packet, Decode, Encode), an enum of all packets (ClientboundPlayPacket, …, implementing PacketSet), and id::* constants. V1_8 / V1_16_5 implement Version (protocol number, position layout, the seven packet-set enums), which is the hook for the version-agnostic layer: write it generically over V: Version, or as one From/match per version mapping that version's enums to common events/actions.

Robustness

Decoding never panics on untrusted input (enforced by property tests on random and mutated inputs for every packet, NBT and the frame decoder):

  • every read is bounds-checked; lengths must be non-negative and fit the remaining input;
  • array counts are bounded by remaining / min_element_size, preallocation is capped at 4096 elements;
  • NBT nesting is limited to 512, TAG_End lists with elements are rejected;
  • frames: 3-byte length prefix (vanilla), max frame 2 MiB − 1, max declared uncompressed size 8 MiB (configurable), inflated size must match the declared size exactly;
  • VarInts longer than 5 bytes (VarLongs: 10) are rejected; like vanilla, padded encodings are accepted.

Decoding of a packet body is strict (decode_raw/decode_as reject trailing bytes, as vanilla does); Decode::decode on a Reader is available for lenient use.

Code generation

codegen/protocol (cargo run -p ghast-codegen-protocol) downloads minecraft-data 3.119.0 from npm into the git-ignored /.cache/minecraft-data/3.119.0/ (sha512-checked), follows dataPaths.json (pc 1.8 → pc/1.8, pc 1.16.5 → pc/1.16.2), and writes src/generated/ (committed; plain cargo build needs no network). Output is deterministic and rustfmt-formatted. minecraft-data is MIT licensed; see src/generated/NOTICE.

Layout of the generated code:

  • defs/p<N>/: every packet struct, nested type and named type exactly once, in the module of the first protocol N that has it. A later version reuses a definition when the emitted Rust code is identical (the concrete slot type and position layout are part of the code) and every definition it refers to is shared as well (a greatest-fixpoint partition refinement, so recursive types work). Each item is gated with #[cfg(any(feature = ...))] on the versions that use it, so a version feature that is off removes all code only it uses. Adding a version never moves an existing definition.
  • Packet structs take the protocol number as a const parameter (struct KeepAlive<const V: i32>), so one definition serves versions with different packet ids. Decoding and encoding are monomorphised per version: the machine code is the same as with one copy per version, without run-time version branches.
  • <version>/: the per-version layer — id constants, pub type KeepAlive = defs::p340::play::clientbound::KeepAlive<340>;, re-exports of the nested types, the Packet impls (id, name, state, direction), the packet-set enums and the Version marker. Struct literals, patterns, decode_as::<cb::KeepAlive>() and write_packet(&sb::KeepAlive { .. }) work through the aliases.
  • versions_table.rs: rows of versions::TABLE (game versions per protocol number come from minecraft-data's protocolVersions.json).

cargo run -p ghast-codegen-protocol prints how many definitions each version reuses.

How protodef types map to Rust:

protodef Rust
varint/varlong/ints/floats/bool i32/i64/…
string ByteString (zero-copy, UTF-8 validated)
buffer (varint count), restBuffer bytes::Bytes (zero-copy)
UUID uuid::Uuid
nbt / optionalNbt RawNbt / Option<RawNbt> (hand-written, lazy)
anonymousNbt / anonOptionalNbt AnonNbt / Option<AnonNbt> (hand-written, lazy)
registryEntryHolder / registryEntryHolderSet Holder<T> / HolderSet
bitflags newtype over the integer with one constant per flag; switches can test a flag (../action/add_player)
lpVec3 LpVec3 (exact wire form, to_vec3/from_vec3)
buffer with a fixed count bytes::Bytes, length checked on encode
recursive named types Box<T> on the references that close a cycle
state-local types (play.toClient.types) named types of that packet module
position BlockPos with the version's layout (hand-written)
slot types::Slot = slot::legacy::Slot / slot::modern::Slot (hand-written)
container struct (anonymous containers and bit fields are flattened into the parent)
switch Option<T> when every branch is void or one type T; otherwise an enum with one variant per case plus Default(T)/Other; the discriminant stays a separate field and encoding checks that both agree
mapper newtype over the integer with named constants (PlayerInfoAction::ADD_PLAYER); unknown values are kept
bitfield struct of integers; encoding range-checks every field
array (count type / fixed / field) Vec<T>; fixed and field counts are checked on encode
option Option<T>
entityMetadataLoop, topBitSetTerminatedArray Vec<T> with the terminator/flag handled by the codec
$compareTo-parametrised types (particleData, entityMetadataItem) one enum in types, instantiated inline per use

Vanilla overrides — the vanilla jar is the source of truth; minecraft-data is corrected where it disagrees, and the generator panics when a correction no longer matches (fixed or changed upstream), so a stale one cannot survive:

  • VersionSpec::presence (tested in tests/overrides.rs): 1.8 spawn_entity.velocity is present iff objectData > 0 (minecraft-data says != 0); 26.1 Slot and UntrustedSlot carry an item iff itemCount > 0 (vanilla's ItemStack.createOptionalStreamCodec reads any count <= 0 as empty; minecraft-data says != 0).
  • PATCHES (JSON-pointer patches of protocol.json, checked by cargo test -p ghast-codegen-protocol): 26.1 multi_block_change.records are VarLongs (vanilla ClientboundSectionBlocksUpdatePacket; minecraft-data has had varint since 1.20.2).

Packet ids of 26.1 are cross-checked against the vanilla server's own report: java -DbundlerMainClass=net.minecraft.data.Main -jar server.jar --reports writes packets.json (never committed); cargo run -p ghast-codegen-protocol -- packets-report 26.1 <packets.json> tests/data/packets_775.tsv pairs it by id with the minecraft-data names (a plain id/name table, committed), and tests/packets_report.rs checks the generated sets against the table (and against the report too when it is in /.cache/mojang/).

Renames: entityMetadataItem → EntityMetadataValue, with readable variant names for the metadata type ids (Byte, VarInt, Slot, Position, Pose, …).

Tests

cargo test -p ghast-protocol                       # everything (node tests skip if node is absent)
cargo test -p ghast-protocol --test differential   # see tests/node/README.md
cargo bench -p ghast-protocol
  • src/** unit tests: known-answer vectors (VarInt/VarLong edges, both position layouts, NIST SP 800-38A CFB8-AES128, hello_world.nbt, Modified UTF-8, slots, frames).
  • tests/roundtrip.rs: every packet of every version, 400 seeds each plus proptest; value and bytes must survive encode → decode → encode; random/mutated bodies never panic.
  • tests/robustness.rs: NBT and framing (all compression/encryption/filter modes, random chunking) round trips, and garbage/mutation inputs.
  • tests/capture_26_1.rs: real bytes from a vanilla 26.1.2 server (offline login, configuration, 40 s of play with items, block changes, chat, scoreboard, …; recorded by examples/login_26_1.rs): every packet decodes strictly and re-encodes to identical bytes, chunk sections parse completely.
  • tests/packets_report.rs: 26.1 packet ids/names against the vanilla report table.
  • examples/login_26_1.rs: handshake → status → login → configuration → play against a live 26.1.x server, answering keep-alives, pings, teleports and chunk batches, using only this crate.
  • tests/differential.rs: byte-exact agreement with node-minecraft-protocol in both directions, plus value-level checks for positions, bit fields, UUIDs, i64, mappers, slots and entity metadata.