Level

endstone.level

Classes:

Name	Description
Chunk	Represents a chunk of blocks.
Dimension	Represents a dimension within a Level.
DimensionCreator	Represents the options that may be used to create a custom dimension.
Level	Represents a level, which may contain actors, chunks and blocks.
Location	Represents a 3-dimensional location in a dimension within a level.

Chunk

Represents a chunk of blocks.

Methods:

Name	Description
add_plugin_chunk_ticket	Adds a plugin ticket for this chunk, loading it if it is not already loaded.
load	Requests this chunk to be loaded, and keeps it resident until it is released again.
remove_plugin_chunk_ticket	Removes the given plugin's ticket for this chunk.
unload	Releases the hold that load placed on this chunk, and unloads it if nothing else keeps it resident.

Attributes:

Name	Type	Description
block_actors	list[BlockState]	The state of every block actor in this chunk, or an empty list if this chunk is not loaded.
dimension	Dimension	The dimension containing this chunk.
is_loaded	bool	Whether this chunk is loaded.
level	Level	The level containing this chunk.
plugin_chunk_tickets	list[Plugin]	The Plugins holding a ticket for this chunk.
x	int	X-coordinate of this chunk.
z	int	Z-coordinate of this chunk.

block_actors property

block_actors: list[BlockState]

The state of every block actor in this chunk, or an empty list if this chunk is not loaded.

dimension property

dimension: Dimension

The dimension containing this chunk.

is_loaded property

is_loaded: bool

Whether this chunk is loaded.

level property

level: Level

The level containing this chunk.

plugin_chunk_tickets property

plugin_chunk_tickets: list[Plugin]

The Plugins holding a ticket for this chunk.

x property

x: int

X-coordinate of this chunk.

z property

z: int

Z-coordinate of this chunk.

add_plugin_chunk_ticket

add_plugin_chunk_ticket(plugin: Plugin) -> bool

Adds a plugin ticket for this chunk, loading it if it is not already loaded.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin taking the ticket.	required

Returns:

Type	Description
bool	True if a plugin ticket was added, False if the plugin already holds one for this chunk.

load

load(generate: bool = True) -> bool

Requests this chunk to be loaded, and keeps it resident until it is released again.

See Dimension.load_chunk for how the hold behaves.

Parameters:

Name	Type	Description	Default
generate	bool	Whether to generate the chunk if it does not exist yet.	True

Returns:

Type	Description
bool	False if generate is False and the chunk has not been generated, otherwise True.

remove_plugin_chunk_ticket

remove_plugin_chunk_ticket(plugin: Plugin) -> bool

Removes the given plugin's ticket for this chunk.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin whose ticket to remove.	required

Returns:

Type	Description
bool	True if a plugin ticket was removed, False if the plugin holds none for this chunk.

unload

unload() -> bool

Releases the hold that load placed on this chunk, and unloads it if nothing else keeps it resident.

Returns:

Type	Description
bool	True if the chunk is no longer loaded, otherwise False.

Dimension

Represents a dimension within a Level.

Methods:

Name	Description
add_plugin_chunk_ticket	Adds a plugin ticket for the Chunk at the given coordinates, loading it if it is not already loaded.
drop_item	Drops an item at the specified Location.
get_block_at
get_highest_block_at
get_highest_block_y_at	Gets the highest non-empty (impassable) coordinate at the given coordinates.
get_plugin_chunk_tickets	Gets which plugins hold a ticket for the Chunk at the given coordinates.
is_chunk_generated	Checks if the Chunk at the given coordinates has been generated.
is_chunk_loaded	Checks if the Chunk at the given coordinates is loaded.
load_chunk	Requests the Chunk at the given coordinates to be loaded, and keeps it resident until it is released again.
remove_plugin_chunk_ticket	Removes the given plugin's ticket for the Chunk at the given coordinates.
remove_plugin_chunk_tickets	Removes every ticket the given plugin holds in this dimension.
spawn_actor	Creates an actor at the given Location.
unload_chunk	Releases the hold that load_chunk placed on the Chunk at the given coordinates, and unloads it if nothing
unload_chunk_request	Releases the hold that load_chunk placed on the Chunk at the given coordinates, without unloading it now.

Attributes:

Name	Type	Description
NETHER	Identifier[Dimension]
OVERWORLD	Identifier[Dimension]
THE_END	Identifier[Dimension]
actors	list[Actor]	A list of all actors currently residing in this dimension.
id	Identifier[Dimension]	The identifier of this dimension.
is_valid	bool	Whether this dimension is still valid (loaded).
level	Level	The level to which this dimension belongs.
loaded_chunks	list[Chunk]	A list of all loaded Chunks.
mobs	list[Mob]	A list of all mobs currently residing in this dimension.
players	list[Player]	A list of all players currently residing in this dimension.
plugin_chunk_tickets	dict[Plugin, list[Chunk]]	The Chunks each Plugin holds a ticket for, as a snapshot.
translation_key	str	The translation key, suitable for use in a translation component.

