nbt

package module
v0.0.0-...-b8dbf4f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 10, 2026 License: MIT Imports: 18 Imported by: 0

README

nbt-go

test Go Reference

Minecraft's NBT format for Go, in two parts:

  • A library modeled on encoding/json, with a structure package for Java Edition structure (.nbt) files. It is documented below.
  • nbt-mcp, an MCP server built on the library that lets an AI model build, inspect and save structure files. It has its own README.

Install

go get github.com/MinecraftMetascript/nbt-go@latest

Requires Go 1.22 or newer. The library has no dependencies outside the standard library.

Features

  • Marshal / Unmarshal, Encoder / Decoder, and nbt:"name,omitempty" struct tags, the same way encoding/json does it.
  • A Tag tree (Compound, List, Int, …) for data whose shape you don't know ahead of time, like map[string]any for JSON.
  • Gzip and zlib compressed input is detected automatically, and Encoder.SetCompression writes it.
  • SNBT (the {id:"minecraft:stone",count:1b} syntax used in commands) both ways.
  • The structure package reads, writes and builds structure files.

Usage

type Item struct {
	Slot  int8   `nbt:"Slot"`
	ID    string `nbt:"id"`
	Count int32  `nbt:"count"`
}

type Chest struct {
	CustomName string `nbt:"CustomName,omitempty"`
	Items      []Item `nbt:"Items"`
}

data, err := nbt.Marshal(Chest{Items: []Item{{0, "minecraft:diamond", 3}}})

var chest Chest
err = nbt.Unmarshal(data, &chest)

Reading and writing files:

f, _ := os.Open("level.dat")
dec := nbt.NewDecoder(f) // gzip is detected
var level struct {
	Data struct {
		LevelName string
		SpawnX, SpawnY, SpawnZ int32
	}
}
err := dec.Decode(&level)

enc := nbt.NewEncoder(out)
enc.SetCompression(nbt.Gzip)
err = enc.Encode(level)

Unknown data, or data you want to pass through untouched:

var tree nbt.Tag // or nbt.Compound, or any
nbt.Unmarshal(data, &tree)
fmt.Println(tree) // prints SNBT: {Items:[{Slot:0b,count:3,id:"minecraft:diamond"}]}

SNBT:

var chest Chest
err := nbt.UnmarshalSNBT(`{Items:[{Slot:0b,id:"minecraft:diamond",count:3}]}`, &chest)
s, err := nbt.MarshalSNBT(chest)

Type mapping

Go NBT
bool TAG_Byte (0/1)
int8, uint8 TAG_Byte
int16, uint16 TAG_Short
int32, uint32, int, uint TAG_Int (int/uint error if out of range)
int64, uint64 TAG_Long
float32 / float64 TAG_Float / TAG_Double
string TAG_String
[]byte, []int8 TAG_Byte_Array
[]int32, []uint32 TAG_Int_Array
[]int64, []uint64 TAG_Long_Array
other slices and arrays TAG_List (elements must share one type)
map[string]T, structs TAG_Compound
pointers, interfaces the value they point to; nil is omitted
nbt.Tag types (nbt.Compound, …) themselves
nbt.Marshaler / encoding.TextMarshaler whatever MarshalNBT returns / TAG_String

Struct tag options:

  • omitempty leaves out zero values, as in encoding/json.
  • list writes a byte, int or long slice as a TAG_List instead of an array. Minecraft uses lists for things like positions: Pos [3]int32 `nbt:"pos,list"` .
  • - skips the field.

Decoding is lenient where it's safe: any integer tag decodes into any Go integer or bool if the value fits, arrays and lists decode into slices, and unknown keys are ignored unless you call Decoder.DisallowUnknownFields. Errors report the path to the bad value, such as blocks[3].pos[1].

Structure files

s := structure.New(5023) // the DataVersion of the target Minecraft version; 5023 is 26.3

s.Fill(0, 0, 0, 4, 0, 4, structure.MustParseBlockState("stone_bricks"))
s.SetBlock(2, 1, 2, structure.MustParseBlockState("chest[facing=north]"),
	nbt.Compound{"LootTable": nbt.String("minecraft:chests/simple_dungeon")})
s.AddEntity([3]float64{2.5, 1, 0.5}, nbt.Compound{"id": nbt.String("minecraft:armor_stand")})

