nbt

README

NBT

This package implement the Named Binary Tag format of Minecraft.

The API is very similar to the standard library encoding/json. If you (high probability) have used that, it is easy to use this.

Documentation

Overview

Package nbt implement the Named Binary Tag format of Minecraft. It provides api like encoding/xml package.

Index

• Constants
• Variables
• func IsArrayTag(ty byte) bool
• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) (string, error)
  • func (d *Decoder) DisallowUnknownFields()
• type DecoderReader
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}, tagName string) error
• type Marshaler
• type RawMessage
  • func (m RawMessage) MarshalNBT(w io.Writer) error
  • func (m RawMessage) String() string
  • func (m RawMessage) TagType() byte
  • func (m RawMessage) Unmarshal(v interface{}) error
  • func (m *RawMessage) UnmarshalNBT(tagType byte, r DecoderReader) error
• type StringifiedMessage
  • func (m StringifiedMessage) MarshalNBT(w io.Writer) error
  • func (m StringifiedMessage) TagType() byte
  • func (m *StringifiedMessage) UnmarshalNBT(tagType byte, r DecoderReader) error
• type SyntaxError
  • func (e *SyntaxError) Error() string
• type Unmarshaler

Examples

• Decoder.Decode
• Decoder.Decode (SingleTagString)
• Encoder (WriteSNBT)
• Encoder.Encode (TagCompound)

Constants

const (
	TagEnd byte = iota
	TagByte
	TagShort
	TagInt
	TagLong
	TagFloat
	TagDouble
	TagByteArray
	TagString
	TagList
	TagCompound
	TagIntArray
	TagLongArray
	TagNone = 0xFF
)

Tag type IDs

Variables

var ErrEND = errors.New("unexpected TAG_End")

ErrEND error will be returned when reading a NBT with only Tag_End

Functions

func IsArrayTag

func IsArrayTag(ty byte) bool

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal is the shortcut of NewEncoder().Encode() with empty tag name. Notices that repeatedly init buffers is low efficiency. Using Encoder and Reset the buffer in each time is recommended in that cases.

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal decode binary NBT data and fill into v This is a shortcut to `NewDecoder(bytes.NewReader(data)).Decode(v)`.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) (string, error)

Decode method decodes an NBT value from the reader underline the Decoder into v. Internally try to handle all possible v by reflection, but the type of v must matches the NBT value logically. For example, you can decode an NBT value which root tag is TagCompound(0x0a) into a struct or map, but not a string.

If v implement Unmarshaler, the method will be called and override the default behavior. Else if v implement encoding.TextUnmarshaler, the value will be encoded as TagString.

This method also return tag name of the root tag. In real world, it is often empty, but the API should allow you to get it when ever you want.

Example

reader := bytes.NewReader([]byte{
	0x0a, // Start TagCompound("")
	0x00, 0x00,

	0x08, // TagString("Author"): "Tnze"
	0x00, 0x06, 'A', 'u', 't', 'h', 'o', 'r',
	0x00, 0x04, 'T', 'n', 'z', 'e',

	0x00, // End TagCompound
})

var value struct {
	Author string
}

decoder := NewDecoder(reader)
_, err := decoder.Decode(&value)
if err != nil {
	panic(err)
}

fmt.Println(value)

Output:

{Tnze}

Example (SingleTagString)

reader := bytes.NewReader([]byte{
	// TagString
	0x08,
	// TagName
	0x00, 0x04,
	0x6e, 0x61, 0x6d, 0x65,
	// Content
	0x00, 0x09,
	0x42, 0x61, 0x6e, 0x61, 0x6e, 0x72, 0x61, 0x6d, 0x61,
})

var Name string

decoder := NewDecoder(reader)
tagName, err := decoder.Decode(&Name)
if err != nil {
	panic(err)
}

fmt.Println(tagName)
fmt.Println(Name)

Output:

name
Bananrama

func (*Decoder) DisallowUnknownFields

func (d *Decoder) DisallowUnknownFields()

DisallowUnknownFields makes the decoder return an error when unmarshalling a compound tag item that has a tag name not present in the destination struct.

type DecoderReader

type DecoderReader = interface {
	io.ByteReader
	io.Reader
}

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Example (WriteSNBT)

var buf bytes.Buffer
if err := NewEncoder(&buf).Encode(StringifiedMessage(`{ name: [Tnze, "Xi_Xi_Mi"]}`), ""); err != nil {
	panic(err)
}
fmt.Printf("% 02x ", buf.Bytes())

Output:

0a 00 00 09 00 04 6e 61 6d 65 08 00 00 00 02 00 04 54 6e 7a 65 00 08 58 69 5f 58 69 5f 4d 69 00

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

func (*Encoder) Encode

func (e *Encoder) Encode(v interface{}, tagName string) error

Encode encodes v into the writer inside Encoder with the root tag named tagName. In most cases, the root tag typed TagCompound and the tag name is empty string, but any other type is allowed just because there is valid technically. Once if you should pass a string into this, you should get a TagString.

Normally, any slice or array typed Go value will be encoded as TagList, expect `[]int8`, `[]int32`, `[]int64`, `[]uint8`, `[]uint32` and `[]uint64`, which TagByteArray, TagIntArray and TagLongArray. To force encode them as TagList, add a struct field tag.

Example (TagCompound)

value := struct {
	Name string `nbt:"name"`
}{"Tnze"}

var buff bytes.Buffer
encoder := NewEncoder(&buff)
err := encoder.Encode(value, "")
if err != nil {
	panic(err)
}

fmt.Printf("% 02x ", buff.Bytes())

Output:

	0a 00 00 08 00 04 6e 61 6d 65 00 04 54 6e 7a 65 00

type Marshaler

type Marshaler interface {
	TagType() byte
	MarshalNBT(w io.Writer) error
}

type RawMessage

type RawMessage struct {
	Type byte
	Data []byte
}

RawMessage stores the raw binary data of NBT. This is usable if you want to store an unknown NBT data and parse it later. Notice that this struct doesn't store the tag name. To convert RawMessage to valid NBT binary value: Encoder.Encode(RawMessage, Name) = []byte{ Type (1 byte) | n (2 byte) | Name (n byte) | Data}.

func (RawMessage) MarshalNBT

func (m RawMessage) MarshalNBT(w io.Writer) error

func (RawMessage) String

func (m RawMessage) String() string

String convert the data into the SNBT(Stringified NBT) format. The output is valid for using in in-game command. Expect two exceptions: - Empty string "" if there is only an TagEnd in the NBT (aka: []byte{0}). - "<Invalid: $Err>" if the content is not valid NBT data.

func (RawMessage) TagType

func (m RawMessage) TagType() byte

func (RawMessage) Unmarshal

func (m RawMessage) Unmarshal(v interface{}) error

Unmarshal decode the data into v.

func (*RawMessage) UnmarshalNBT

func (m *RawMessage) UnmarshalNBT(tagType byte, r DecoderReader) error

type StringifiedMessage

type StringifiedMessage string

func (StringifiedMessage) MarshalNBT

func (m StringifiedMessage) MarshalNBT(w io.Writer) error

func (StringifiedMessage) TagType

func (m StringifiedMessage) TagType() byte

func (*StringifiedMessage) UnmarshalNBT

func (m *StringifiedMessage) UnmarshalNBT(tagType byte, r DecoderReader) error

type SyntaxError

type SyntaxError struct {
	Message string
	Offset  int
}

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Unmarshaler

type Unmarshaler interface {
	UnmarshalNBT(tagType byte, r DecoderReader) error
}