amulet.api.level.immutable_structure
package¶
- class amulet.api.level.ImmutableStructure[source]¶
Bases:
BaseLevel
This is a special version of the level class that is only used when extracting a region of the world.
It is much the same as a normal level class but does not have an associated file/folder data like
World
andStructure
do.To extract a section of a world you should use
extract_structure()
.- __init__()[source]¶
Construct an
ImmutableStructure
instance.You probably don’t want to call this directly.
To extract a section of a world you should use
extract_structure()
.
- 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
- Returns
The build volume for the dimension.
- classmethod from_level(level, selection, dimension)[source]¶
Extract a section of the level into an
ImmutableStructure
class.- Parameters
level (
BaseLevel
) – The level to extract the area from.selection (
SelectionGroup
) – The selection to extract.dimension (
str
) – The dimension to extract from.
- Returns
The created instance of
ImmutableStructure
- classmethod from_level_iter(level, selection, dimension)[source]¶
Extract a section of the level into an
ImmutableStructure
class.Also yields the progress from 0-1.
- Parameters
level (
BaseLevel
) – The level to extract the area from.selection (
SelectionGroup
) – The selection to extract.dimension (
str
) – The dimension to extract from.
- Return type
- Returns
The created instance of
ImmutableStructure
- 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.
- 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.
- 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.
- 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
- 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
- extract_structure(selection, dimension)[source]¶
Extract the region of the dimension specified by
selection
to anImmutableStructure
class.- Parameters
selection (
SelectionGroup
) – The selection to extract.dimension (
str
) – The dimension to extract the selection from.
- Return type
- Returns
The
ImmutableStructure
containing the extracted region.
- extract_structure_iter(selection, dimension)[source]¶
Extract the region of the dimension specified by
selection
to anImmutableStructure
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
- 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
- Return type
- 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
- Return type
- 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
andSelectionBox
instances into that chunkIf 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 usebounds()
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
- 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 usebounds()
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 chunkIf 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 usebounds()
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
- 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 upselection (
Union
[SelectionGroup
,SelectionBox
,None
]) – An optional selection. The overlap of this and self.selection will be useddestination_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 upselection (
Union
[SelectionGroup
,SelectionBox
,None
]) – An optional selection. The overlap of this and the dimensions bounds will be useddestination_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.
- get_player(player_id)[source]¶
Gets the
Player
object that belongs to the specified player idIf 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 blocky (
int
) – The Y coordinate of the desired blockz (
int
) – The Z coordinate of the desired blockdimension (
str
) – The dimension of the desired blockversion (
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
- 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.
- 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.
- property level_wrapper: FormatWrapper[source]¶
A class to access data directly from the level.
- 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 levelscale (
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 levelscale (
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
- 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.
- purge()[source]¶
Unload all loaded and cached data.
This is functionally the same as closing and reopening the world without creating a new class.
- 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
- 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.
- 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.
- 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
andblock_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 translation_manager: TranslationManager[source]¶
An instance of the translation class for use with this level.