Crate golden_apple

Overview

golden_apple is a library for decoding, encoding, and using common types found in Minecraft: Java Edition.

Goals

• Provide a generalized format for sharing and using Minecraft’s data types
• Simplify the decoding and encoding of network data
• Abstract away enums usually passed as numbers

Usage

Parsing NBT

let mut nbt_file_reader = std::fs::File::open("test.nbt")
    .expect("Unable to open file!");

match golden_apple::nbt::from_reader(&mut nbt_file_reader) {
    Ok(named_tag) => {
        println!("NBT Data: {:#?}", named_tag);
    }
    Err(e) => {
        panic!("Unable to parse NBT! ({:?})", e);
    }
}

Other

Proprietary Minecraft types like VarInt, VarLong, and Position are a part of the top level crate. Types that can be fully represented in Rust have encoders/decoders under golden_apple::generalized for reading and writing from both byte arrays and Rust’s Read/Write traits. Communicating with existing servers and clients can be done using the packet format and tools found in the netty module.

Status

This crate is unfinished and some features aren’t yet present. Here’s an overview of what’s still in progress:

• Metadata
• Slot
• Netty (13.1%)
• Other General Enums (~50%)

Cargo Features

There is one Cargo feature flag for this crate, encryption. It is not complete at this time and currently does nothing. Eventually, this will enable methods for handling packets when encryption is enabled between the server and client.

Version Support

Changelog

Crate version	Minecraft version	Minecraft Protocol ID
0.20.0	1.21.2 - 1.21.3	768
0.18.0 - 0.19.0	1.21.0 - 1.21.1	767
0.17.0 - 0.17.2	1.19.2	762

Modules

enums

Provides tools for reading, writing, and managing the various enums that Minecraft uses.

generalized

generalized contains many repetetive and unnecisary functions for reading and writing data. For sake of completion and inclusiveness, all standard types that may be written over the stream, no matter how easy to parse, are included here.

nbt

Provides tools for reading, writing, and managing NBT types.

netty

Enums and tools for communicating using the Minecraft network protocol.

Structs

Angle

Represents an angle. Cannot be greater than one full rotation, does not have negative values.

Chat

Represents a chat message or other form of rich text.

ChatComponent

Represents one component of a Chat object.

ChatScore

Describes details about a scoreboard.

ClickEvent

HoverEvent

Identifier

Represents a namespaced selector.

Position

Represents a position in the Minecraft world. Not the floating point values used for player movement, but the whole number values used for things like block positions.

UUID

Represents a Unique User ID. Used to track players and entities.

VarInt

Represents a Java Int (i32) using between 1-5 bytes.

VarLong

Represents a Java Long (i64) using between 1-10 bytes.

Enums

Error

Represents an error that can occur while using one of the libraries functions.

Constants

PROTOCOL_VERSION

The Minecraft protocol version used for communicating over the network with the netty module. see wiki.vg for more information.