anvil

package
v0.0.0-...-f974f5f Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2022 License: BSD-1-Clause Imports: 14 Imported by: 0

README

Anvil

Package anvil reads level.dat and .mca region files which make up Minecraft worlds.

This library allows loading, modifying and saving of all the information. This means it can be used to analyze the contents of a world, but also change it to create new worlds.

Warning

The code defines read->write->read roundtrip tests to ensure the written data is consistent and correct. Even so, you should always create backups of any world you are about to change. I am not responsible for any damage you may do to your world data or Minecraft itself.

This package has been tested with world data created in Vanilla Minecraft 1.8.3+. There are no guarantees that older worlds can be read or that changes to such a world will still load up in Minecraft. Test your changes thoroughly. And when you're done testing, test some more.

Additionally, don't read/write world data which is currently being used by Minecraft itself. The behaviour of this undefined and will very likely end up in tears.

Documentation

Overview

Package anvil reads level.dat and .mca region files which make up Minecraft worlds.

This library allows loading, modifying and saving of all the information. This means it can be used to analyze the contents of a world, but also change it to create new worlds.

Warning

The code defines read->write->read roundtrip tests to ensure the written data is consistent and correct. Even so, you should __always create backups__ of any world you are about to change. I am __not__ responsible for any damage you may do to your world data or Minecraft itself.

This package has been tested with world data created in Vanilla Minecraft 1.8.3+. There are no guarantees that older worlds can be read or that changes to such a world will still load up in Minecraft. Test your changes thoroughly. And when you're done testing, test some more.

Additionally, don't read/write world data which is currently being used by Minecraft itself. The behaviour of this undefined and will very likely end up in tears.

Index

Constants

View Source 
const (
	GZip = 1
	ZLib = 2
)

Known chunk compression schemes.

View Source 
const (
	// These values are here to aid in converting various coordinate
	// sets between one another: block->chunk, block->region, etc.
	ChunksPerRegion  = 32
	BlocksPerChunk   = 16
	BlocksPerSection = 16
	SectionsPerChunk = 16
	BlocksPerRegion  = BlocksPerChunk * ChunksPerRegion
	MaxChunkHeight   = SectionsPerChunk * BlocksPerSection

	// MaxLight defines the highest possible light level.
	MaxLight = 15

	// RegionFileExtension defines the file extension for region files.
	RegionFileExtension = ".mca"
)

Variables

This section is empty.

Functions

func RegionCoords 

func RegionCoords(name string) (int, int, bool)

RegionCoords returns the x and z coordinates associated with the given region file.

The name should be in the form 'r.<X>.<Z>.mca', where X and Z are the signed integer coordinates.

Returns false if the coordinates could not be determined.

Types

type Abilities 

type Abilities struct {
	FlySpeed     float32 `nbt:"flySpeed"`
	WalkSpeed    float32 `nbt:"walkSpeed"`
	Flying       bool    `nbt:"flying"`
	Instabuild   bool    `nbt:"instabuild"`
	Invulnerable bool    `nbt:"invulnerable"`
	Mayfly       bool    `nbt:"mayfly"`
	MayBuild     bool    `nbt:"mayBuild"`
}

Abilities describes entity abilities.

type Attribute 

type Attribute struct {
	Modifiers []Modifier `nbt:"Modifiers"`
	Name      string     `nbt:"Name"`
	Base      float64    `nbt:"Base"`
}

Attribute defines an active attribute for an entity.

type Block 

type Block struct {
	Id         item.Id // The complete block id.
	BlockLight uint8   // Amount of block-emitted light.
	SkyLight   uint8   // Amount of sunlight or moonlight hitting the block.
}

Block represents a single block.

type Chunk 

type Chunk struct {
	Entities         []Entity     `nbt:"Entities"`
	TileEntities     []TileEntity `nbt:"TileEntities"`
	TileTicks        []TileTick   `nbt:"TileTicks"`
	Sections         []Section    `nbt:"Sections"`
	Biomes           []int8       `nbt:"Biomes"`
	HeightMap        []int32      `nbt:"HeightMap"`
	LastUpdate       int64        `nbt:"LastUpdate"`
	InhabitedTime    int64        `nbt:"InhabitedTime"`
	X                int32        `nbt:"xPos"`
	Z                int32        `nbt:"zPos"`
	V                int8         `nbt:"V"`
	LightPopulated   bool         `nbt:"LightPopulated"`
	TerrainPopulated bool         `nbt:"TerrainPopulated"`
}

