nbt

NBT encoding and decoding for Minecraft Bedrock and Java Edition

The minecraft/nbt package implements NBT (Named Binary Tag) formats used by Minecraft. It supports little endian, big endian, and varint-based network formats.

Encoding Functions

Marshal

func Marshal(v any) ([]byte, error)

Encodes a Go value to NBT format using NetworkLittleEndian encoding.

v · any

The value to encode (must be a supported type)

[]byte

The encoded NBT data

error

Error if encoding fails

MarshalEncoding

func MarshalEncoding(v any, encoding Encoding) ([]byte, error)

Encodes a value using a specific NBT encoding variant.

v · any

The value to encode

encoding · Encoding

The NBT encoding to use (NetworkLittleEndian, LittleEndian, or BigEndian)

Decoding Functions

Unmarshal

func Unmarshal(data []byte, v any) error

Decodes NBT data into a Go value using NetworkLittleEndian encoding.

data · []byte

The NBT data to decode

v · any

Pointer to the value to decode into

error

Error if decoding fails

UnmarshalEncoding

func UnmarshalEncoding(data []byte, v any, encoding Encoding) error

Decodes NBT data using a specific encoding variant.

Streaming Encoders/Decoders

Encoder

type Encoder struct {
    Encoding Encoding
}

Writes NBT objects to an output stream.

NewEncoder

func NewEncoder(w io.Writer) *Encoder

Creates a new encoder that writes to the given writer.

NewEncoderWithEncoding

func NewEncoderWithEncoding(w io.Writer, encoding Encoding) *Encoder

Creates an encoder with a specific encoding.

Encode

func (e *Encoder) Encode(v any) error

Encodes a value and writes it to the output stream.

Decoder

type Decoder struct {
    Encoding  Encoding
    AllowZero bool
}

Reads NBT objects from an input stream.

NewDecoder

func NewDecoder(r io.Reader) *Decoder

Creates a new decoder that reads from the given reader.

NewDecoderWithEncoding

func NewDecoderWithEncoding(r io.Reader, encoding Encoding) *Decoder

Creates a decoder with a specific encoding.

Decode

func (d *Decoder) Decode(v any) error

Reads the next NBT object and decodes it into the given value.

Encoding Variants

var (
    NetworkLittleEndian Encoding // Network variant (default)
    LittleEndian        Encoding // Bedrock Edition file format
    BigEndian           Encoding // Java Edition format
)

Type Mappings

NBT tags map to Go types as follows:

NBT Tag	Go Type
TAG_Byte	byte, uint8, bool
TAG_Short	int16
TAG_Int	int32
TAG_Long	int64
TAG_Float	float32
TAG_Double	float64
TAG_ByteArray	[…]byte (array, not slice)
TAG_String	string
TAG_List	[]T (slice of any type)
TAG_Compound	struct, map[string]T
TAG_IntArray	[…]int32 (array, not slice)
TAG_LongArray	[…]int64 (array, not slice)

Struct Tags

The nbt struct tag controls field behavior:

type Example struct {
    Name   string `nbt:"name"`          // Use different NBT name
    Value  int32  `nbt:"value,omitempty"` // Omit if zero value
    Ignore string `nbt:"-"`              // Never encode/decode
}

Example Usage

Marshal/Unmarshal

type PlayerData struct {
    Name   string
    Health int32
    Pos    [3]float64
}

// Encode
data := PlayerData{
    Name:   "Steve",
    Health: 20,
    Pos:    [3]float64{0, 64, 0},
}
encoded, err := nbt.Marshal(data)
if err != nil {
    panic(err)
}

// Decode
var decoded PlayerData
err = nbt.Unmarshal(encoded, &decoded)
if err != nil {
    panic(err)
}

Stream Encoding

var buf bytes.Buffer
enc := nbt.NewEncoder(&buf)

err := enc.Encode(data)
if err != nil {
    panic(err)
}

Using Different Encodings

// For Java Edition compatibility
encoded, err := nbt.MarshalEncoding(data, nbt.BigEndian)

// For Bedrock Edition files
encoded, err := nbt.MarshalEncoding(data, nbt.LittleEndian)

// For network packets (default)
encoded, err := nbt.Marshal(data)