amulet.api.level.base_level package

Contents:

class amulet.api.level.BaseLevel(path, format_wrapper)[source]

Bases: object

BaseLevel is a base class for all world-like data.

It exposes chunk data and other data using a history system to track and enable undoing changes.

__init__(path, format_wrapper)[source]

Construct a BaseLevel object from the given data.

This should not be used directly. You should instead use amulet.load_level().

Parameters

  • path (str) – The path to the data being loaded. May be a file or directory. If blank there is no data on disk associated with this.

  • format_wrapper (FormatWrapper) – The FormatWrapper instance that the level will wrap around.

property level_wrapper: FormatWrapper[source]

A class to access data directly from the level.

property sub_chunk_size: int[source]

The normal dimensions of the chunk.

property level_path: str[source]

The system path where the level is located.

This may be a directory, file or an empty string depending on the level that is loaded.

property translation_manager: TranslationManager[source]

An instance of the translation class for use with this level.

property block_palette: BlockManager[source]

The manager for the universal blocks in this level. New blocks must be registered here before adding to the level.

property biome_palette: BiomeManager[source]

The manager for the universal blocks in this level. New biomes must be registered here before adding to the level.

property selection_bounds: SelectionGroup[source]

The selection(s) that all chunk data must fit within. Usually +/-30M for worlds. The selection for structures.

bounds(dimension)[source]

The selection(s) that all chunk data must fit within. This specifies the volume that can be built in. Worlds will have a single cuboid volume. Structures may have one or more cuboid volumes.

Parameters

dimension (str) – The dimension to get the bounds of.

Return type

SelectionGroup

Returns

The build volume for the dimension.

property dimensions: Tuple[str, ...][source]

The dimensions strings that are valid for this level.

get_block(x, y, z, dimension)[source]

Gets the universal Block object at the specified coordinates.

To get the block in a given format use get_version_block()

Parameters

  • x (int) – The X coordinate of the desired block

  • y (int) – The Y coordinate of the desired block

  • z (int) – The Z coordinate of the desired block

  • dimension (str) – The dimension of the desired block

Return type

Block

Returns

The universal Block object representation of the block at that location

Raises

ChunkDoesNotExist: If the chunk does not exist (was deleted or never created)

ChunkLoadError: If the chunk was not able to be loaded. Eg. If the chunk is corrupt or some error occurred when loading.

get_coord_box(dimension, selection=None, yield_missing_chunks=False)[source]

Given a selection will yield chunk coordinates and SelectionBox instances into that chunk

If not given a selection will use the bounds of the object.

Parameters

  • dimension (str) – The dimension to take effect in.

  • selection (Union[SelectionGroup, SelectionBox, None]) – SelectionGroup or SelectionBox into the level. If None will use bounds() for the dimension.

  • yield_missing_chunks – If a chunk does not exist an empty one will be created (defaults to false). Use this with care.

Return type

Generator[Tuple[Tuple[int, int], SelectionBox], None, None]

get_chunk_boxes(dimension, selection=None, create_missing_chunks=False)[source]

Given a selection will yield Chunk and SelectionBox instances into that chunk

If not given a selection will use the bounds of the object.

Parameters

  • dimension (str) – The dimension to take effect in.

  • selection (Union[SelectionGroup, SelectionBox, None]) – SelectionGroup or SelectionBox into the level. If None will use bounds() for the dimension.

  • create_missing_chunks – If a chunk does not exist an empty one will be created (defaults to false). Use this with care.

Return type

Generator[Tuple[Chunk, SelectionBox], None, None]

get_chunk_slice_box(dimension, selection=None, create_missing_chunks=False)[source]

Given a selection will yield Chunk, slices, SelectionBox for the contents of the selection.

Parameters

  • dimension (str) – The dimension to take effect in.

  • selection (Union[SelectionGroup, SelectionBox, None]) – SelectionGroup or SelectionBox into the level. If None will use bounds() for the dimension.

  • create_missing_chunks – If a chunk does not exist an empty one will be created (defaults to false)

Return type

Generator[Tuple[Chunk, Tuple[slice, slice, slice], SelectionBox], None, None]

>>> for chunk, slices, box in level.get_chunk_slice_box(selection):
>>>     chunk.blocks[slice] = ...
get_moved_coord_slice_box(dimension, destination_origin, selection=None, destination_sub_chunk_shape=None, yield_missing_chunks=False)[source]

Iterate over a selection and return slices into the source object and destination object given the origin of the destination. When copying a selection to a new area the slices will only be equal if the offset is a multiple of the chunk size. This will rarely be the case so the slices need to be split up into parts that intersect a chunk in the source and destination.