Chunk represents a single chunk in a region file.

Reference: http://minecraft.gamepedia.com/Chunk_format

func (*Chunk) Init 

func (c *Chunk) Init(x, z int)

Init initializes the chunk to a default, empty state. Writing in block data will create sections as necessary.

func (*Chunk) Section 

func (c *Chunk) Section(y int, create bool) *Section

Section returns the section for the given Y coordinate. The coordinate is expected to be in the range 0-255 (MaxChunkHeight-1).

If create is true, a new section is added if it doesn't yet exist, provided the y value is in an acceptable range.

Returns nil if the coordinate is invalid. Returns nil if the section has not yet been generated and create is false.

func (*Chunk) UpdateHeightmap 

func (c *Chunk) UpdateHeightmap()

UpdateHeightmap refills the heightmap with current block data. Each value in the heightmap records the lowest level in each column where the light from the sky is at full strength.

This speeds computing of the SkyLight.

type ChunkDescriptor 

type ChunkDescriptor struct {
	LastModified time.Time // Last time thischunk was modified.
	X, Z         int       // Chunk coordinates in region.
	// contains filtered or unexported fields
}

ChunkDescriptor describes a single chunk as stored in a region.

func (*ChunkDescriptor) Read 

func (cd *ChunkDescriptor) Read(c *Chunk) bool

Read decompresses chunk data into the given structure. Returns false if ther eis no data or the decompression failed.

func (*ChunkDescriptor) SectorCount 

func (cd *ChunkDescriptor) SectorCount() int

SectorCount returns the number of sectors this chunk occupies.

func (*ChunkDescriptor) Write 

func (cd *ChunkDescriptor) Write(c *Chunk) bool

Write compresses the given chunk and writes the data into the current chunk descriptor.

type CommandStats 

type CommandStats struct {
	SuccessCountObjective     string `nbt:"SuccessCountObjective"`
	SuccessCountName          string `nbt:"SuccessCountName"`
	AffectedBlocksObjective   string `nbt:"AffectedBlocksObjective"`
	AffectedBlocksName        string `nbt:"AffectedBlocksName"`
	AffectedEntitiesObjective string `nbt:"AffectedEntitiesObjective"`
	AffectedEntitiesName      string `nbt:"AffectedEntitiesName"`
	AffectedItemsObjective    string `nbt:"AffectedItemsObjective"`
	AffectedItemsName         string `nbt:"AffectedItemsName"`
	QueryResultObjective      string `nbt:"QueryResultObjective"`
	QueryResultName           string `nbt:"QueryResultName"`
}

CommandStats defines information identifying scoreboard parameters to modify relative to the last command run.

type Difficulty 

type Difficulty int8

Difficulty defines the world's difficulty level 

const (
	Peaceful Difficulty = iota
	Easy
	Normal
	Hard
)

Known game modes.

func (Difficulty) String 

func (i Difficulty) String() string

type Entity 

type Entity struct {
	Riding            *Entity       `nbt:"Riding"`
	CommandStats      *CommandStats `nbt:"CommandStats"`
	Id                string        `nbt:"id"`
	UUID              string        `nbt:"UUID"`
	CustomName        string        `nbt:"CustomName"`
	OwnerUUID         string        `nbt:"OwnerUUID"`
	Owner             string        `nbt:"Owner"`
	Pos               []float64     `nbt:"Pos"`
	Motion            []float64     `nbt:"Motion"`
	Rotation          []float32     `nbt:"Rotation"`
	UUIDMost          int64         `nbt:"UUIDMost"`
	UUIDLeast         int64         `nbt:"UUIDLeast"`
	FallDistance      float32       `nbt:"FallDistance"`
	Dimension         int32         `nbt:"Dimension"`
	PortalCooldown    int32         `nbt:"PortalCooldown"`
	BreedingInLove    int32         `nbt:"InLove"`
	Fire              int16         `nbt:"Fire"`
	Air               int16         `nbt:"Air"`
	Health            uint8         `nbt:"Health"`
	OnGround          bool          `nbt:"OnGround"`
	Invulnerable      bool          `nbt:"Invulnerable"`
	CustomNameVisible bool          `nbt:"CustomNameVisible"`
	Silent            bool          `nbt:"Silent"`
}

