Documentation ¶
Overview ¶
Package nbt provides encoding and decoding functionality for minecraft's NBT format. This package implements support for both BigEndian and SmallEndian, i.e. for every binary.ByteOrder.
To marshal a struct, use the marshal function as follows.
type myStruct struct { X int `nbt:"x"` } ... _ = nbt.MarshalWriter(myWriter, binary.BigEndian, myStruct{5})
The above example will write the following as NBT.
TagCompound(''): 1 entries { TagInt('x'): 5 }
You can also manually encode a tag, as follows.
enc := nbt.NewEncoder(myWriter, binary.BigEndian) _ = enc.WriteTag(nbt.NewCompoundTag("", []Tag{ nbt.NewIntTag("x", 5), }), )
This will result in the same output on the writer as in the example above. To read this written NBT tag, there are a few options, the easiest one being unmarshalling.
var v myStruct _ = nbt.UnmarshalReader(myReader, binary.BigEndian, &v) // v == 5
For (un-)marshalling, there is a struct tag, which supports naming, '-' (ignore while marshalling and unmarshalling) and 'omitempty', which ignores zero values while marshalling. For reading tags one by one from a reader, the process is similar to encoding.
dec := NewDecoder(myReader, binary.BigEndian) tag, err := dec.ReadTag() fmt.Println(nbt.ToString(tag))
This will print whatever one tag was on the reader. nbt.ToString will print an NBT tag in the above used representation.
Another way of decoding is using the nbt.Mapper. It is designed to unmarshal larger structures, for which unmarshalling is not flexible enough. It is more work than unmarshalling, but provides a clean and simple API for decoding. The idea is based on XPath, and a simple version of that is currently implemented.
TagCompound(''): 1 entries { TagCompound('first'): 1 entries { TagInt('x'): 5 } }
Using this NBT structure, the following code will extract the value 5 and finally print it.
var myInt int mapper := nbt.NewSimpleMapper(myTag) _ = mapper.MapInt("first.x", &myInt) fmt.Println(myInt)
This works for all NBT data types, including arrays and lists. For lists, the mapping function takes a function that is called before any mapping is done with the size of the list, which allows the user to preallocate a slice or similar. The following code decodes a list of int tags into an int array.
var myInts []int _ = mapper.MapList("path.to.intlist", func(size int) { myInts = make([]int, size) }, func(i int, mapper Mapper) error { return mapper.MapInt(&myInts[i]) })
Any error returned will contain a detailed message, what caused the error. Examples are, that the root tag or any tag in the query path except the last element is not a compound, the query path does not exist, or a type didn't match.
Index ¶
- func MarshalWriter(w io.Writer, order binary.ByteOrder, val interface{}) error
- func ToString(tag Tag) string
- func UnmarshalReader(rd io.Reader, order binary.ByteOrder, v interface{}) error
- type Byte
- type ByteArray
- type Compound
- func (t *Compound) Get(name string) (Tag, bool)
- func (t *Compound) ID() ID
- func (t Compound) Name() string
- func (t *Compound) Put(tag Tag)
- func (t *Compound) ReadFrom(reader io.Reader, order binary.ByteOrder) error
- func (t Compound) SetName(name string)
- func (t *Compound) WriteTo(writer io.Writer, order binary.ByteOrder) error
- type Decoder
- type Double
- type Encoder
- type End
- type Float
- type ID
- type Identifier
- type Int
- type IntArray
- type List
- type Long
- type LongArray
- type Mapper
- type Namer
- type ReaderFrom
- type Short
- type String
- type Tag
- type WriterTo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MarshalWriter ¶
MarshalWriter marshals the given val onto the given writer as an NBT tag. The given byte order is respected.
Types ¶
type Byte ¶
type Byte struct { Value int8 // contains filtered or unexported fields }
Byte is a tag for a byte
type ByteArray ¶
type ByteArray struct { Value []int8 // contains filtered or unexported fields }
ByteArray is a tag for []byte
func NewByteArrayTag ¶
NewByteArrayTag returns a new ByteArray tag
type Compound ¶
Compound is a list of named tags.
func NewCompoundTag ¶
NewCompoundTag returns a new Compound tag.
func (*Compound) Get ¶
Get returns the named tag with the given name in this compound, or false if no such tag exists.
type Double ¶
type Double struct { Value float64 // contains filtered or unexported fields }
Double is a double tag, which contains a float64 value.
func NewDoubleTag ¶
NewDoubleTag returns a new Double tag.
type End ¶
type End struct {
// contains filtered or unexported fields
}
End is an end tag. This has no data.
type Float ¶
type Float struct { Value float32 // contains filtered or unexported fields }
Float is a float tag.
func NewFloatTag ¶
NewFloatTag returns a new Float tag.
type ID ¶
type ID byte
ID is a tag id, such as IDTagEnd or IDTagLongArray.
const ( // IDTagEnd indicates the end for a compound tag. IDTagEnd ID = iota // TagEnd // IDTagByte is a signed byte (-128 to 127). IDTagByte // TagByte // IDTagShort is a signed short (-32768 to 32767). IDTagShort // TagShort // IDTagInt is a signed int (-2147483648 to 2147483647). IDTagInt // TagInt // IDTagLong is a signed long (-9223372036854775808 to 9223372036854775807). IDTagLong // TagLong // IDTagFloat is a signed float32 (IEEE-754). IDTagFloat // TagFloat // IDTagDouble is a signed float64 (IEEE-754). IDTagDouble // TagDouble // IDTagByteArray is a array of signed bytes. IDTagByteArray // TagByteArray // IDTagString is a UTF-8 string. IDTagString // TagString // IDTagList is a list of nameless tags, all tags are of the same type. IDTagList // TagList // IDTagCompound is a list of named tags. IDTagCompound // TagCompound // IDTagIntArray is a array for int(4bytes). IDTagIntArray // TagIntArray // IDTagLongArray is a array for long(8bytes). IDTagLongArray // TagLongArray // NumIDTags is the amount of ID tags that are known. NumIDTags // amount of ID tags )
type Int ¶
type Int struct { Value int32 // contains filtered or unexported fields }
Int is an int tag.
type IntArray ¶
type IntArray struct { Value []int32 // contains filtered or unexported fields }
IntArray is a tag for a int array
func NewIntArrayTag ¶
NewIntArrayTag returns a new IntArray tag
type List ¶
List is a list of unnamed tags.
func NewListTag ¶
NewListTag returns a new List tag.
type Long ¶
type Long struct { Value int64 // contains filtered or unexported fields }
Long is a tag for an int64
type LongArray ¶
type LongArray struct { Value []int64 // contains filtered or unexported fields }
LongArray is a tag for a array of longs
func NewLongArrayTag ¶
NewLongArrayTag returns a new LongArray tag
type Mapper ¶
type Mapper interface { // Query will execute the given query string on the tag in this mapper. // The interpretation of the query is implementation specific. Query(string) (Tag, error) // MapByte will interpret the tag under the given query path as byte and // store it under the given *int8, or return an error if the tag under the // path is not a byte tag. MapByte(string, *int8) error // MapShort will interpret the tag under the given query path as short and // store it under the given *int16, or return an error if the tag under the // path is not a short tag. MapShort(string, *int16) error // MapInt will interpret the tag under the given query path as int and // store it under the given *int, or return an error if the tag under the // path is not an int tag. MapInt(string, *int) error // MapInt32 works just as MapInt, but converts the given int to an int32. // This can be useful if you have a lot of ints (which are 4-byte in NBT), // but want to save the extra 4 bytes if you're on a 64bit arch. MapInt32(string, *int32) error // MapLong will interpret the tag under the given query path as int64 and // store it under the given *int64, or return an error if the tag under the // path is not a long tag. MapLong(string, *int64) error // MapFloat will interpret the tag under the given query path as float32 and // store it under the given *float32, or return an error if the tag under the // path is not a long tag. MapFloat(string, *float32) error // MapDouble will interpret the tag under the given query path as float64 and // store it under the given *float64, or return an error if the tag under the // path is not a long tag. MapDouble(string, *float64) error // MapString will interpret the tag under the given query path as string and // store it under the given *string, or return an error if the tag under the // path is not a string tag. MapString(string, *string) error // MapByteArray will interpret the tag under the given query path as bytearray and // store it under the given *[]int8, or return an error if the tag under the // path is not a bytearray tag. MapByteArray(string, *[]int8) error // MapIntArray will interpret the tag under the given query path as intarray and // store it under the given *[]int, or return an error if the tag under the // path is not a intarray tag. MapIntArray(string, *[]int) error // MapInt32Array is the array equivalent to MapInt32. MapInt32Array(string, *[]int32) error // MapLongArray will interpret the tag under the given query path as longarray and // store it under the given *[]int64, or return an error if the tag under the // path is not a longarray tag. MapLongArray(string, *[]int64) error // MapList will interpret the tag under the given query path as list. It will return // an error if that tag is not a list (also returns an error if the path points to // an array). Before calling the mapping function, it will call the initializer function // once with the size of the list, allowing for preallocation. After that, it will call // the mapping function for every element in the list, with the mapper containing only // the list element at index i. i is the zero-based index of an element in the list. MapList(query string, initializer func(int), mapping func(i int, mapper Mapper) error) error // MapCustom is equivalent to calling Query, and then calling the given function with the tag // udner the query, or return an error if any. MapCustom(string, func(Tag) error) error }
Mapper describes a component that can be used to support more complex mappings of known structures than marshalling could support.
func NewSimpleMapper ¶
NewSimpleMapper creates a new mapper on the given source tag. It doesn't do any kind of caching or other performance improvements.
type ReaderFrom ¶
ReaderFrom is something that can read from a reader respecting a byte order.
type Short ¶
type Short struct { Value int16 // contains filtered or unexported fields }
Short is a tag for a short
func NewShortTag ¶
NewShortTag returns a new Short tag
Source Files ¶
- decoder.go
- doc.go
- encoder.go
- id.go
- id_string.go
- mapper.go
- mapper_simple.go
- marshal.go
- structtag.go
- tag.go
- tag_array_byte.go
- tag_array_int.go
- tag_array_long.go
- tag_base.go
- tag_byte.go
- tag_compound.go
- tag_double.go
- tag_end.go
- tag_float.go
- tag_int.go
- tag_list.go
- tag_long.go
- tag_short.go
- tag_string.go
- tostring.go
- unmarshal.go