nbt

README

NBT (Named Binary Tag)

NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of meta data. An NBT file consists of a single compressed, named tag of type TAG_Compound, which holds an arbitrary amount of nested tags.

Usage

Unmarshal parses the uncompressed, NBT-encoded data and stores the result in the value pointed to by v. This is most commonly a struct, which reflects the NBT structure in its fields. Field tags can be used to map these fields to appropriate tag names in the NBT data. For example:

type Level struct {
	Name             string    `nbt:"levelName"`
	Generator        string    `nbt:"generatorName"`
	GeneratorOptions string    `nbt:"generatorOptions"`
	LastPlayed       time.Time `nbt:"LastPlayed", time:"2006-01-02T15:04:05"`
	Seed             int64     `nbt:"RandomSeed"`
	SpawnX           int32     `nbt:"SpawnX"`
	SpawnY           int32     `nbt:"SpawnY"`
	SpawnZ           int32     `nbt:"SpawnZ"`
	MapFeatures      bool      `nbt:"MapFeatures"`
	AllowCommands    bool      `nbt:"allowCommands"`
}

gz, err := gzip.NewReader(r)
...

var level Level
err = nbt.Unmarshal(gz, &level)
...

Data can be re-encoded with the Marshal call, or directly through the Encoder type:

var level Level
level.Name = "test"
...

gz := gzip.NewWriter(w)
err = nbt.Marshal(gz, &level)
...

Type compatibility

Some implicit type conversions can be achieved by adhering to the following guidelines.

    Tag Id         | Assignable to field | Note
    =======================================================================
    TAG_Byte       | int8, uint8         |
                   | int16, uint16       |
                   | int32, uint32       |
                   | int64, uint64       |
                   | bool                | true if the tag value is not 0
    -----------------------------------------------------------------------
    TAG_Short      | int16, uint16       |
                   | int32, uint32       |
                   | int64, uint64       |
    -----------------------------------------------------------------------
    TAG_Int        | int32, uint32       |
                   | int64, uint64       |
    -----------------------------------------------------------------------
    TAG_Long       | int64, uint64       |
                   | time.Time           | Expects a Unix timestamp.
    -----------------------------------------------------------------------
    TAG_Float      | float32             |
                   | float64             |
    -----------------------------------------------------------------------
    TAG_Double     | float64             |
    -----------------------------------------------------------------------
    TAG_Byte_Array | []int8, []uint8     |
    -----------------------------------------------------------------------
    TAG_Int_Array  | []int32, []uint32   |
    -----------------------------------------------------------------------
    TAG_String     | string              |
                   | bool                | Parsed using strconv.ParseBool()
    -----------------------------------------------------------------------
    TAG_List       | []T, []*T           |
    -----------------------------------------------------------------------
    Tag_Compound   | T, *T               |
    -----------------------------------------------------------------------

Any other, incompatible assignment will result in a parse error. Exceptions are type 'aliases' which are directly convertible to any of the types listed above. For instance:

type GameMode int32

type Level struct {
	...
	Mode   GameMode  `nbt:"gameType"` // == TAG_Int("gameType")
	...
}

If the encoder should not output a tag for an empty field, append the omitempty value to the struct field tag. For example:

type T struct {
	Data []byte  `nbt:"data,omitempty"
}

If len(T.Data) == 0, the encoder will ignore this field and no tag is emitted.

Documentation

Overview

NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of meta data. An NBT file consists of a single compressed, named tag of type `TAG_Compound`, which holds an arbitrary amount of nested tags.

Usage

Unmarshal parses the uncompressed, NBT-encoded data and stores the result in the value pointed to by v. This is most commonly a struct, which reflects the NBT structure in its fields. Field tags can be used to map these fields to appropriate tag names in the NBT data. For example:

type Level struct {
	Name             string    `nbt:"levelName"`
	Generator        string    `nbt:"generatorName"`
	GeneratorOptions string    `nbt:"generatorOptions"`
	LastPlayed       time.Time `nbt:"LastPlayed", time:"2006-01-02T15:04:05"`
	Seed             int64     `nbt:"RandomSeed"`
	SpawnX           int32     `nbt:"SpawnX"`
	SpawnY           int32     `nbt:"SpawnY"`
	SpawnZ           int32     `nbt:"SpawnZ"`
	MapFeatures      bool      `nbt:"MapFeatures"`
	AllowCommands    bool      `nbt:"allowCommands"`
}

gz, err := gzip.NewReader(r)
...

var level Level
err = nbt.Unmarshal(gz, &level)
...

Data can be re-encoded with the `Marshal` call, or directly through the `Encoder` type:

var level Level
level.Name = "test"
...

gz := gzip.NewWriter(w)
err = nbt.Marshal(gz, &level)
...

Type compatibility

Some implicit type conversions can be achieved by adhering to the following guidelines.

Tag Id         | Assignable to field | Note
=======================================================================
TAG_Byte       | int8, uint8         |
               | int16, uint16       |
               | int32, uint32       |
               | int64, uint64       |
               | bool                | true if the tag value is not 0
-----------------------------------------------------------------------
TAG_Short      | int16, uint16       |
               | int32, uint32       |
               | int64, uint64       |
-----------------------------------------------------------------------
TAG_Int        | int32, uint32       |
               | int64, uint64       |
-----------------------------------------------------------------------
TAG_Long       | int64, uint64       |
               | time.Time           | Expects a Unix timestamp.
-----------------------------------------------------------------------
TAG_Float      | float32             |
               | float64             |
-----------------------------------------------------------------------
TAG_Double     | float64             |
-----------------------------------------------------------------------
TAG_Byte_Array | []int8, []uint8     |
-----------------------------------------------------------------------
TAG_Int_Array  | []int32, []uint32   |
-----------------------------------------------------------------------
TAG_String     | string              |
               | bool                | Parsed using strconv.ParseBool()
-----------------------------------------------------------------------
TAG_List       | []T, []*T           |
-----------------------------------------------------------------------
Tag_Compound   | T, *T               |
-----------------------------------------------------------------------

Any other, incompatible assignment will result in a parse error. Exceptions are type 'aliases' which are directly convertible to any of the types listed above. For instance:

type GameMode int32

type Level struct {
	...
	Mode   GameMode  `nbt:"gameType"` // == TAG_Int("gameType")
	...
}

If the encoder should not output a tag for an empty field, append the `omitempty` value to the struct field tag. For example:

type T struct {
	Data []byte  `nbt:"data,omitempty"
}

If `len(T.Data) == 0`, the encoder will ignore this field and no tag is emitted.

Index

• func Marshal(w io.Writer, v interface{}) error
• func Unmarshal(r io.Reader, v interface{}) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}) error
• type MarshalError
  • func (e *MarshalError) Error() string
• type UnmarshalError
  • func (e *UnmarshalError) Error() string

Functions

func Marshal

func Marshal(w io.Writer, v interface{}) error

Marshal translates data into uncompressed, NBT-encoded data and writes it to the given stream.

func Unmarshal

func Unmarshal(r io.Reader, v interface{}) error

Unmarshal parses the uncompressed, NBT-encoded data and stores the result in the value pointed to by v.

Types

type Decoder

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

Decoder defines a NBT decoder, used to unmarshal uncompressed, NBT formatted data into a Go type.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new decoder for the given input stream.

func (*Decoder) Decode

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

Decode recursively reads tags and unmarshals them into the given value.

type Encoder

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

Encoder translates a Go type into a stream of NBT encoded data.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new encoder for the given value.

func (*Encoder) Encode

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

Encode translates v into uncompressed, NBT-encoded data and writes it to the underlying stream.

type MarshalError

type MarshalError struct {
	Name string
	Type reflect.Type
}

MarshalError describes an invalid argument passed to Marshal/Encode.

func (*MarshalError) Error

func (e *MarshalError) Error() string

type UnmarshalError

type UnmarshalError struct {
	Type reflect.Type
}

UnmarshalError describes an invalid argument passed to Unmarshal/Decode.

func (*UnmarshalError) Error

func (e *UnmarshalError) Error() string