f, _ := os.Create("my_structure.nbt")
defer f.Close()
err := s.Write(f) // gzip compressed, ready for a structure block or data pack

structure.Read loads existing files, including vanilla ones with multiple palettes (shipwrecks and similar). Positions with no block are left alone when the structure is placed, like minecraft:structure_void; place minecraft:air to clear a space.

The DataVersion decides how the file is written. Minecraft 26.3 renamed the palette keys from Name/Properties to id/properties (from DataVersion 5009 on). Both are read, and a structure is written with the keys that match its DataVersion, so set it to the version of the game that will load the file. Newer games upgrade older files, but older games can't read newer ones.

Development

The repository holds two Go modules: the library at the root and the server in cmd/nbt-mcp, which pins a version of the library in its go.mod. Run the checks in each:

go test -race ./...
golangci-lint run          # in cmd/nbt-mcp: golangci-lint run -c ../../.golangci.yml

To build the server against a local copy of the library, add a go.work file (it is not committed):

go work init . ./cmd/nbt-mcp

Scope

This library covers Java Edition NBT (big-endian). Bedrock's little-endian and network variants, and region (.mca) files, aren't supported yet.

License

MIT. See LICENSE.

Documentation

Overview

Package nbt implements encoding and decoding of Minecraft's Named Binary Tag (NBT) format, as used by Java Edition for level data, player data and structure (.nbt) files.

The API is modeled on encoding/json. Go values are converted to and from NBT with Marshal and Unmarshal, or streamed with Encoder and Decoder. Struct fields are mapped with `nbt:"name,opts"` tags.

When the shape of the data is not known ahead of time, decode into a Tag (or an empty interface) to get a tree of Compound, List, Int, ... values, much like decoding JSON into map[string]any.

Type mapping

Go values are encoded as follows: 

bool                     Byte (0 or 1)
int8, uint8              Byte
int16, uint16            Short
int32, uint32            Int
int, uint                Int (an error if the value does not fit)
int64, uint64            Long
float32                  Float
float64                  Double
string                   String
[]byte, []int8           ByteArray
[]int32, []uint32        IntArray
[]int64, []uint64        LongArray
other slices and arrays  List (elements must all encode to the same type)
map[string]T             Compound
struct                   Compound
pointer, interface       the value pointed to; nil is omitted

The "list" tag option forces a byte, int or long slice to be encoded as a List instead of an array, which some Minecraft formats require (for example the "pos" field in structure files is a List of Int): 

Pos [3]int32 `nbt:"pos,list"`

NBT has no null value, so nil pointers, interfaces and maps-of-nothing are left out of the enclosing compound rather than written as an empty value.

Decoding is lenient in the same way encoding/json is: any integer tag can be decoded into any Go integer (or bool) as long as the value fits, any numeric tag into a float, arrays and lists into slices, and unknown compound keys are ignored unless Decoder.DisallowUnknownFields is set.

Compression

Unmarshal and Decoder detect gzip and zlib compressed input automatically. Encoder.SetCompression selects compression when writing; Java Edition structure files are gzip compressed.

SNBT

Every Tag formats itself as stringified NBT (the syntax used by commands such as /data and /give) via its String method, and ParseSNBT, MarshalSNBT and UnmarshalSNBT convert in the other direction.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/MinecraftMetascript/nbt-go"
)

type Item struct {
	Slot  int8   `nbt:"Slot"`
	ID    string `nbt:"id"`
	Count int32  `nbt:"count"`
}

type Chest struct {
	CustomName string `nbt:"CustomName,omitempty"`
	Items      []Item `nbt:"Items"`
}

func main() {
	chest := Chest{Items: []Item{{Slot: 0, ID: "minecraft:diamond", Count: 3}}}

	data, err := nbt.Marshal(chest)
	if err != nil {
		log.Fatal(err)
	}

	var decoded Chest
	if err := nbt.Unmarshal(data, &decoded); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", decoded)
}

Output:
{CustomName: Items:[{Slot:0 ID:minecraft:diamond Count:3}]}

Index

Examples

Constants

View Source 
const MaxDepth = 512

MaxDepth is the maximum nesting depth of lists and compounds accepted when reading, matching Minecraft's own limit.

