valence

Crate protocol

Source
Expand description

§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