Crate valence::protocol

valence_protocol

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.
encoder.append_packet(&packet);

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

let mut decoder = PacketDecoder::new();

// Put it in the decoder.
decoder.queue_bytes(bytes);

// 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.

Modules

• anyhow
  github crates-io docs-rs
• block_pos
• bytes
  Provides abstractions for working with bytes.
• chunk_pos
• chunk_section_pos
• decode
• encode
• game_mode
• packet_id
  Contains constants for every vanilla packet ID.
• packets
  All of Minecraft’s network packets.
• profile
• sound
• status_effects
• var_int

Macros

• ident
  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.

Structs

• BiomePos
• BlockPos
  Represents an absolute block position in world space.
• BlockState
  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.
• Bounded
  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.
• ByteAngle
  Represents an angle in steps of 1/256 of a full turn.
• ChunkPos
  The X and Z position of a chunk.
• ChunkSectionPos
• CompressionThreshold
  How large a packet should be before it is compressed by the packet encoder.
• FixedArray
  A fixed-size array encoded and decoded with a VarInt length prefix.
• FixedBitSet
• GlobalPos
• Ident
  A wrapper around a string type S which guarantees the wrapped string is a valid resource identifier.
• ItemStack
  A stack of items in an inventory.
• PacketDecoder
• PacketEncoder
• RawBytes
  While encoding, the contained slice is written directly to the output without any length prefix or metadata.
• Text
  Represents formatted text in Minecraft’s JSON text format.
• VarInt
  An i32 encoded with variable length.
• VarLong
  An i64 encoded with variable length.
• Velocity
  Quantized entity velocity.

Enums

• BlockKind
  An enumeration of all block kinds.
• Difficulty
• Direction
• GameMode
• Hand
• ItemKind
  Represents an item from the game
• PacketSide
  The side a packet is intended for.
• PacketState
  The statein which a packet is used.
• Particle
• Sound
  Represents a sound from the game

Constants

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

Traits

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

Derive Macros

• Decode
• Encode
• Packet