ghast_protocol/lib.rs
1//! Minecraft Java Edition network protocol for the ghast client library.
2//!
3//! Layers, bottom to top:
4//!
5//! - [`codec`]: bounds-checked [`Reader`] over [`bytes::Bytes`] (zero-copy byte arrays
6//! and strings), [`McWrite`] for encoding, VarInt/VarLong.
7//! - [`types`], [`nbt`], [`chat`]: hand-written shared types — [`BlockPos`] with the
8//! per-version bit layout, slots, lazily parsed NBT ([`nbt::RawNbt`]), chat JSON.
9//! - Generated packet modules per protocol version (`v1_8` = protocol 47, `v1_12_2` =
10//! 340, `v1_16_5` = 754, `v26_1` = 775, `v26_2` = 776), each with typed packets, one enum per state
11//! and direction, and id constants. The definitions themselves live once in [`defs`]
12//! and are shared by every version whose code for them is identical. A [`Version`]
13//! marker type ties a version's packet sets together so a version-agnostic layer can be
14//! written generically; [`versions`] is the table of known protocol numbers.
15//! - [`frame`]: length framing, zlib compression with partial inflation, the
16//! AES-128-CFB8 hook ([`crypto`]), and the per-id [`PacketFilter`] that drops unwanted
17//! packets before they are decoded.
18//! - [`io`] (feature `tokio`): async framed reader/writer.
19//!
20//! Decoding never panics on untrusted input: every failure is a [`DecodeError`] or
21//! [`FrameError`], and allocations are bounded by the input size.
22//!
23//! ```
24//! use ghast_protocol::{FrameDecoder, FrameEncoder, PacketSet, RawPacket};
25//! use ghast_protocol::v1_8::play::serverbound::{KeepAlive, ServerboundPlayPacket};
26//!
27//! let mut enc = FrameEncoder::new();
28//! enc.write_packet(&KeepAlive { keep_alive_id: 42 }).unwrap();
29//! let mut dec = FrameDecoder::new();
30//! dec.push(&enc.take());
31//! let raw: RawPacket = dec.next_packet().unwrap().unwrap();
32//! let p = ServerboundPlayPacket::decode_raw(&raw).unwrap();
33//! assert_eq!(p, ServerboundPlayPacket::KeepAlive(KeepAlive { keep_alive_id: 42 }));
34//! ```
35
36#![forbid(unsafe_code)]
37#![warn(missing_docs, unnameable_types)]
38
39pub mod chat;
40pub mod codec;
41pub mod crypto;
42pub mod error;
43pub mod frame;
44pub mod intern;
45#[cfg(feature = "tokio")]
46pub mod io;
47pub mod nbt;
48pub mod packet;
49#[cfg(feature = "testgen")]
50pub mod testgen;
51pub mod types;
52pub mod versions;
53
54#[path = "generated/defs/mod.rs"]
55pub mod defs;
56
57#[cfg(feature = "v1_8")]
58#[path = "generated/v1_8/mod.rs"]
59pub mod v1_8;
60
61#[cfg(feature = "v1_12_2")]
62#[path = "generated/v1_12_2/mod.rs"]
63pub mod v1_12_2;
64
65#[cfg(feature = "v1_16_5")]
66#[path = "generated/v1_16_5/mod.rs"]
67pub mod v1_16_5;
68
69#[cfg(feature = "v26_1")]
70#[path = "generated/v26_1/mod.rs"]
71pub mod v26_1;
72
73#[cfg(feature = "v26_2")]
74#[path = "generated/v26_2/mod.rs"]
75pub mod v26_2;
76
77pub use codec::{Decode, Encode, McWrite, Reader};
78pub use error::{DecodeError, EncodeError, FrameError};
79pub use frame::{FrameDecoder, FrameEncoder, FrameLimits};
80#[cfg(feature = "tokio")]
81pub use io::{FramedReader, FramedWriter};
82pub use packet::{
83 Direction, NoPackets, Packet, PacketFilter, PacketSet, RawPacket, State, Version,
84};
85pub use types::BlockPos;
86pub use versions::ProtocolVersion;