Variables

This section is empty.

Functions

func FromTag 

func FromTag(t Tag, v any) error

FromTag stores t in the value pointed to by v, using the same rules as Unmarshal. It is the inverse of ToTag.

func Marshal 

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

Marshal returns the uncompressed binary NBT encoding of v, written as a root tag with an empty name (as Java Edition does for structure and level files). Use an Encoder to set the root name or compress the output.

v is normally a struct or map, giving a TAG_Compound root. See the package documentation for how Go values map to NBT.

func MarshalSNBT 

func MarshalSNBT(v any) (string, error)

MarshalSNBT returns the stringified NBT (SNBT) form of v, the syntax used by Minecraft commands such as /data and /give. Compound keys are sorted so the output is deterministic.

func Unmarshal 

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

Unmarshal parses binary NBT data and stores the result in the value pointed to by v. Gzip and zlib compressed data is detected and decompressed automatically. The root tag's name is ignored; use a Decoder to read it.

v may be a pointer to a struct or map (for a compound root), to a Tag or empty interface (to get the raw tree), or to any other type compatible with the root tag. See the package documentation for the conversion rules.

Example (Tree) 
package main

import (
	"fmt"
	"log"

	"github.com/MinecraftMetascript/nbt-go"
)

func main() {
	data, _ := nbt.Marshal(map[string]any{
		"pos":  []float64{1.5, 64, -3},
		"name": "Steve",
	})

	// Decode into a Tag (or any) when the shape isn't known up front.
	var tree nbt.Tag
	if err := nbt.Unmarshal(data, &tree); err != nil {
		log.Fatal(err)
	}
	c := tree.(nbt.Compound)
	fmt.Println(c["name"], c["pos"].Type())
	fmt.Println(tree)
}

Output:
"Steve" TAG_List
{name:"Steve",pos:[1.5d,64d,-3d]}

func UnmarshalSNBT 

func UnmarshalSNBT(s string, v any) error

UnmarshalSNBT parses SNBT and stores the result in the value pointed to by v, using the same rules as Unmarshal.

Types

type Byte 

type Byte int8

Byte is a TAG_Byte, a signed 8-bit integer. Minecraft also uses it for booleans.

func (Byte) String 

func (t Byte) String() string

func (Byte) Type 

func (Byte) Type() TagType

type ByteArray 

type ByteArray []byte

ByteArray is a TAG_Byte_Array.

func (ByteArray) String 

func (t ByteArray) String() string

func (ByteArray) Type 

func (ByteArray) Type() TagType

type Compound 

type Compound map[string]Tag

Compound is a TAG_Compound: a set of uniquely named tags. Key order is not significant in NBT; SNBT output sorts keys.

func (Compound) String 

func (t Compound) String() string

func (Compound) Type 

func (Compound) Type() TagType

type Compression 

type Compression int

Compression selects how an Encoder compresses its output. 

const (
	// None writes uncompressed NBT. This is the default.
	None Compression = iota
	// Gzip writes gzip-compressed NBT, the format of Java Edition .nbt
	// structure files, level.dat and player data.
	Gzip
	// Zlib writes zlib-compressed NBT, as used for chunks in region files.
	Zlib
)

func (Compression) String 

func (c Compression) String() string

type Decoder 

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

A Decoder reads NBT values from an input stream.

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r. Gzip or zlib compression is detected from the first bytes of the stream.

The decoder may read data from r beyond the NBT values requested.

func (*Decoder) Compression 

func (d *Decoder) Compression() Compression

Compression reports the compression detected on the stream. It is only meaningful after the first call to Decode or DecodeTag.

func (*Decoder) Decode 

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

Decode reads the next root tag from the stream and stores it in the value pointed to by v. See Unmarshal for details of the conversion. It returns io.EOF when the stream has no more values.

func (*Decoder) DecodeTag 

func (d *Decoder) DecodeTag() (Tag, error)

DecodeTag reads the next root tag from the stream and returns it as a tree. It returns io.EOF when the stream has no more values.

func (*Decoder) DisallowUnknownFields 

func (d *Decoder) DisallowUnknownFields()

DisallowUnknownFields causes Decode to return an UnknownFieldError when a compound contains a key that does not match any field of the destination struct.

func (*Decoder) RootName 

