3D position with world reference, yaw, and pitch

Location

A Location represents a position in a world with rotation angles. It is used for teleportation, block lookups, spawning, and spatial calculations.

Constructor

Location(x=0.0, y=0.0, z=0.0, world=None, yaw=0.0, pitch=0.0)

Create a new location.

• Parameters:
• x (float) — X coordinate. Default 0.
• y (float) — Y coordinate. Default 0.
• z (float) — Z coordinate. Default 0.
• world (World | str | None) — World reference or name. Default None.
• yaw (float) — Horizontal rotation in degrees. Default 0.
• pitch (float) — Vertical rotation in degrees. Default 0. Negative = looking up.

loc = Location(100, 64, -200, "world")
loc = Location(0, 64, 0, "world_nether", yaw=90, pitch=-45)

Attributes

x

• Type: float

X coordinate (East-West).

y

• Type: float

Y coordinate (altitude).

z

• Type: float

Z coordinate (North-South).

world

• Type: World

The world this location is in.

yaw

• Type: float

Horizontal rotation in degrees. 0 = South, 90 = West, 180 = North, 270 = East.

pitch

• Type: float

Vertical rotation in degrees. 0 = level, -90 = straight up, 90 = straight down.

Methods

add

new_loc = location.add(x, y, z)

Create a new location with the given offsets added. This is synchronous — no await needed.

• Parameters:
• x (float) — X offset.
• y (float) — Y offset.
• z (float) — Z offset.
• Returns: Location — A new location (the original is not modified).

above = player.location.add(0, 2, 0)

Arithmetic Operators

Location supports +, -, *, and / operators with Location or Vector operands.

Addition (+)

# Location + Location
new_loc = player.location + Location(1, 0, 0)

# Location + Vector (common for directional offsets)
spawn_pos = player.location + player.look_direction * 3

Subtraction (-)

offset = loc_a - loc_b  # Location representing the difference

The result preserves the world, yaw, and pitch of the left-hand operand.

Multiplication (*)

scaled = location * 2.0  # Scale coordinates by a factor

Division (/)

halved = location / 2.0  # Divide coordinates by a factor

normalize

normalized = location.normalize()

Return a new location with the XYZ components normalized to a unit vector. Synchronous.

• Returns: Location

midpoint

mid = location.midpoint(other)

Return the midpoint between this location and another. Synchronous.

• Parameters:
• other (Location) — The other location.
• Returns: Location

center = loc_a.midpoint(loc_b)

clone

copy = location.clone()

Create an independent copy of this location. Synchronous.

• Returns: Location

distance

d = location.distance(other)

Calculate the Euclidean distance to another location. Synchronous.

• Parameters:
• other (Location) — The other location.
• Returns: float

dist = player.location.distance(spawn_location)
if dist < 10:
    await player.send_message("You're near spawn!")

distance_squared

d2 = location.distance_squared(other)

Calculate the squared distance to another location. Synchronous. Faster than distance() when you only need to compare distances (avoids square root).

• Parameters:
• other (Location) — The other location.
• Returns: float

# More efficient than: if loc.distance(other) < 10
if loc.distance_squared(other) < 100:
    ...

Indexing & Iteration

Location supports indexing, iteration, and unpacking:

# Index access
x = loc[0]  # x
y = loc[1]  # y
z = loc[2]  # z

# Unpacking
x, y, z = loc

# Splat
block = await world.block_at(*loc)

# Length
len(loc)  # 3