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_1 (feature v1_12_2) |
Protocol 338 (1.12.1): the 1.12.2 definitions except the keep-alive packets (VarInt ids, as in 1.8) |
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); also the layout of 751 (1.16.2) and 753 (1.16.3), which have table rows but no module of their own: write the handshake with their number |
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 ;
use ;
let = tcp.into_split;
let mut reader = new;
let mut writer = new;
// Login: after Set Compression (login::clientbound::Compress) call on both halves
reader.decoder.set_compression;
writer.encoder.set_compression;
// after sending the encryption response (secret from ghast-auth):
writer.encoder.enable_encryption;
reader.decoder.enable_encryption;
// Play: drop what the bot does not need before it is decoded (or even inflated).
reader.decoder.set_filter;
while let Some = reader.read_packet.await?
// One tick: queue the actions and the movement packet, then write them in one syscall.
writer.queue?;
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_Endlists 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 protocolNthat 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 —idconstants,pub type KeepAlive = defs::p340::play::clientbound::KeepAlive<340>;, re-exports of the nested types, thePacketimpls (id, name, state, direction), the packet-set enums and theVersionmarker. Struct literals, patterns,decode_as::<cb::KeepAlive>()andwrite_packet(&sb::KeepAlive { .. })work through the aliases.versions_table.rs: rows ofversions::TABLE(game versions per protocol number come from minecraft-data'sprotocolVersions.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 intests/overrides.rs): 1.8spawn_entity.velocityis present iffobjectData > 0(minecraft-data says!= 0); 26.1SlotandUntrustedSlotcarry an item iffitemCount > 0(vanilla'sItemStack.createOptionalStreamCodecreads any count <= 0 as empty; minecraft-data says!= 0).PATCHES(JSON-pointer patches ofprotocol.json, checked bycargo test -p ghast-codegen-protocol): 26.1multi_block_change.recordsare VarLongs (vanillaClientboundSectionBlocksUpdatePacket; minecraft-data has hadvarintsince 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
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 byexamples/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.