func (d *Decoder) RootName() string

RootName returns the name of the root tag most recently decoded.

type Double 

type Double float64

Double is a TAG_Double, a 64-bit IEEE 754 number.

func (Double) String 

func (t Double) String() string

func (Double) Type 

func (Double) Type() TagType

type Encoder 

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

An Encoder writes NBT values to an output stream.

Example (Gzip) 
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/MinecraftMetascript/nbt-go"
)

func main() {
	var buf bytes.Buffer
	enc := nbt.NewEncoder(&buf)
	enc.SetCompression(nbt.Gzip)
	if err := enc.Encode(map[string]int32{"DataVersion": 3955}); err != nil {
		log.Fatal(err)
	}

	// Decoders detect compression on their own.
	dec := nbt.NewDecoder(&buf)
	var v struct{ DataVersion int32 }
	if err := dec.Decode(&v); err != nil {
		log.Fatal(err)
	}
	fmt.Println(v.DataVersion, dec.Compression())
}

Output:
3955 gzip

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode 

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

Encode writes the NBT encoding of v to the stream as a named root tag. See Marshal for details of the conversion.

func (*Encoder) EncodeTag 

func (e *Encoder) EncodeTag(t Tag) error

EncodeTag writes t to the stream as a named root tag.

func (*Encoder) SetCompression 

func (e *Encoder) SetCompression(c Compression)

SetCompression sets the compression applied to each value written. With Gzip or Zlib, every call to Encode writes one complete compressed stream.

func (*Encoder) SetRootName 

func (e *Encoder) SetRootName(name string)

SetRootName sets the name written for the root tag. It defaults to the empty string, which is what Java Edition uses.

type Float 

type Float float32

Float is a TAG_Float, a 32-bit IEEE 754 number.

func (Float) String 

func (t Float) String() string

func (Float) Type 

func (Float) Type() TagType

type Int 

type Int int32

Int is a TAG_Int, a signed 32-bit integer.

func (Int) String 

func (t Int) String() string

func (Int) Type 

func (Int) Type() TagType

type IntArray 

type IntArray []int32

IntArray is a TAG_Int_Array.

func (IntArray) String 

func (t IntArray) String() string

func (IntArray) Type 

func (IntArray) Type() TagType

type InvalidUnmarshalError 

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. The argument must be a non-nil pointer.

func (*InvalidUnmarshalError) Error 

func (e *InvalidUnmarshalError) Error() string

type List 

type List []Tag

List is a TAG_List. All elements must have the same type. An empty List is written with element type TAG_End, as Minecraft does.

func (List) ElemType 

func (l List) ElemType() TagType

ElemType reports the type of the list's elements, or TagEnd if it is empty.

func (List) String 

func (t List) String() string

func (List) Type 

func (List) Type() TagType

type Long 

type Long int64

Long is a TAG_Long, a signed 64-bit integer.

func (Long) String 

func (t Long) String() string

func (Long) Type 

func (Long) Type() TagType

type LongArray 

type LongArray []int64

LongArray is a TAG_Long_Array.

func (LongArray) String 

func (t LongArray) String() string

func (LongArray) Type 

func (LongArray) Type() TagType

type Marshaler 

type Marshaler interface {
	MarshalNBT() (Tag, error)
}

Marshaler is implemented by types that can convert themselves to a Tag.

type MarshalerError 

type MarshalerError struct {
	Type reflect.Type
	Err  error
}

A MarshalerError wraps an error returned by a MarshalNBT method.

func (*MarshalerError) Error 

func (e *MarshalerError) Error() string

func (*MarshalerError) Unwrap 

func (e *MarshalerError) Unwrap() error

type SNBTSyntaxError 

type SNBTSyntaxError struct {
	Offset int // byte offset in the input
	// contains filtered or unexported fields
}

An SNBTSyntaxError describes malformed SNBT.

func (*SNBTSyntaxError) Error 

func (e *SNBTSyntaxError) Error() string

type Short 

type Short int16

Short is a TAG_Short, a signed 16-bit integer.

func (Short) String 

func (t Short) String() string

func (Short) Type 

func (Short) Type() TagType

type String 

type String string

String is a TAG_String.

func (String) String 

func (t String) String() string

func (String) Type 

func (String) Type() TagType

