# 🧭 Position#

#bs.position:help

Manage entity positions and rotations using scores.

“The excitement lies in the exploration of the world around us.”

—Jim Peebles

## 🔧 Functions#

You can find below all functions available in this module.

### Canonical to local#

#bs.position:canonical_to_local

Convert a canonical position (using the relative reference frame) into a local position (using the local reference frame).

Inputs:

Execution rotated as <entity> or rotated <h> <v>: Rotation used for the conversion.

Scores @s bs.pos.[x,y,z]: Position to convert.

Outputs:

Scores @s bs.pos.[x,y,z]: Converted position.

Credits: Aksiome

### Get distance#

#bs.position:get_distance_ata {scale:<scaling>}

Compute the distance between the source entity and the execution position of the function.

Inputs:

Execution as <entities>: Entity positioned at the reference point.

Execution at <entity> or positioned <x> <y> <z>: Position to get the distance from.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Return | Score $position.get_distance_ata bs.out: Distance between the two positions. Calculate the distance between you and the nearest sheep (in blocks, without scaling): # Once execute at @e[type=sheep,limit=1,sort=nearest] run function #bs.position:get_distance_ata {scale:1} # See the result tellraw @a [{"text": "Distance: ", "color": "dark_gray"},{"score":{"name":"$position.get_distance_ata", "objective": "bs.out"}, "color": "gold"}]


Performance tip

For several applications such as comparing distances, you can use the squared distance instead of the “normal” distance. It is a bit faster to compute.

#bs.position:get_distance_squared_ata {scale:<scaling>}

Compute the squared distance between the source entity and the execution position of the function.

Inputs:

Execution as <entities>: Entity positioned at the reference point.

Execution at <entity> or positioned <x> <y> <z>: Position to get the distance from.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Return | Score $position.get_distance_ata bs.out: Squared distance between the two positions. Calculate the squared distance between you and the nearest sheep (in blocks, without scaling): # Once execute at @e[type=sheep,limit=1,sort=nearest] run function #bs.position:get_distance_squared_ata {scale:1} # See the result tellraw @a [{"text": "Distance^2: ", "color": "dark_gray"},{"score":{"name":"$position.get_distance_squared_ata", "objective": "bs.out"}, "color": "gold"}]


Score limitation

Scores in Minecraft have a limited size similar to a signed int variable. The latter is huge, but not unlimited and can overflow. Since this function uses powers of 2 to calculate the result, you should prefer the “normal” version (which does not rely on powers) when working over big distances.

Credits: Aksiome, Leirof

### Get position#

#bs.position:get_pos {scale:<scaling>}

Get the execution position of the function and store the coordinates in 3 scores.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or positioned <x> <y> <z>: Position to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Scores @s bs.pos.[x,y,z]: Coordinates of the position.

Detect and display the position of the nearest spider (without scaling):

# Once
execute as @e[type=spider,limit=1,sort=nearest] run function #bs.position:get_pos {scale:1}

# See the resluts
tellraw @a [{"text": "X = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.x"}, "color": "gold"},{"text":", Y = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.y"}, "color": "gold"},{"text":", Z = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.z"}, "color": "gold"}]

#bs.position:get_pos_x {scale:<scaling>}

Get the execution x position of the function and store the coordinate in a score.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or positioned <x> <y> <z>: Position to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Score @s bs.pos.x: Coordinates of the position.

Detect and display the x position of the nearest spider (without scaling):

# Once
execute as @e[type=spider,limit=1,sort=nearest] run function #bs.position:get_pos_x {scale:1}

# See the resluts
tellraw @a [{"text": "X = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.x"}, "color": "gold"}]

#bs.position:get_pos_y {scale:<scaling>}

Get the execution y position of the function and store the coordinate in a score.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or positioned <x> <y> <z>: Position to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Score @s bs.pos.y: Coordinates of the position.

Detect and display the y position of the nearest spider (without scaling):

# Once
execute as @e[type=spider,limit=1,sort=nearest] run function #bs.position:get_pos_y {scale:1}

# See the resluts
tellraw @a [{"text": "Y = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.y"}, "color": "gold"}]

#bs.position:get_pos_z {scale:<scaling>}

Get the execution z position of the function and store the coordinate in a score.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or positioned <x> <y> <z>: Position to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Score @s bs.pos.z: Coordinates of the position.

Detect and display the z position of the nearest spider (without scaling):

# Once
execute as @e[type=spider,limit=1,sort=nearest] run function #bs.position:get_pos_z {scale:1}

# See the resluts
tellraw @a [{"text": "Z = ", "color": "dark_gray"},{"score":{"name":"@e[type=spider,limit=1,sort=nearest]", "objective": "bs.pos.z"}, "color": "gold"}]


Credits: Aksiome, Leirof

### Get relative#

#bs.position:get_relative_ata {scale:<scaling>}

Get the execution position of the function relatively to the position of the executing entity.

Inputs:

Execution as <entities>: Entity considered at the reference point.

Execution at <entity> or positioned <x> <y> <z>: Position te get the relative position from.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Scores @s bs.pos.[x,y,z]: Relative coordinates.

Get your position relative to the nearest Creeper (without scaling):

# Once
execute as @s at @e[type=creeper,limit=1,sort=nearest] run function #bs.position:get_relative_ata {scale:1}

