schematic

README

go-schematic

Go library for reading and writing Sponge Schematic v2/v3 files (.schem), as used by WorldEdit for Minecraft 1.13+.

Blocks are stored as palette-indexed varint arrays inside a gzip-compressed NBT structure.

Install

go get github.com/go-mclib/go-schematic

Usage

Create a new schematic

s := schematic.New(16, 8, 16) // width, height, length

s.SetBlock(0, 0, 0, "minecraft:stone")
s.SetBlock(1, 0, 0, "minecraft:oak_planks")

block := s.BlockAt(0, 0, 0) // "minecraft:stone"

Save to file

f, _ := os.Create("build.schem")
defer f.Close()

if err := s.Save(f); err != nil {
    log.Fatal(err)
}

Load from file

ReadFrom auto-detects v2 and v3 schematics:

f, _ := os.Open("build.schem")
defer f.Close()

s, err := schematic.ReadFrom(f)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("size: %dx%dx%d\n", s.Width, s.Height, s.Length)

Block states

Block state strings follow Minecraft's format: namespace:block[property=value,...]. Properties are optional and describe variants like orientation, open/closed state, etc.

// simple block
s.SetBlock(0, 0, 0, "minecraft:stone")

// block with state properties
s.SetBlock(1, 0, 0, "minecraft:oak_stairs[facing=east,half=bottom,shape=straight]")
s.SetBlock(2, 0, 0, "minecraft:oak_door[facing=north,half=lower,open=false]")
s.SetBlock(3, 0, 0, "minecraft:redstone_wire[power=15]")

// reading back includes the full state string
fmt.Println(s.BlockAt(1, 0, 0)) // "minecraft:oak_stairs[facing=east,half=bottom,shape=straight]"

The palette is managed automatically -- new states are added on first use, and BlockAt returns the exact string that was set.

Block entities and entities

Block entities (chests, signs, etc.) and entities (mobs, items, etc.) are preserved during read/write:

for _, be := range s.BlockEntities {
    fmt.Printf("%s at %v\n", be.ID, be.Pos)
}

for _, e := range s.Entities {
    fmt.Printf("%s at %v\n", e.ID, e.Pos)
}

Types

Type	Description
Schematic	Main struct holding dimensions, palette, block data, and entities
BlockEntity	Tile entity with position, ID, and NBT data
Entity	Entity with float position, ID, and NBT data

License

MIT

Documentation

Overview

Package schematic implements reading and writing of Sponge Schematic v2/v3 files.

These are the .schem files used by WorldEdit for Minecraft 1.13+. The format stores blocks as palette-indexed varint arrays inside a gzip-compressed NBT structure.

Index

• func AppendVarint(buf []byte, value int) []byte
• func DecodeVarint(data []byte) (value int, bytesRead int)
• type BlockEntity
• type Entity
• type Schematic
  • func New(width, height, length int16) *Schematic
  • func ReadFrom(r io.Reader) (*Schematic, error)
  • func (s *Schematic) BlockAt(x, y, z int) string
  • func (s *Schematic) Index(x, y, z int) int
  • func (s *Schematic) Save(w io.Writer) error
  • func (s *Schematic) SetBlock(x, y, z int, state string)

Functions

func AppendVarint

func AppendVarint(buf []byte, value int) []byte

AppendVarint appends a variable-length integer to the byte slice.

func DecodeVarint

func DecodeVarint(data []byte) (value int, bytesRead int)

DecodeVarint reads a variable-length integer from the byte slice.

Types

type BlockEntity

type BlockEntity struct {
	Pos  [3]int32
	ID   string
	Data nbt.Compound
}

type Entity

type Entity struct {
	Pos  [3]float64
	ID   string
	Data nbt.Compound
}

type Schematic

type Schematic struct {
	Version       int32
	DataVersion   int32
	Width         int16
	Height        int16
	Length        int16
	Offset        [3]int32
	Palette       []string // index → block state string
	Blocks        []int32  // flat array of palette indices, len = Width*Height*Length
	BlockEntities []BlockEntity
	Entities      []Entity
}

func New

func New(width, height, length int16) *Schematic

New creates an empty schematic filled with air.

func ReadFrom

func ReadFrom(r io.Reader) (*Schematic, error)

ReadFrom reads a gzipped .schem file, auto-detecting v2 or v3.

func (*Schematic) BlockAt

func (s *Schematic) BlockAt(x, y, z int) string

BlockAt returns the block state string at (x, y, z).

func (*Schematic) Index

func (s *Schematic) Index(x, y, z int) int

Index returns the flat array index for the given (x, y, z) position.

func (*Schematic) Save

func (s *Schematic) Save(w io.Writer) error

Save writes the schematic as a gzipped Sponge Schematic v3 file.

func (*Schematic) SetBlock

func (s *Schematic) SetBlock(x, y, z int, state string)

SetBlock sets the block at (x, y, z), adding to palette if needed.