Worlds and dimensions

Reach the running level, enumerate its dimensions, and work with locations and positions.

A Bedrock world is a level, and a level holds one or more dimensions - the overworld, the nether, and the end. Everything with a position - players, spawns, blocks - lives inside a dimension, addressed by x, y, z coordinates. This page covers reaching the level and its dimensions and working with locations; see Blocks to read and place the blocks inside them.

Reach the level and its dimensions

The server exposes the running world at self.server.level. From the level you read its name and seed, and you enumerate the dimensions inside it:

src/endstone_my_plugin/my_plugin.py

from endstone.level import Dimension
from endstone.plugin import Plugin

class MyPlugin(Plugin):
    api_version = "0.11"

    def on_enable(self) -> None:
        level = self.server.level
        self.logger.info(f"World: {level.name}, seed {level.seed}")

        for dimension in level.dimensions:
            self.logger.info(f"  dimension {dimension.id}")

        overworld = level.get_dimension(Dimension.OVERWORLD)

Level is the world as a whole - its name, seed, the in-game time, and the list of actors across every dimension.
Dimension is one space within that level. Get them all from level.dimensions, or fetch one by id with level.get_dimension(Dimension.OVERWORLD). The constants Dimension.OVERWORLD, Dimension.NETHER, and Dimension.THE_END are Identifiers, and get_dimension also accepts the raw string ("minecraft:overworld"). Each dimension's id is that same Identifier.

The in-game time lives on the level, not the dimension: read and write level.time as an integer of ticks. Endstone's level API does not currently expose weather or game rules - drive those with the vanilla /weather and /gamerule commands through server.dispatch_command if you need them.

Locations and positions

A Location is a point inside a dimension: a dimension plus x, y, z, and an optional pitch and yaw facing. It's what blocks report for their position and what teleports and spawns consume.

from endstone.level import Location

loc = Location(overworld, 100.0, 64.0, -200.0)

loc.x, loc.y, loc.z              # the float coordinates
loc.block_x, loc.block_y, loc.block_z  # floored to the block they sit in
loc.dimension                    # the dimension this location belongs to

The coordinates are floats, so a location can sit anywhere within a block. The block_x / block_y / block_z properties floor each axis to the integer coordinate of the block that contains the point - exactly what you pass when looking a block up by coordinate.

Locations are how you address the blocks in a dimension - see Blocks to read and place them.

Worlds and dimensions

Reach the level and its dimensions

Locations and positions

On this page