Parameters

  • dimension (str) – The dimension to iterate over.

  • destination_origin (Tuple[int, int, int]) – The location where the minimum point of the selection will end up

  • selection (Union[SelectionGroup, SelectionBox, None]) – An optional selection. The overlap of this and the dimensions bounds will be used

  • destination_sub_chunk_shape (Optional[int]) – the chunk shape of the destination object (defaults to self.sub_chunk_size)

  • yield_missing_chunks (bool) – Generate empty chunks if the chunk does not exist.

Return type

Generator[Tuple[Tuple[int, int], Tuple[slice, slice, slice], SelectionBox, Tuple[int, int], Tuple[slice, slice, slice], SelectionBox], None, None]

Returns

get_moved_chunk_slice_box(dimension, destination_origin, selection=None, destination_sub_chunk_shape=None, create_missing_chunks=False)[source]

Iterate over a selection and return slices into the source object and destination object given the origin of the destination. When copying a selection to a new area the slices will only be equal if the offset is a multiple of the chunk size. This will rarely be the case so the slices need to be split up into parts that intersect a chunk in the source and destination.

Parameters

  • dimension (str) – The dimension to iterate over.

  • destination_origin (Tuple[int, int, int]) – The location where the minimum point of self.selection will end up

  • selection (Union[SelectionGroup, SelectionBox, None]) – An optional selection. The overlap of this and self.selection will be used

  • destination_sub_chunk_shape (Optional[int]) – the chunk shape of the destination object (defaults to self.sub_chunk_size)

  • create_missing_chunks (bool) – Generate empty chunks if the chunk does not exist.

Return type

Generator[Tuple[Chunk, Tuple[slice, slice, slice], SelectionBox, Tuple[int, int], Tuple[slice, slice, slice], SelectionBox], None, None]

Returns

pre_save_operation()[source]

Logic to run before saving. Eg recalculating height maps or lighting. Is a generator yielding progress from 0 to 1 and returning a bool saying if changes have been made.

Return type

Generator[float, None, bool]

Returns

Have any modifications been made.

save(wrapper=None, progress_callback=None)[source]

Save the level to the given FormatWrapper.

Parameters

  • wrapper (Optional[FormatWrapper]) – If specified will save the data to this wrapper instead of self.level_wrapper

  • progress_callback (Optional[Callable[[int, int], None]]) – Optional progress callback to let the calling program know the progress. Input format chunk_index, chunk_count

Returns

save_iter(wrapper=None)[source]

Save the level to the given FormatWrapper.

This will yield the progress which can be used to update a UI.

Parameters

wrapper (Optional[FormatWrapper]) – If specified will save the data to this wrapper instead of self.level_wrapper

Return type

Generator[Tuple[int, int], None, None]

Returns

A generator of the number of chunks completed and the total number of chunks

purge()[source]

Unload all loaded and cached data.

This is functionally the same as closing and reopening the world without creating a new class.

close()[source]

Close the attached level and remove temporary files.

Use changed method to check if there are any changes that should be saved before closing.

unload(safe_area=None)[source]

Unload all chunk data not in the safe area.

Parameters

safe_area (Optional[Tuple[str, int, int, int, int]]) – The area that should not be unloaded [dimension, min_chunk_x, min_chunk_z, max_chunk_x, max_chunk_z]. If None will unload all chunk data.

unload_unchanged()[source]

Unload all data that has not been marked as changed.

property chunks: ChunkManager[source]

The chunk container.

Most methods from ChunkManager also exists in the level class.

all_chunk_coords(dimension)[source]

The coordinates of every chunk in this dimension of the level.

This is the combination of chunks saved to the level and chunks yet to be saved.

Return type

Set[Tuple[int, int]]

has_chunk(cx, cz, dimension)[source]

Does the chunk exist. This is a quick way to check if the chunk exists without loading it.

Parameters

  • cx (int) – The x coordinate of the chunk.

  • cz (int) – The z coordinate of the chunk.

  • dimension (str) – The dimension to load the chunk from.

Return type

bool

Returns

True if the chunk exists. Calling get_chunk on this chunk may still throw ChunkLoadError

get_chunk(cx, cz, dimension)[source]

Gets a Chunk class containing the data for the requested chunk.

Parameters

  • cx (int) – The X coordinate of the desired chunk

  • cz (int) – The Z coordinate of the desired chunk

  • dimension (str) – The dimension to get the chunk from

Return type

Chunk

Returns

A Chunk object containing the data for the chunk

Raises