NETHER class-attribute instance-attribute

NETHER: Identifier[Dimension] = 'minecraft:nether'

OVERWORLD class-attribute instance-attribute

OVERWORLD: Identifier[Dimension] = 'minecraft:overworld'

THE_END class-attribute instance-attribute

THE_END: Identifier[Dimension] = 'minecraft:the_end'

actors property

actors: list[Actor]

A list of all actors currently residing in this dimension.

id property

id: Identifier[Dimension]

The identifier of this dimension.

is_valid property

is_valid: bool

Whether this dimension is still valid (loaded).

level property

level: Level

The level to which this dimension belongs.

loaded_chunks property

loaded_chunks: list[Chunk]

A list of all loaded Chunks.

mobs property

mobs: list[Mob]

A list of all mobs currently residing in this dimension.

players property

players: list[Player]

A list of all players currently residing in this dimension.

plugin_chunk_tickets property

plugin_chunk_tickets: dict[Plugin, list[Chunk]]

The Chunks each Plugin holds a ticket for, as a snapshot.

translation_key property

translation_key: str

The translation key, suitable for use in a translation component.

add_plugin_chunk_ticket

add_plugin_chunk_ticket(
    x: int, z: int, plugin: Plugin
) -> bool

Adds a plugin ticket for the Chunk at the given coordinates, loading it if it is not already loaded.

A plugin ticket keeps the chunk resident until it is explicitly removed or the owning plugin is disabled. A plugin may only have one ticket per chunk, but each chunk can have multiple plugin tickets. unload_chunk does not remove plugin tickets.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required
plugin	Plugin	Plugin taking the ticket.	required

Returns:

Type	Description
bool	True if a plugin ticket was added, False if the plugin already holds one for this chunk.

Raises:

Type	Description
RuntimeError	If the plugin is not enabled, or if called from a thread other than the server thread.

drop_item

drop_item(location: Location, item: ItemStack) -> Item

Drops an item at the specified Location.

Parameters:

Name	Type	Description	Default
location	Location	Location to drop the item.	required
item	ItemStack	ItemStack to drop.	required

Returns:

Type	Description
Item	Item entity created as a result of this method.

get_block_at

get_block_at(location: Location) -> Block

get_block_at(x: int, y: int, z: int) -> Block

get_highest_block_at

get_highest_block_at(location: Location) -> Block

get_highest_block_at(x: int, z: int) -> Block

get_highest_block_y_at

get_highest_block_y_at(x: int, z: int) -> int

Gets the highest non-empty (impassable) coordinate at the given coordinates.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the blocks.	required
z	int	Z-coordinate of the blocks.	required

Returns:

Type	Description
int	Y-coordinate of the highest non-empty block.

get_plugin_chunk_tickets

get_plugin_chunk_tickets(x: int, z: int) -> list[Plugin]

Gets which plugins hold a ticket for the Chunk at the given coordinates.

The returned list is a snapshot; it does not track tickets added or removed afterwards.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required

Returns:

Type	Description
list[Plugin]	The Plugins holding a ticket for the chunk.

is_chunk_generated

is_chunk_generated(x: int, z: int) -> bool

Checks if the Chunk at the given coordinates has been generated.

A chunk counts as generated once it is loaded or has been written to the level's chunk storage.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required

Returns:

Type	Description
bool	True if the chunk has been generated, otherwise False.

is_chunk_loaded

is_chunk_loaded(x: int, z: int) -> bool

Checks if the Chunk at the given coordinates is loaded.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required

Returns:

Type	Description
bool	True if the chunk is loaded, otherwise False.

load_chunk

load_chunk(x: int, z: int, generate: bool = True) -> bool

Requests the Chunk at the given coordinates to be loaded, and keeps it resident until it is released again.

The chunk is held from the moment this returns until unload_chunk or unload_chunk_request releases it, or the server restarts. Unlike Java Edition, Bedrock has no synchronous chunk load: unless the chunk was already resident, the load finishes on a later tick, so is_chunk_loaded may still report False right afterwards. A chunk held this way stays in memory but is not ticked, and the hold never expires on its own. Intended for keeping a handful of chunks resident, not for loading large regions.

The hold is not attributed to any plugin and survives that plugin being disabled. Use add_plugin_chunk_ticket for a hold that is released automatically.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required
generate	bool	Whether to generate the chunk if it does not exist yet.	True

