API Reference

Block

class anvil.Block(namespace, block_id=None, properties=None)

Represents a minecraft block.

namespace

Namespace of the block, most of the time this is minecraft

Type

str

id

ID of the block, for example: stone, diamond_block, etc…

Type

str

properties

Block properties as a dict

Type

dict

__init__(namespace, block_id=None, properties=None)
Parameters

  • namespace (str) – Namespace of the block. If no block_id is given, assume this is block_id and set namespace to "minecraft"

  • block_id (Optional[str]) – ID of the block

  • properties (Optional[dict]) – Block properties

classmethod from_name(name, *args, **kwargs)

Creates a new Block from the format: namespace:block_id

Parameters

name (str) – Block in said format

:param : Will be passed on to the main constructor :param args: Will be passed on to the main constructor :param kwargs: Will be passed on to the main constructor

classmethod from_numeric_id(block_id, data=0)

Creates a new Block from the block_id:data fromat used pre-flattening (pre-1.13)

Parameters

  • block_id (int) – Numeric ID of the block

  • data (int) – Numeric data, used to represent variants of the block

classmethod from_palette(tag)

Creates a new Block from the tag format on Section.Palette

Parameters

tag (TAG_Compound) – Raw tag from a section’s palette

name()

Returns the block in the minecraft:block_id format

Return type

str

class anvil.OldBlock(block_id, data=0)

Represents a pre 1.13 minecraft block, with a numeric id.

id

Numeric ID of the block

Type

int

data

The block data, used to represent variants of the block

Type

int

__init__(block_id, data=0)
Parameters

  • block_id (int) – ID of the block

  • data (int) – Block data

Region

class anvil.Region(data)

Read-only region

data

Region file (.mca) as bytes

Type

bytes

chunk_data(chunk_x, chunk_z)

Returns the NBT data for a chunk

Parameters

  • chunk_x (int) – Chunk’s X value

  • chunk_z (int) – Chunk’s Z value

Raises

anvil.GZipChunkData – If the chunk’s compression is gzip

Return type

NBTFile

chunk_location(chunk_x, chunk_z)

Returns the chunk offset in the 4KiB sectors from the start of the file, and the length of the chunk in sectors of 4KiB

Will return (0, 0) if chunk hasn’t been generated yet

Parameters

  • chunk_x (int) – Chunk’s X value

  • chunk_z (int) – Chunk’s Z value

Return type

Tuple[int, int]

classmethod from_file(file)

Creates a new region with the data from reading the given file

Parameters

file (Union[str, BinaryIO]) – Either a file path or a file object

get_chunk(chunk_x, chunk_z)

Returns the chunk at given coordinates, same as doing Chunk.from_region(region, chunk_x, chunk_z)

Parameters

  • chunk_x (int) – Chunk’s X value

  • chunk_z (int) – Chunk’s Z value

Return type

anvil.Chunk

staticmethod header_offset(chunk_x, chunk_z)

Returns the byte offset for given chunk in the header

Parameters

  • chunk_x (int) – Chunk’s X value

  • chunk_z (int) – Chunk’s Z value

Return type

int

Chunk

class anvil.Chunk(nbt_data)

Represents a chunk from a .mca file.

Note that this is read only.

x

Chunk’s X position

Type

int

z

Chunk’s Z position

Type

int

version

Version of the chunk NBT structure

Type

int

data

Raw NBT data of the chunk

Type

nbt.TAG_Compound

tile_entities

self.data['TileEntities'] as an attribute for easier use

Type

nbt.TAG_Compound

classmethod from_region(region, chunk_x, chunk_z)

Creates a new chunk from region and the chunk’s X and Z

Parameters

region (Union[str, Region]) – Either a anvil.Region or a region file name (like r.0.0.mca)

Raises

anvil.ChunkNotFound – If a chunk is outside this region or hasn’t been generated yet

get_block(x, y, z, section=None, force_new=False)

Returns the block in the given coordinates

Parameters

  • x (int) – Block’s coordinates in the chunk

  • y (int) – Block’s coordinates in the chunk

  • z (int) – Block’s coordinates in the chunk

  • section (int) – Either a section NBT tag or an index. If no section is given, assume Y is global and use it for getting the section.

  • force_new (bool) – Always returns an instance of Block if True, otherwise returns type OldBlock for pre-1.13 versions. Defaults to False