Entity defines a single entity with fields shared by all entity types.

FIXME: This listing is far from complete. There are a huge amount of fields we do not account for here as they belong to individual entity sub-types like Horses, chickens, etc.

type EntityTag 

type EntityTag struct {
	CanDestroy  item.Id `nbt:"CanDestroy"`
	Unbreakable bool    `nbt:"Damage"`
}

type GameMode 

type GameMode int8

GameMode defines the current game mode. 

const (
	Survival GameMode = iota
	Creative
	Adventure
	Spectator
)

Known game modes.

func (GameMode) String 

func (i GameMode) String() string

type GameRules 

type GameRules struct {
	RandomTickSpeed     string `nbt:"randomTickSpeed"`
	CommandBlockOutput  bool   `nbt:"commandBlockOutput"`
	DaylightCycle       bool   `nbt:"doDaylightCycle"`
	FireTick            bool   `nbt:"doFireTick"`
	TileDrops           bool   `nbt:"doTileDrops"`
	KeepInventory       bool   `nbt:"keepInventory"`
	LogAdminCommands    bool   `nbt:"logAdminCommands"`
	MobLoot             bool   `nbt:"doMobLoot"`
	MobSpawning         bool   `nbt:"doMobSpawning"`
	MobGriefing         bool   `nbt:"mobGriefing"`
	NaturalRegeneration bool   `nbt:"naturalRegeneration"`
	SendCommandFeedback bool   `nbt:"sendCommandFeedback"`
	ShowDeathMessages   bool   `nbt:"showDeathMessages"`
	ReducedDebugInfo    bool   `nbt:"reducedDebugInfo"`
	EntityDrops         bool   `nbt:"doEntityDrops"`
}

GameRules describes the current rules for a world.

type InventorySlot 

type InventorySlot struct {
	Id     string `nbt:"id"`
	Damage int16  `nbt:"Damage"`
	Count  int8   `nbt:"Count"`
	Slot   int8   `nbt:"Slot"`
}

InventorySlot defines an inventory slot.

type Item 

type Item struct {
	Tag    EntityTag `nbt:"tag"`
	Id     string    `nbt:"id"`
	Count  int8      `nbt:"Count"`
	Slot   int8      `nbt:"Slot"`
	Damage int8      `nbt:"Damage"`
}

Items are used both in the player's inventory, Ender inventory, and in chest tile entities, dropped item entities, furnace tile entities, brewing stand tile entities, and Villager trading recipes.

Sometimes a Slot tag is used to specify the slot the item is in, such was with chests; other times there is no Slot tag, such as with dropped items.

type Level 

type Level struct {
	Player               *Player    `nbt:"Player"`
	Rules                GameRules  `nbt:"GameRules"`
	Name                 string     `nbt:"LevelName"`
	GeneratorName        string     `nbt:"generatorName"`
	GeneratorOptions     string     `nbt:"generatorOptions"`
	LastPlayed           int64      `nbt:"LastPlayed"`
	Seed                 int64      `nbt:"RandomSeed"`
	Time                 int64      `nbt:"Time"`
	DayTime              int64      `nbt:"DayTime"`
	SizeOnDisk           int64      `nbt:"SizeOnDisk"`
	BorderSizeLerpTime   int64      `nbt:"BorderSizeLerpTime"`
	BorderCenterX        float64    `nbt:"BorderCenterX"`
	BorderCenterZ        float64    `nbt:"BorderCenterZ"`
	BorderSize           float64    `nbt:"BorderSize"`
	BorderSizeLerpTarget float64    `nbt:"BorderSizeLerpTarget"`
	BorderWarningBlocks  float64    `nbt:"BorderWarningBlocks"`
	BorderWarningTime    float64    `nbt:"BorderWarningTime"`
	BorderDamagePerBlock float64    `nbt:"BorderDamagePerBlock"`
	BorderSafeZone       float64    `nbt:"BorderSafeZone"`
	GeneratorVersion     int32      `nbt:"generatorVersion"`
	Version              int32      `nbt:"version"`
	SpawnX               int32      `nbt:"SpawnX"`
	SpawnY               int32      `nbt:"SpawnY"`
	SpawnZ               int32      `nbt:"SpawnZ"`
	RainTime             int32      `nbt:"rainTime"`
	ClearWeatherTime     int32      `nbt:"clearWeatherTime"`
	ThunderTime          int32      `nbt:"thunderTime"`
	GameMode             GameMode   `nbt:"GameType"`
	Difficulty           Difficulty `nbt:"Difficulty"`
	Initialized          bool       `nbt:"initialized"`
	MapFeatures          bool       `nbt:"MapFeatures"`
	AllowCommands        bool       `nbt:"allowCommands"`
	Hardcore             bool       `nbt:"hardcore"`
	DifficultyLocked     bool       `nbt:"DifficultyLocked"`
	Raining              bool       `nbt:"raining"`
	Thundering           bool       `nbt:"thundering"`
}

