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.

Re-exports

pub use block_pos::BlockPos;

pub use chunk_pos::ChunkPos;

pub use chunk_section_pos::ChunkSectionPos;

pub use decode::PacketDecoder;

pub use encode::PacketEncoder;

pub use encode::WritePacket;

pub use game_mode::GameMode;

pub use item::ItemStack;

pub use packets::play::particle_s2c::Particle;

pub use var_int::VarInt;

pub use anyhow;

pub use bytes;

pub use uuid;

pub use valence_ident as ident;

pub use valence_math as math;

pub use valence_nbt as nbt;

pub use valence_text as text;

Modules

block

block_pos

chunk_pos

chunk_section_pos

decode

encode

game_mode

item

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

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.

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.

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.

VarLong

An i64 encoded with variable length.

Velocity

Quantized entity velocity.

Enums

BlockKind

An enumeration of all block kinds.

Difficulty

Direction

Hand

ItemKind

Represents an item from the game

PacketSide

The side a packet is intended for.

PacketState

The statein which a packet is used.

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.

Derive Macros

Decode

Encode

Packet