Raises

  • anvil.OutOfBoundCoordidnates – If X, Y or Z are not in the proper range

  • :rtype – anvil.Block:

Return type

Union[Block, OldBlock]

get_palette(section)

Returns the block palette for given section

Parameters

section (Union[int, TAG_Compound]) – Either a section NBT tag or an index

Return type

Tuple[anvil.Block]

get_section(y)

Returns the section at given y index can also return nothing if section is missing, aka it’s empty

Parameters

y (int) – Section Y index

Raises

anvil.OutOfBoundsCoordinates – If Y is not in range of 0 to 15

Return type

TAG_Compound

get_tile_entity(x, y, z)

Returns the tile entity at given coordinates, or None if there isn’t a tile entity

To iterate through all tile entities in the chunk, use Chunk.tile_entities

Return type

Optional[TAG_Compound]

for ... in stream_blocks(index=0, section=None, force_new=False)

Returns a generator for all the blocks in given section

Parameters

  • index (int) –

    At what block to start from.

    To get an index from (x, y, z), simply do:

    y * 256 + z * 16 + x

  • section (Union[int, TAG_Compound, None]) – Either a Y index or a section NBT tag.

  • force_new (bool) – Always returns an instance of Block if True, otherwise returns type OldBlock for pre-1.13 versions. Defaults to False

Raises

anvil.OutOfBoundCoordidnates – If section is not in the range of 0 to 15

Yields

anvil.Block

Return type

Generator[Block, None, None]

for ... in stream_chunk(index=0, section=None)

Returns a generator for all the blocks in the chunk

This is a helper function that runs Chunk.stream_blocks from section 0 to 15

Yields

anvil.Block

Return type

Generator[Block, None, None]

Empty

Region

class anvil.EmptyRegion(x, z)

Used for making own regions

chunks

List of chunks in this region

Type

List[anvil.EmptyChunk]

x
Type

int

z
Type

int

add_chunk(chunk)

Adds given chunk to this region. Will overwrite if a chunk already exists in this location

Parameters

chunk (EmptyChunk) –

Raises

anvil.OutOfBoundCoordidnates – If the chunk (x, z) is not inside this region

add_section(section, x, z, replace=True)

Adds section to chunk at (x, z). Same as EmptyChunk.add_section(section)

Parameters

  • section (EmptySection) – Section to add

  • x (int) – Chunk’s coordinate

  • z (int) – Chunk’s coordinate

  • replace (bool) – Whether to replace section if it already exists in the chunk

Raises

anvil.OutOfBoundsCoordinates – If the chunk (x, z) is not inside this region

fill(block, x1, y1, z1, x2, y2, z2, ignore_outside=False)

Fills in blocks from (x1, y1, z1) to (x2, y2, z2) in a rectangle.

Parameters

  • block (Block) –

  • x1 (int) – Coordinates

  • y1 (int) – Coordinates

  • z1 (int) – Coordinates

  • x2 (int) – Coordinates

  • y2 (int) – Coordinates

  • z2 (int) – Coordinates

  • ignore_outside (bool) – Whether to ignore if coordinates are outside the region

Raises

anvil.OutOfBoundsCoordinates – If any of the coordinates are outside the region

get_chunk(x, z)

Returns the chunk at given chunk coordinates

Parameters

  • x (int) – Chunk’s coordinates

  • z (int) – Chunk’s coordinates

Raises

  • anvil.OutOfBoundCoordidnates – If the chunk (x, z) is not inside this region

  • :rtype – anvil.EmptyChunk:

Return type

EmptyChunk

inside(x, y, z, chunk=False)

Returns if the given coordinates are inside this region

Parameters

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

  • chunk (bool) – Whether coordinates are global or chunk coordinates

Return type

bool

save(file=None)

Returns the region as bytes with the anvil file format structure, aka the final .mca file.

Parameters

file (Union[str, BinaryIO, None]) – Either a path or a file object, if given region will be saved there.

Return type

bytes

set_block(block, x, y, z)

Sets block at given coordinates. New chunk is made if it doesn’t exist.

Parameters

  • block (Block) – Block to place

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