ChunkDoesNotExist: If the chunk does not exist (was deleted or never created)

ChunkLoadError: If the chunk was not able to be loaded. Eg. If the chunk is corrupt or some error occurred when loading.

create_chunk(cx, cz, dimension)[source]

Create an empty chunk and put it at the given location.

If a chunk exists at the given location it will be overwritten.

Parameters

  • cx (int) – The X coordinate of the chunk

  • cz (int) – The Z coordinate of the chunk

  • dimension (str) – The dimension to put the chunk in.

Return type

Chunk

Returns

The newly created Chunk.

put_chunk(chunk, dimension)[source]

Add a given chunk to the level.

Parameters

  • chunk (Chunk) – The Chunk to add to the level. It will be added at the location stored in Chunk.coordinates

  • dimension (str) – The dimension to add the chunk to.

delete_chunk(cx, cz, dimension)[source]

Delete a chunk from the level.

Parameters

  • cx (int) – The X coordinate of the chunk

  • cz (int) – The Z coordinate of the chunk

  • dimension (str) – The dimension to delete the chunk from.

extract_structure(selection, dimension)[source]

Extract the region of the dimension specified by selection to an ImmutableStructure class.

Parameters

  • selection (SelectionGroup) – The selection to extract.

  • dimension (str) – The dimension to extract the selection from.

Return type

ImmutableStructure

Returns

The ImmutableStructure containing the extracted region.

extract_structure_iter(selection, dimension)[source]

Extract the region of the dimension specified by selection to an ImmutableStructure class.

Also yields the progress as a float from 0-1

Parameters

  • selection (SelectionGroup) – The selection to extract.

  • dimension (str) – The dimension to extract the selection from.

Return type

Generator[float, None, ImmutableStructure]

Returns

The ImmutableStructure containing the extracted region.

paste(src_structure, src_dimension, src_selection, dst_dimension, location, scale=(1.0, 1.0, 1.0), rotation=(0.0, 0.0, 0.0), include_blocks=True, include_entities=True, skip_blocks=(), copy_chunk_not_exist=False)[source]

Paste a level into this level at the given location. Note this command may change in the future.

Parameters

  • src_structure (BaseLevel) – The structure to paste into this structure.

  • src_dimension (str) – The dimension of the source structure to copy from.

  • src_selection (SelectionGroup) – The selection to copy from the source structure.

  • dst_dimension (str) – The dimension to paste the structure into.

  • location (Tuple[int, int, int]) – The location where the centre of the structure will be in the level

  • scale (Tuple[float, float, float]) – The scale in the x, y and z axis. These can be negative to mirror.

  • rotation (Tuple[float, float, float]) – The rotation in degrees around each of the axis.

  • include_blocks (bool) – Include blocks when pasting the structure.

  • include_entities (bool) – Include entities when pasting the structure.

  • skip_blocks (Tuple[Block, ...]) – If a block matches a block in this list it will not be copied.

  • copy_chunk_not_exist (bool) – If a chunk does not exist in the source should it be copied over as air. Always False where level is a World.

Returns

paste_iter(src_structure, src_dimension, src_selection, dst_dimension, location, scale=(1.0, 1.0, 1.0), rotation=(0.0, 0.0, 0.0), include_blocks=True, include_entities=True, skip_blocks=(), copy_chunk_not_exist=False)[source]

Paste a structure into this structure at the given location. Note this command may change in the future.

Parameters

  • src_structure (BaseLevel) – The structure to paste into this structure.

  • src_dimension (str) – The dimension of the source structure to copy from.

  • src_selection (SelectionGroup) – The selection to copy from the source structure.

  • dst_dimension (str) – The dimension to paste the structure into.

  • location (Tuple[int, int, int]) – The location where the centre of the structure will be in the level

  • scale (Tuple[float, float, float]) – The scale in the x, y and z axis. These can be negative to mirror.

  • rotation (Tuple[float, float, float]) – The rotation in degrees around each of the axis.

  • include_blocks (bool) – Include blocks when pasting the structure.

  • include_entities (bool) – Include entities when pasting the structure.

  • skip_blocks (Tuple[Block, ...]) – If a block matches a block in this list it will not be copied.

  • copy_chunk_not_exist (bool) – If a chunk does not exist in the source should it be copied over as air. Always False where level is a World.

Return type

Generator[float, None, None]

Returns

A generator of floats from 0 to 1 with the progress of the paste operation.

get_version_block(x, y, z, dimension, version)[source]

Get a block at the specified location and convert it to the format of the version specified

Note the odd return format. In most cases this will return (Block, None) or (Block, BlockEntity) if a block entity is present.