type SyntaxError 

type SyntaxError struct {
	Offset int64 // bytes read before the error occurred
	// contains filtered or unexported fields
}

A SyntaxError describes malformed binary NBT.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

type Tag 

type Tag interface {
	// Type reports the wire type of the tag.
	Type() TagType
	String() string
	// contains filtered or unexported methods
}

Tag is an NBT value. The concrete types are Byte, Short, Int, Long, Float, Double, ByteArray, String, List, Compound, IntArray and LongArray. The set is closed: other packages cannot implement Tag.

The String method of every Tag returns its SNBT representation.

func ParseSNBT 

func ParseSNBT(s string) (Tag, error)

ParseSNBT parses a single SNBT value, such as 

{Items:[{Slot:0b,id:"minecraft:diamond",count:3}],CustomName:'"Loot"'}

Unquoted values are typed the way Minecraft types them: 1b is a Byte, 1s a Short, 1 an Int, 1L a Long, 1.5f a Float, 1.5 or 1.5d a Double, true and false are Bytes, and anything else is a String.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/MinecraftMetascript/nbt-go"
)

type Item struct {
	Slot  int8   `nbt:"Slot"`
	ID    string `nbt:"id"`
	Count int32  `nbt:"count"`
}

type Chest struct {
	CustomName string `nbt:"CustomName,omitempty"`
	Items      []Item `nbt:"Items"`
}

func main() {
	tag, err := nbt.ParseSNBT(`{Items:[{Slot:0b,id:"minecraft:diamond",count:3}]}`)
	if err != nil {
		log.Fatal(err)
	}
	var chest Chest
	if err := nbt.FromTag(tag, &chest); err != nil {
		log.Fatal(err)
	}
	fmt.Println(chest.Items[0].ID, chest.Items[0].Count)
}

Output:
minecraft:diamond 3

func ToTag 

func ToTag(v any) (Tag, error)

ToTag converts v to an NBT tree using the same rules as Marshal. It is useful for building a Compound from Go values, for example to embed in another structure or format as SNBT.

type TagType 

type TagType byte

TagType identifies the type of an NBT tag as it appears on the wire. 

const (
	TagEnd       TagType = 0
	TagByte      TagType = 1
	TagShort     TagType = 2
	TagInt       TagType = 3
	TagLong      TagType = 4
	TagFloat     TagType = 5
	TagDouble    TagType = 6
	TagByteArray TagType = 7
	TagString    TagType = 8
	TagList      TagType = 9
	TagCompound  TagType = 10
	TagIntArray  TagType = 11
	TagLongArray TagType = 12
)

The NBT tag types, with their on-the-wire IDs.

func (TagType) String 

func (t TagType) String() string

type UnknownFieldError 

type UnknownFieldError struct {
	Name string
	Type reflect.Type
	Path string
}

An UnknownFieldError is returned when Decoder.DisallowUnknownFields is set and a compound has a key with no matching struct field.

func (*UnknownFieldError) Error 

func (e *UnknownFieldError) Error() string

type UnmarshalTypeError 

type UnmarshalTypeError struct {
	Tag   TagType      // the NBT type that was found
	Type  reflect.Type // the Go type it could not be assigned to
	Path  string       // dotted path of the offending value, e.g. "blocks[3].pos"
	Value string       // optional detail, e.g. the overflowing number
}

An UnmarshalTypeError describes an NBT tag that could not be stored in a Go value of a particular type.

func (*UnmarshalTypeError) Error 

func (e *UnmarshalTypeError) Error() string

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalNBT(Tag) error
}

Unmarshaler is implemented by types that can set themselves from a Tag.

type UnsupportedTypeError 

type UnsupportedTypeError struct {
	Type reflect.Type
}

An UnsupportedTypeError is returned by Marshal when asked to encode a value of a type that has no NBT representation, such as a channel or func.

func (*UnsupportedTypeError) Error 

func (e *UnsupportedTypeError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
nbt-mcp module
Package structure reads, writes and builds Minecraft Java Edition structure files: the gzip-compressed .nbt files saved by structure blocks and loaded by /place template or data packs.
 Package structure reads, writes and builds Minecraft Java Edition structure files: the gzip-compressed .nbt files saved by structure blocks and loaded by /place template or data packs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.