Raises

anvil.OutOfBoundsCoordinates – If the block (x, y, z) is not inside this region

set_if_inside(block, x, y, z)

Helper function that only sets the block if self.inside(x, y, z) is true

Parameters

  • block (Block) – Block to place

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

Chunk

class anvil.EmptyChunk(x, z)

Used for making own chunks

x

Chunk’s X position

Type

int

z

Chunk’s Z position

Type

int

sections

List of all the sections in this chunk

Type

List[anvil.EmptySection]

version

Chunk’s DataVersion

Type

int

add_section(section, replace=True)

Adds a section to the chunk

Parameters

  • section (EmptySection) – Section to add

  • replace (bool) – Whether to replace section if one at same Y already exists

Raises

anvil.EmptySectionAlreadyExists – If replace is False and section with same Y already exists in this chunk

get_block(x, y, z)

Gets the block at given coordinates

Parameters

  • x (int) – In range of 0 to 15

  • z (int) – In range of 0 to 15

  • y (int) – In range of 0 to 255

Raises

anvil.OutOfBoundCoordidnates – If X, Y or Z are not in the proper range

Returns

block – Returns None if the section is empty, meaning the block is most likely an air block.

Return type

anvil.Block or None

save()

Saves the chunk data to a NBTFile

Notes

Does not contain most data a regular chunk would have, but minecraft stills accept it.

Return type

NBTFile

set_block(block, x, y, z)

Sets block at given coordinates

Parameters

  • x (int) – In range of 0 to 15

  • z (int) – In range of 0 to 15

  • y (int) – In range of 0 to 255

Raises

anvil.OutOfBoundCoordidnates – If X, Y or Z are not in the proper range

Section

class anvil.EmptySection(y)

Used for making own sections.

This is where the blocks are actually stored, in a 16³ sized array. To save up some space, None is used instead of the air block object, and will be replaced with self.air when needed

y

Section’s Y index

Type

int

blocks

1D list of blocks

Type

List[Block]

air

An air block

Type

Block

blockstates(palette=None)

Returns a list of each block’s index in the palette.

This is used in the BlockStates tag of the section.

Parameters

palette (Optional[Tuple[Block]]) – Section’s palette. If not given will generate one.

Return type

array

get_block(x, y, z)

Gets the block at given coordinates.

Parameters

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

Raises

anvil.OutOfBoundsCoordinates – If coordinates are not in range of 0-15

Return type

Block

staticmethod inside(x, y, z)

Check if X Y and Z are in range of 0-15

Parameters

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

Return type

bool

palette()

Generates and returns a tuple of all the different blocks in the section The order can change as it uses sets, but should be fine when saving since it’s only called once.

Return type

Tuple[Block]

save()

Saves the section to a TAG_Compound and is used inside the chunk tag This is missing the SkyLight tag, but minecraft still accepts it anyway

Return type

TAG_Compound

set_block(block, x, y, z)

Sets the block at given coordinates

Parameters

  • block (Block) – Block to set

  • x (int) – Coordinates

  • y (int) – Coordinates

  • z (int) – Coordinates

Raises

anvil.OutOfBoundsCoordinates – If coordinates are not in range of 0-15

class anvil.RawSection(y, blocks, palette)

Same as EmptySection but you manually set the palette and the blocks array (which instead of Block, it’s indexes on the palette)

y

Section’s Y index

Type

int

blocks

Array of palette indexes

Type

Iterable[int]

_palette

Section’s palette

Type

Sequence[Block]

blockstates(palette=None)

Refer to EmptySection.blockstates()

Return type

array

palette()

Returns self._palette

Return type

Sequence[Block]

save()

Refer to EmptySection.save()

Return type

TAG_Compound

Errors

exception anvil.errors.ChunkNotFound

Bases: Exception

Exception used for when a chunk was not found

exception anvil.errors.EmptySectionAlreadyExists

Bases: Exception

Exception used for when trying to add an EmptySection to an EmptyChunk and the chunk already has a section with the same Y

exception anvil.errors.GZipChunkData

Bases: Exception

Exception used when trying to get chunk data compressed in gzip

exception anvil.errors.OutOfBoundsCoordinates

Bases: ValueError

Exception used for when coordinates are out of bounds