In select cases (like item frames) it may return (Entity, None)

Parameters

  • x (int) – The X coordinate of the desired block

  • y (int) – The Y coordinate of the desired block

  • z (int) – The Z coordinate of the desired block

  • dimension (str) – The dimension of the desired block

  • version (Tuple[str, Union[int, Tuple[int, ...]]]) –

    The version to get the block converted to.

    >>> ("java", (1, 16, 2))  # Java 1.16.2 format
>>> ("java", 2578)  # Java 1.16.2 format (using the data version)
>>> ("bedrock", (1, 16, 210))  # Bedrock 1.16.210 format

Return type

Union[Tuple[Block, BlockEntity], Tuple[Entity, None]]

Returns

The block at the given location converted to the version format. Note the odd return format.

Raises

ChunkDoesNotExist: If the chunk does not exist (was deleted or never created)

ChunkLoadError: If the chunk was not able to be loaded. Eg. If the chunk is corrupt or some error occurred when loading.

set_version_block(x, y, z, dimension, version, block, block_entity=None)[source]

Convert the block and block_entity from the given version format to the universal format and set at the location.

Parameters

  • x (int) – The X coordinate of the desired block.

  • y (int) – The Y coordinate of the desired block.

  • z (int) – The Z coordinate of the desired block.

  • dimension (str) – The dimension of the desired block.

  • version (Tuple[str, Union[int, Tuple[int, ...]]]) –

    The version the given block and block_entity come from.

    >>> ("java", (1, 16, 2))  # Java 1.16.2 format
>>> ("java", 2578)  # Java 1.16.2 format (using the data version)
>>> ("bedrock", (1, 16, 210))  # Bedrock 1.16.210 format

  • block (Block) – The block to set. Must be valid in the specified version.

  • block_entity (Optional[BlockEntity]) – The block entity to set. Must be valid in the specified version.

Returns

The block at the given location converted to the version format. Note the odd return format.

Raises

ChunkLoadError: If the chunk was not able to be loaded. Eg. If the chunk is corrupt or some error occurred when loading.

get_native_entities(cx, cz, dimension)[source]

Get a list of entities in the native format from a given chunk. This currently returns the raw data from the chunk but in the future will convert to the world version format.

Parameters

  • cx (int) – The chunk x position

  • cz (int) – The chunk z position

  • dimension (str) – The dimension of the chunk.

Return type

Tuple[EntityList, Tuple[str, Union[int, Tuple[int, ...]]]]

Returns

A copy of the list of entities and the version format they are in.

set_native_entites(cx, cz, dimension, entities)[source]

Set the entities in the native format. Note that the format must be compatible with level_wrapper.max_world_version.

Parameters

  • cx (int) – The chunk x position

  • cz (int) – The chunk z position

  • dimension (str) – The dimension of the chunk.

  • entities (Iterable[Entity]) – The entities to set on the chunk.

property history_manager: MetaHistoryManager[source]

The class that manages undoing and redoing changes.

create_undo_point(world=True, non_world=True)[source]

Create a restore point for all the data that has changed.

Parameters

  • world – If True the restore point will include world based data.

  • non_world – If True the restore point will include data not related to the world.

Return type

bool

Returns

If True a restore point was created. If nothing changed no restore point will be created.

create_undo_point_iter(world=True, non_world=True)[source]

Create a restore point for all the data that has changed.

Also yields progress from 0-1

Parameters

  • world – If True the restore point will include world based data.

  • non_world – If True the restore point will include data not related to the world.

Return type

Generator[float, None, bool]

Returns

If True a restore point was created. If nothing changed no restore point will be created.

property changed: bool[source]

Has any data been modified but not saved to disk

undo()[source]

Undoes the last set of changes to the level.

redo()[source]

Redoes the last set of changes to the level.

restore_last_undo_point()[source]

Restore the level to the state it was when self.create_undo_point was last called.

If an operation errors there may be modifications made that did not get tracked.

This will revert those changes.

property players: PlayerManager[source]

The player container.

Most methods from PlayerManager also exists in the level class.

all_player_ids()[source]

Returns a set of all player ids that are present in the level.

Return type

Set[str]

has_player(player_id)[source]

Is the given player id present in the level

Parameters

player_id (str) – The player id to check

Return type

bool

Returns

True if the player id is present, False otherwise

get_player(player_id)[source]

Gets the Player object that belongs to the specified player id

If no parameter is supplied, the data of the local player will be returned

Parameters

player_id (str) – The desired player id

Return type

Player

Returns

A Player instance