Level describes the level.dat file for a Minecraft world. It holds general information about a world, like the name, the generator and seed and other things.

func LoadLevel 

func LoadLevel(file string) (*Level, error)

LoadLevel loads level data from the given level.dat file.

func (*Level) Save 

func (l *Level) Save(file string) error

Save saves level data to the given file.

type Modifier 

type Modifier struct {
	Name      string  `nbt:"Name"`
	UUIDLeast int64   `nbt:"UUIDLeast"`
	UUIDMost  int64   `nbt:"UUIDMost"`
	Amount    float64 `nbt:"Amount"`
	Operation int32   `nbt:"Operation"`
}

Modifier defines an attribute modifier.

type Player 

type Player struct {
	Abilities           Abilities       `nbt:"abilities"`
	Attributes          []Attribute     `nbt:"Attributes"`
	Inventory           []InventorySlot `nbt:"Inventory"`
	EnderItems          []InventorySlot `nbt:"EnderItems"`
	Motion              []float64       `nbt:"Motion"`
	Pos                 []float64       `nbt:"Pos"`
	Rotation            []float64       `nbt:"Rotation"`
	UUIDLeast           int64           `nbt:"UUIDLeast"`
	UUIDMost            int64           `nbt:"UUIDMost"`
	FoodExhaustionLevel float32         `nbt:"foodExhaustionLevel"`
	HealF               float32         `nbt:"HealF"`
	XpP                 float32         `nbt:"XpP"`
	AbsorptionAmount    float32         `nbt:"AbsorptionAmount"`
	FoodSaturationLevel float32         `nbt:"foodSaturationLevel"`
	FallDistance        float32         `nbt:"FallDistance"`
	SelectedItemSlot    int32           `nbt:"SelectedItemSlot"`
	FoodTickTimer       int32           `nbt:"foodTickTimer"`
	XpLevel             int32           `nbt:"XpLevel"`
	XpSeed              int32           `nbt:"XpSeed"`
	XpTotal             int32           `nbt:"XpTotal"`
	PlayerGameType      int32           `nbt:"playerGameType"`
	FoodLevel           int32           `nbt:"foodLevel"`
	Score               int32           `nbt:"Score"`
	HurtByTimestamp     int32           `nbt:"HurtByTimestamp"`
	Dimension           int32           `nbt:"Dimension"`
	PortalCooldown      int32           `nbt:"PortalCooldown"`
	Health              int16           `nbt:"Health"`
	Fire                int16           `nbt:"Fire"`
	DeathTime           int16           `nbt:"DeathTime"`
	SleepTimer          int16           `nbt:"SleepTimer"`
	HurtTime            int16           `nbt:"HurtTime"`
	Air                 int16           `nbt:"Air"`
	Sleeping            bool            `nbt:"Sleeping"`
	Invulnerable        bool            `nbt:"Invulnerable"`
	OnGround            bool            `nbt:"OnGround"`
}

Player defines all properties for a single player. For single-player games, this is part of level.dat. For servers, this is stored in separate files in the $WORLD/playerdata/ directory.

type Region 

type Region struct {
	X int // Region's X coordinate.
	Z int // Region's Z coordinate.
	// contains filtered or unexported fields
}

A region describes chunks with block data in a Minecraft world.

func CreateRegion 

func CreateRegion(file string) (*Region, error)

CreateRegion creates an empty region file at the given location. This contains only an empty header, without any chunks. Returns an error if the file already exists.

func LoadRegion 

func LoadRegion(file string) (*Region, error)

LoadRegion opens a region from the given file.

func (*Region) ChunkLen 

func (r *Region) ChunkLen() int

ChunkLen returns the number of /valid/ chunks in this region. Meaning chunks which have actually been generated and have data.

func (*Region) Chunks 

func (r *Region) Chunks() [][2]int

