Positions

A position represents a location in the Minecraft world. Positions are used in many blocks and commands to spawn mobs, fill blocks and more…

A position is represented by 3 numbers, x, y, and z:

• x: East (positive, +x) or West (negative, -x), also known as longitude in the real world
• y: up (positive, +y) or down (negative, -y), altitude or elevation
• z: South (positive, +z) or North (negative, -z), also known as latitude in the real world

The numbers for x, y, and z are the coordinates (a coordinate is also known as a direction or an axis) of the position.

There are different kinds of positions: world, relative, player, and local, and positions.

World positions

A world position is 3 numbers that are the distances in each direction from the world origin: (0, 0, 0). This is also called an absolute position. World positions aren’t changed by the player’s current position. They always stay the same. For example, the position (5, 2, 15) will always mean the same block in the world, no matter where the player is.

You can create a world position using the ||positions:world 0 0 0|| block.

let worldPos = world(0, 0, 0)

Relative positions

A relative position has ~ before each number and is centered on the player’s current position: (~0, ~0, ~0). Players are two blocks tall, so it is important to note that the position (~0, ~0, ~0) corresponds to the player’s feet.

Because relative positions start from where the player’s feet are, relative positions aren’t fixed in the world - they “move” with the player. For example, the relative position (~0, ~2, ~0) will always correspond to the block that is currently above the player’s head, no matter where the player is in the world. If the player moves, then (~0, ~2, ~0) is no longer at the same block as before the player moved. Keep this in mind when using relative positions in your code!

You can create a relative position using the ||positions:~0 ~0 ~0|| block.

let relativePos = pos(0, 0, 0)

Here are more examples of relative positions:

• The position of the player’s head is 1 block above their feet, its relative position is (~0, ~1, ~0).
• The position of the block 1 block East of the player is (~1, ~0, ~0).
• The position of the block 2 block West, 5 blocks down of the player is (~-2, ~-5, ~0).

Player positions

A player position allows you to specify coordinates to the right/left, above/below, and in front/behind the player. The direction in which the player is facing sets the axes for the coordinates when using a player position. For example, this will place one gold block at a position which is 3 blocks in front of the player:

blocks.place(GOLD_BLOCK, posCamera(0, 0, 3))

For this the example, instead of being placed to the East, West, North, or South of the player, the block is placed directly in front of where the player is looking.

Local positions

A local position has ^ before each number and is centered on the player’s current position: (^0, ^0, ^0), which is at the level of their feet.

A local position is like a relative position execpt that local positions determine the place where the player will be in the direction they are heading. So, instead of East or West the x direction is right (+x) or left (-x). The y direction is up (+y) or down (-y) and the z direction is forward (+z) or backward (-z).

A local position of (^-4, ^8, ^3) is a place that is 4 blocks to the left, 8 blocks up, and 3 blocks ahead of the player.

let localPos = posLocal(-4, 8, 3)

Math operators

You can add, ||positions:+||, two positions together to create a new one.

let p = positions.add(player.position(), pos(10, 15, 20))

Reference

pos(0, 0, 0)
world(0, 0, 0)
posLocal(0, 0, 0)
posCamera(0, 0, 0)
positions.equals(
    pos(0, 0, 0),
    pos(0, 0, 0)
)
positions.add(
    pos(0, 0, 0),
    pos(0, 0, 0)
)
randpos(
    pos(0, 0, 0),
    pos(0, 0, 0)
)
pos(0, 0, 0).getValue(Axis.X)
pos(0, 0, 0).toWorld()
pos(0, 0, 0).toString()
positions.groundPosition(pos(0, 0, 0))