Returns:

Type	Description
bool	False if generate is False and the chunk has not been generated, or if the coordinates lie outside
bool	the world limit, otherwise True.

Raises:

Type	Description
RuntimeError	If called from a thread other than the server thread.

remove_plugin_chunk_ticket

remove_plugin_chunk_ticket(
    x: int, z: int, plugin: Plugin
) -> bool

Removes the given plugin's ticket for the Chunk at the given coordinates.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required
plugin	Plugin	Plugin whose ticket to remove.	required

Returns:

Type	Description
bool	True if a plugin ticket was removed, False if the plugin holds none for this chunk.

remove_plugin_chunk_tickets

remove_plugin_chunk_tickets(plugin: Plugin) -> None

Removes every ticket the given plugin holds in this dimension.

Parameters:

Name	Type	Description	Default
plugin	Plugin	Plugin whose tickets to remove.	required

spawn_actor

spawn_actor(
    location: Location, type: Identifier[ActorType] | str
) -> Actor | None

Creates an actor at the given Location.

Parameters:

Name	Type	Description	Default
location	Location	The location to spawn the actor.	required
type	Identifier[ActorType] | str	The actor type to spawn.	required

Returns:

Type	Description
Actor | None	Resulting Actor of this method.

unload_chunk

unload_chunk(x: int, z: int) -> bool

Releases the hold that load_chunk placed on the Chunk at the given coordinates, and unloads it if nothing else keeps it resident.

A chunk kept alive by a nearby player, the spawn area, a /tickingarea or a plugin chunk ticket stays loaded, and this reports False. Unloading a chunk saves it and fires a ChunkUnloadEvent, which handlers observe before this returns. It also completes any chunk unloads the dimension had pending, so calling it once per chunk over a large area is expensive; use unload_chunk_request when releasing many chunks at once.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required

Returns:

Type	Description
bool	True if the chunk is no longer loaded, otherwise False.

Raises:

Type	Description
RuntimeError	If called from a thread other than the server thread.

unload_chunk_request

unload_chunk_request(x: int, z: int) -> bool

Releases the hold that load_chunk placed on the Chunk at the given coordinates, without unloading it now.

The chunk is unloaded on a later tick once nothing else keeps it resident.

Parameters:

Name	Type	Description	Default
x	int	X-coordinate of the chunk.	required
z	int	Z-coordinate of the chunk.	required

Returns:

Type	Description
bool	True.

Raises:

Type	Description
RuntimeError	If called from a thread other than the server thread.

DimensionCreator

DimensionCreator(id: Identifier[Dimension] | str)

Represents the options that may be used to create a custom dimension.

Creates an instance of a DimensionCreator for the given dimension id.

Parameters:

Name	Type	Description	Default
id	Identifier[Dimension] | str	The identifier of the dimension to create, e.g. myplugin:void_realm.	required

Attributes:

Name	Type	Description
id	Identifier[Dimension]	The identifier of the dimension that is being created.

id property

id: Identifier[Dimension]

The identifier of the dimension that is being created.

Level

Represents a level, which may contain actors, chunks and blocks.

Methods:

Name	Description
create_dimension	Creates a new custom dimension within this level.
get_dimension	Gets the dimension with the given id.
get_game_rule
has_game_rule	Checks if a game rule exists.
set_game_rule

Attributes:

Name	Type	Description
actors	list[Actor]	A list of all actors currently residing in this level.
dimensions	list[Dimension]	A list of all dimensions within this level.
name	str	The unique name of this level.
recipes	list[Recipe]	The list of crafting recipes.
seed	int	The Seed for this level.
time	int	The relative in-game time of this level.

actors property

actors: list[Actor]

A list of all actors currently residing in this level.

dimensions property

dimensions: list[Dimension]

A list of all dimensions within this level.

name property

name: str

The unique name of this level.

recipes property

recipes: list[Recipe]

The list of crafting recipes.

seed property

seed: int

The Seed for this level.

time property writable

time: int

The relative in-game time of this level.

create_dimension

create_dimension(
    creator: DimensionCreator,
) -> Dimension | None

Creates a new custom dimension within this level.

Custom dimensions are empty (void) dimensions identified by a namespaced id, e.g. myplugin:void_realm; populate them with blocks, structures or actors afterward.

The level remembers which id belongs to which name, so a dimension's terrain and actors survive a restart. The registration itself does not: call this again on every startup to get the same dimension back.

If a dimension with the requested name already exists, that existing dimension is returned instead.

Parameters:

Name	Type	Description	Default
creator	DimensionCreator	The options to use when creating the dimension. An identifier or plain string is also accepted as the name.	required

Returns:

Type	Description
Dimension | None	The newly created (or existing) Dimension, or None if it could not be created.

get_dimension

get_dimension(
    id: Identifier[Dimension] | str,
) -> Dimension | None

Gets the dimension with the given id.

Parameters:

Name	Type	Description	Default
id	Identifier[Dimension] | str	The id of the dimension to retrieve.	required

Returns:

Type	Description
Dimension | None	The Dimension with the given id, or None if none exists.

get_game_rule

get_game_rule(rule: Identifier[GameRule[_T]]) -> _T

get_game_rule(rule: str) -> bool | int | float

has_game_rule

has_game_rule(rule: Identifier[GameRule] | str) -> bool

Checks if a game rule exists.

Parameters:

Name	Type	Description	Default
rule	Identifier[GameRule] | str	The Minecraft game rule to check.	required

Returns:

Type	Description
bool	True if the game rule exists.

set_game_rule

set_game_rule(
    rule: Identifier[GameRule[_T]], value: _T
) -> None

set_game_rule(rule: str, value: bool | float) -> None

Location

Location(
    dimension: Dimension | None,
    x: float,
    y: float,
    z: float,
    pitch: float = 0.0,
    yaw: float = 0.0,
)

Represents a 3-dimensional location in a dimension within a level.

Methods:

Name	Description
distance	Get the distance between this location and another.
distance_squared	Get the squared distance between this location and another.
normalize_pitch	Normalizes the given pitch angle to a value between +/-90 degrees.
normalize_yaw	Normalizes the given yaw angle to a value between +/-180 degrees.
zero	Zero this location's components. Not world-aware.

Attributes:

Name	Type	Description
block	Block	The block at the represented location.
block_x	int	The floored value of the X component, indicating the block that this location is contained with.
block_y	int	The floored value of the Y component, indicating the block that this location is contained with.
block_z	int	The floored value of the Z component, indicating the block that this location is contained with.
dimension	Dimension | None	The Dimension that contains this position, or None if it is not set.
direction	Vector	A unit-vector pointing in the direction that this Location is facing.
is_dimension_loaded	bool	Whether the dimension of this location is present and still loaded.
length	float	The magnitude of the location, defined as sqrt(x^2+y^2+z^2).
length_squared	float	The magnitude of the location squared.
pitch	float	The pitch of this location, measured in degrees.
x	float	The x-coordinate of this location.
y	float	The y-coordinate of this location.
yaw	float	The yaw of this location, measured in degrees.
z	float	The z-coordinate of this location.

block property

block: Block

The block at the represented location.

block_x property

block_x: int

The floored value of the X component, indicating the block that this location is contained with.

block_y property

block_y: int

The floored value of the Y component, indicating the block that this location is contained with.

block_z property

block_z: int

The floored value of the Z component, indicating the block that this location is contained with.

dimension property writable

dimension: Dimension | None

The Dimension that contains this position, or None if it is not set.

direction property writable

direction: Vector

A unit-vector pointing in the direction that this Location is facing.

is_dimension_loaded property

is_dimension_loaded: bool

Whether the dimension of this location is present and still loaded.

length property

length: float

The magnitude of the location, defined as sqrt(x^2+y^2+z^2).

Not world-aware and orientation independent.

length_squared property

length_squared: float

The magnitude of the location squared.

Not world-aware and orientation independent.

pitch property writable

pitch: float

The pitch of this location, measured in degrees.

x property writable

x: float

The x-coordinate of this location.

y property writable

y: float

The y-coordinate of this location.

yaw property writable

yaw: float

The yaw of this location, measured in degrees.

z property writable

z: float

The z-coordinate of this location.

distance

distance(other: Location) -> float

Get the distance between this location and another.

Parameters:

Name	Type	Description	Default
other	Location	The other location.	required

Returns:

Type	Description
float	The distance.

distance_squared

distance_squared(other: Location) -> float

Get the squared distance between this location and another.

Parameters:

Name	Type	Description	Default
other	Location	The other location.	required

Returns:

Type	Description
float	The distance.

normalize_pitch staticmethod

normalize_pitch(pitch: float) -> float

Normalizes the given pitch angle to a value between +/-90 degrees.

Parameters:

Name	Type	Description	Default
pitch	float	The pitch in degrees.	required

Returns:

Type	Description
float	The normalized pitch in degrees.

normalize_yaw staticmethod

normalize_yaw(yaw: float) -> float

Normalizes the given yaw angle to a value between +/-180 degrees.

Parameters:

Name	Type	Description	Default
yaw	float	The yaw in degrees.	required

Returns:

Type	Description
float	The normalized yaw in degrees.

zero

zero() -> Location

Zero this location's components. Not world-aware.