Crate valence::protocol

source ·
Expand description


A protocol library for Minecraft: Java Edition. Use this to build clients, servers, proxies, or something novel!

valence_protocol is primarily concerned with defining all of Minecraft’s network packets and the process for encoding and decoding them. To encode and decode packets, use the PacketEncoder and PacketDecoder types.

use valence_protocol::{PacketEncoder, PacketDecoder, Difficulty};
use valence_protocol::packets::play::DifficultyS2c;

let mut encoder = PacketEncoder::new();

let packet = DifficultyS2c {
    difficulty: Difficulty::Peaceful,
    locked: true,

// Encode our packet struct.

// Take our encoded packet(s) out of the encoder.
let bytes = encoder.take();

let mut decoder = PacketDecoder::new();

// Put it in the decoder.

// Get the next packet "frame" from the decoder and use that to decode the body of the packet.
// Packet frames can be thought of as type-erased packet structs.
let frame = decoder.try_next_packet().unwrap().unwrap();
let decoded_packet = frame.decode::<DifficultyS2c>().unwrap();

// Check that our original packet struct is the same as the one we just decoded.
assert_eq!(&packet, &decoded_packet);

Supported Minecraft Versions

Currently, valence_protocol only intends to support the most recent stable version of Minecraft. New Minecraft versions often entail a major version bump, since breaking changes to packet definitions are frequent.

The currently targeted Minecraft version and protocol version can be checked using the MINECRAFT_VERSION and PROTOCOL_VERSION constants.

Feature Flags

  • encryption: Enables support for packet encryption.
  • compression: Enables support for packet compression.



  • Creates a new Ident at compile time from a string literal. A compile error is raised if the string is not a valid resource identifier.


  • Represents an absolute block position in world space.
  • Represents the state of a block. This does not include block entity data such as the text on a sign, the design on a banner, or the content of a spawner.
  • A newtype wrapper for T which modifies the Encode and Decode impls to be bounded by some upper limit MAX. Implementations are expected to error eagerly if the limit is exceeded.
  • Represents an angle in steps of 1/256 of a full turn.
  • The X and Z position of a chunk.
  • How large a packet should be before it is compressed by the packet encoder.
  • A fixed-size array encoded and decoded with a VarInt length prefix.
  • A wrapper around a string type S which guarantees the wrapped string is a valid resource identifier.
  • A stack of items in an inventory.
  • While encoding, the contained slice is written directly to the output without any length prefix or metadata.
  • Represents formatted text in Minecraft’s JSON text format.
  • An i32 encoded with variable length.
  • An i64 encoded with variable length.
  • Quantized entity velocity.



  • The maximum number of bytes in a single Minecraft packet.
  • The stringified name of the Minecraft version this library currently targets.
  • The Minecraft protocol version this library currently targets.


  • The Decode trait allows objects to be read from the Minecraft protocol. It is the inverse of Encode.
  • The Encode trait allows objects to be written to the Minecraft protocol. It is the inverse of Decode.
  • Types considered to be Minecraft packets.
  • Types that can have packets written to them.

Derive Macros