amulet.api.level.structure module

class amulet.api.level.Structure(directory, structure_wrapper)[source]

Bases: BaseLevel

Class that handles editing of any structure format via an separate and flexible data format

__init__(directory, structure_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 – 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 – The FormatWrapper instance that the level will wrap around.

property level_wrapper: StructureFormatWrapper[source]

A class to access data directly from the level.

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]]

all_player_ids()[source]

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

Return type

Set[str]

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 block_palette: BlockManager[source]

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

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 changed: bool[source]

Has any data been modified but not saved to disk

property chunks: ChunkManager[source]

The chunk container.

Most methods from ChunkManager also exists in the level 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.

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.

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.

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.

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

The dimensions strings that are valid for this level.

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.

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_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.

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_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_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

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_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.

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

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.

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

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

property history_manager: MetaHistoryManager[source]

The class that manages undoing and redoing changes.

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.

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.

property players: PlayerManager[source]

The player container.

Most methods from PlayerManager also exists in the level class.

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.

purge()[source]

Unload all loaded and cached data.

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

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.

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.

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

property selection_bounds: SelectionGroup[source]

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

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.

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.

property sub_chunk_size: int[source]

The normal dimensions of the chunk.

property translation_manager: TranslationManager[source]

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

undo()[source]

Undoes the last set of changes to the level.

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.