Chunks yields a list of chunk X/Z cooridnates for all valid chunks in this region. There are a maximum of 1024 chunks per region.

func (*Region) Clear 

func (r *Region) Clear()

Clear removes all blocks and all chunks from the region. Note that Region.Save() must be called to persist these changes.

func (*Region) HasChunk 

func (r *Region) HasChunk(x, z int) bool

HasChunk returns true if the given chunk exists in this region. That is, it has been generated and contains data.

func (*Region) ReadChunk 

func (r *Region) ReadChunk(x, z int, c *Chunk) bool

ReadChunk reads chunk data for the given coordinates into the specified structure.

Returns false if there is no valid chunk available, or the chunk data can not be decompressed.

func (*Region) Save 

func (r *Region) Save() error

Save writes all region data to the underlying file.

func (*Region) WriteChunk 

func (r *Region) WriteChunk(x, z int, c *Chunk) bool

WriteChunk writes compresses the given chunk data, so it may later be persisted using Region.Save().

type Section 

type Section struct {
	Blocks     []uint8 `nbt:"Blocks"`        // Primary block IDs -- 8 bits per block.
	Add        []uint8 `nbt:"Add,omitempty"` // Optional extra block ID information -- 4 bits per block.
	Data       []uint8 `nbt:"Data"`          // Block data -- 4 bits per block.
	BlockLight []uint8 `nbt:"BlockLight"`    // Amount of block-emitted light in each block -- 4 bits per block.
	SkyLight   []uint8 `nbt:"SkyLight"`      // Amount of sunlight or moonlight hitting each block -- 4 bits per block.
	Y          byte    `nbt:"Y"`             // Y index for this section.
}

Section defines a section of blocks.

Each chunk is divided up into 16 equal sections. Only generated sections will be saved to the world file. This is done to save file space. Each section spans 16*16*16 blocks.

func (*Section) Init 

func (s *Section) Init(y byte)

Init initializes the section to default, empty settings.

func (*Section) Read 

func (s *Section) Read(x, y, z int, b *Block) bool

Read fills the given block struct with data at the specified coordinates.

Returns false if the block data could not be found. This can happen when the coordinates are out of range.

func (*Section) Write 

func (s *Section) Write(x, y, z int, b *Block) bool

Write stores the given block struct for the specified coordinates.

Returns false if the coordinates are out of range.

type TileEntity 

type TileEntity struct {
	Id string `nbt:"id"`
	X  int32  `nbt:"x"`
	Y  int32  `nbt:"y"`
	Z  int32  `nbt:"z"`

	// Chest fields.
	Lock  string `nbt:"Lock"`
	Items []Item `nbt:"Items"`

	// Mob spawner fields.
	EntityId            string `nbt:"EntityId"`
	Delay               int16  `nbt:"Delay"`
	RequiredPlayerRange int16  `nbt:"RequiredPlayerRange"`
	MaxNearbyEntities   int16  `nbt:"MaxNearbyEntities"`
	MinSpawnDelay       int16  `nbt:"MinSpawnDelay"`
	MaxSpawnDelay       int16  `nbt:"MaxSpawnDelay"`
	SpawnRange          int16  `nbt:"SpawnRange"`
	SpawnCount          int16  `nbt:"SpawnCount"`
}

TileEntity describes a tile entity.

These are part of Chunk descriptors and cover things like mob spawners and chests.

type TileTick 

type TileTick struct {
	Id string `nbt:"i"`
	T  int32  `nbt:"t"`
	P  int32  `nbt:"p"`
	X  int32  `nbt:"x"`
	Y  int32  `nbt:"Y"`
	Z  int32  `nbt:"Z"`
}

Tile Ticks represent block updates that need to happen because they could not happen before the chunk was saved. Examples reasons for tile ticks include redstone circuits needing to continue updating, water and lava that should continue flowing, recently placed sand or gravel that should fall, etc. Tile ticks are not used for purposes such as leaf decay, where the decay information is stored in the leaf block data values and handled by Minecraft when the chunk loads.

For map makers, tile ticks can be used to update blocks after a period of time has passed with the chunk loaded into memory.

Source Files

View all Source files

Directories

Path Synopsis
Package biome describes a set of known biomes.
 Package biome describes a set of known biomes.
Package item defines constants with ids for all known items.
 Package item defines constants with ids for all known items.
NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of meta data.
 NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of meta data.

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.