# See the result
tellraw @a [{"text": "Relative position : X=", "color": "dark_gray"},{"score":{"name":"@s", "objective": "bs.pos.x"}, "color": "gold"},{"text":", Y=", "color": "dark_gray"},{"score":{"name":"@s", "objective": "bs.pos.y"},"color":"gold"},{"text":", Z=","color":"dark_gray"},{"score":{"name":"@s","objective":"bs.pos.z"},"color":"gold"}]

#bs.position:get_relative_from_dir {scale:<scaling>}

Get a direction vector based on the execution position and rotation. Scale is used as the norm/length.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or positioned <x> <y> <z> rotated <h> <v>: Position and rotation te get the relative position from.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Scores @s bs.pos.[x,y,z]: Relative coordinates.

Get your position relative to the position that is 2 blocks in front of you (scaled by 1000):

# Once
execute at @s run function #bs.position:get_relative_from_dir {scale:2000}

# See the result
tellraw @a [{"text": "Relative position : X=", "color": "dark_gray"},{"score":{"name":"@s", "objective": "bs.pos.x"}, "color": "gold"},{"text":", Y=", "color": "dark_gray"},{"score":{"name":"@s", "objective": "bs.pos.y"},"color":"gold"},{"text":", Z=","color":"dark_gray"},{"score":{"name":"@s","objective":"bs.pos.z"},"color":"gold"}]


Credits: Aksiome, Leirof

### Get rotation#

#bs.position:get_rot {scale:<scaling>}

Get the execution rotation of the function and store it in 2 scores.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or rotated <h> <v>: Rotation to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Scores @s bs.rot.[h,v]: Rotation of the position.

#bs.position:get_rot_h {scale:<scaling>}

Get the execution horizontal rotation of the function.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or rotated <h> <v>: Rotation to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Score @s bs.rot.h: Horizontal rotation of the position.

#bs.position:get_rot_v {scale:<scaling>}

Get the execution vertical rotation of the function.

Inputs:

Execution as <entities>: Entity to store the score to.

Execution at <entity> or rotated <h> <v>: Rotation to get.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

Score @s bs.rot.v: Vertical rotation of the position.

Credits: Aksiome, Leirof, theogiraudet

### Local to canonical#

#bs.position:local_to_canonical

Convert a local position (using the local reference frame) into a canonical position (using the relative reference frame).

Inputs:

Execution rotated as <entity> or rotated <h> <v>: Rotation used for the conversion.

Scores @s bs.pos.[x,y,z]: Position to convert.

Outputs:

Scores @s bs.pos.[x,y,z]: Converted position.

Credits: Aksiome

### Normalize rotation#

#bs.position:normalize_rot

Normalize rotations (replace the bs.rot.h and bs.rot.v scores respectively in the interval [0;360[ and [0;180[)

Credits: Leirof

### Set position#

#bs.position:set_pos {scale:<scaling>}

Place an entity at coordinates given by scores.

Inputs:

Execution as <entities>: Entity to teleport.

Scores @s bs.pos.[x,y,z]: Coordinates to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the coordinates indicated by the scores.

Teleport to 48.85 0 2.29:

# Once
scoreboard players set @s bs.pos.x 4885
scoreboard players set @s bs.pos.y 0
scoreboard players set @s bs.pos.z 229
function #bs.position:set_pos {scale:0.001}

#bs.position:set_pos_x {scale:<scaling>}

Place an entity at a precise x coordinate given by scores.

Inputs:

Execution as <entities>: Entity to teleport.

Score @s bs.pos.x: Coordinate x to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the x coordinate indicated by the score.

Teleport to 70 ~ ~:

# Once
scoreboard players set @s bs.pos.x 70
function #bs.position:set_pos_x {scale:1}

#bs.position:set_pos_y {scale:<scaling>}

Place an entity at a precise y coordinate given by scores.

Inputs:

Execution as <entities>: Entity to teleport.

Score @s bs.pos.y: Coordinate y to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the y coordinate indicated by the score.

Teleport to ~ 82 ~:

# Once
scoreboard players set @s bs.pos.y 82
function #bs.position:set_pos_y {scale:1}

#bs.position:set_pos_z {scale:<scaling>}

Place an entity at a precise z coordinate given by scores.

Inputs:

Execution as <entities>: Entity to teleport.

Score @s bs.pos.z: Coordinate z to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the z coordinate indicated by the score.

Teleport to ~ ~ 65:

# Once
scoreboard players set @s bs.pos.z 65
function #bs.position:set_pos_z {scale:1}


Credits: Aksiome, Leirof

### Set rotation#

#bs.position:set_rot {scale:<scaling>}

Rotate an entity according to its scores.

Inputs:

Execution as <entities>: Entity to teleport.

Scores @s bs.rot.[h,v]: Rotation to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the rotation indicated by the scores.

#bs.position:set_rot_h {scale:<scaling>}

Rotate an entity according to its horizontal rotation score.

Inputs:

Execution as <entities>: Entity to teleport.

Score @s bs.rot.h: Rotation to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the rotation indicated by the horizontal score.

#bs.position:set_rot_v {scale:<scaling>}

Rotate an entity according to its vertical rotation score.

Inputs:

Execution as <entities>: Entity to teleport.

Score @s bs.rot.v: Rotation to teleport to.

Macro Var scale: Scalar for the function’s outputs.

Outputs:

State: Entity is teleported to the rotation indicated by the vertical score.

Credits: Aksiome, Leirof, theogiraudet