Coordinate System in Commands and Functions

Minecraft Bedrock uses a three-dimensional Cartesian coordinate system consisting of X, Y, and Z axes. The X-axis runs east and west, where positive X points due east and negative X points due west. The Z-axis runs north and south, where positive Z points due south and negative Z points due north. The Y-axis represents vertical elevation, with positive Y pointing straight up into the sky and negative Y pointing down toward the void. In the Overworld, the buildable vertical range spans from Y = -64 to Y = 320, whereas the Nether and the End operate within a range of Y = 0 to Y = 256.

A common point of friction for add-on developers is the difference between integer block coordinates and floating-point entity coordinates. Every block in the world occupies a 1x1x1 meter cube, and its integer coordinate refers to its lower-north-west corner—specifically, the corner with the lowest X, Y, and Z values. A block at `10 64 20` spans from `10.0` to `11.0` on the X-axis, `64.0` to `65.0` on the Y-axis, and `20.0` to `21.0` on the Z-axis.

When you use a command like `/setblock` or `/fill`, the engine automatically snaps any floating-point numbers down (floors them) to find the integer block grid. However, when you use `/tp` or `/summon` with integer coordinates, Bedrock often applies automatic centering on the X and Z axes, placing the entity at `.5` so it stands in the middle of the block rather than clipping into neighboring walls. If you want exact placement without automatic centering, always provide explicit decimal values in your function files, such as `10.0 64.0 20.0` or `10.5 64.0 20.5`.

Commands accept three distinct coordinate notations: absolute (numbers), relative (tildes `~`), and local (carets `^`). Absolute coordinates always refer to an exact, fixed location in the active dimension, regardless of who is running the command or where they are standing. For example, `0 64 0` will always target that exact location in the world.

Relative coordinates use the tilde (`~`) prefix and calculate an offset from the current execution position along the fixed world axes. Writing `~ ~1 ~` means zero offset on X, plus one block straight up on the world's Y-axis, and zero offset on Z. You can freely mix absolute and relative coordinates within a single triplet: `~5 64 ~-2` moves 5 blocks east and 2 blocks north from the current execution X and Z, while locking the vertical height strictly to Y = 64. Relative coordinates completely ignore which way the executing entity is looking.

Local coordinates use the caret (`^`) prefix and calculate an offset relative to both the execution position and the execution rotation (yaw and pitch). A local triplet is written as `^left ^up ^forward`. The first value moves to the entity's left (negative values move right), the second value moves upward relative to the entity's head tilt (not the world's vertical axis), and the third value moves directly forward along the entity's line of sight. Unlike absolute and relative values, local coordinates cannot be mixed with other types in the same three-number coordinate set; if one value uses a caret, all three must use carets.

Every command runs inside an execution context consisting of three distinct properties: the executor (who is running it, referenced by `@s`), the execution position (where `~ ~ ~` and `^ ^ ^` start from), and the execution rotation (which direction `^ ^ ^` points). When a behavior pack animation controller or entity event runs a command, the executor, position, and rotation all default to that specific entity. However, when you chain subcommands inside `/execute`, these properties are decoupled and must be managed deliberately.

The biggest pitfall in modern Bedrock command syntax is assuming that `execute as @e[...]` moves the execution position to the target entity. It does not. `as` only changes the executor (`@s`), leaving the position and rotation back at the previous origin (such as a command block or the player who triggered the function). To move the coordinate origin to the entity, you must include `at @s`. When `as` and `at` are combined, `~ ~ ~` anchors to the entity's feet (the bottom center of its collision box), and `^ ^ ^` aligns with the entity's current head rotation.

If you need to cast a ray or spawn an effect from an entity's eyes rather than its feet, use the `anchored eyes` subcommand. This shifts the local coordinate origin (`^ ^ ^`) upward to the entity's eye level, which is defined by the entity's collision box height. Keep in mind that `anchored eyes` only offsets local caret coordinates (`^ ^ ^`); relative tilde coordinates (`~ ~ ~`) remain anchored at the entity's feet unless you manually shift the context using `positioned ^ ^ ^`.

# Shift execution to the caster, anchor to their eyes, and step forward along their line of sight
execute as @s at @s anchored eyes run particle minecraft:snowflake_particle ^ ^ ^1.5
execute as @s at @s anchored eyes run particle minecraft:snowflake_particle ^ ^ ^3.0
execute as @s at @s anchored eyes run particle minecraft:snowflake_particle ^ ^ ^4.5

# Move the actual execution position 4.5 blocks forward from the eyes, then damage nearby targets
execute as @s at @s anchored eyes positioned ^ ^ ^4.5 run damage @e[rm=0.1,r=2.0,type=!item] 6 freezing entity @s

# Place a temporary light block at the impact point using world-relative offsets from the new position
execute as @s at @s anchored eyes positioned ^ ^ ^4.5 run fill ~ ~ ~ ~ ~ ~ minecraft:light_block ["block_light_level"=10] replace air

In addition to spatial X, Y, and Z positions, commands like `/tp` and `/execute rotated` use a two-value rotation coordinate system: `yaw pitch` (often denoted in syntax documentation as `yRot xRot`). Yaw controls horizontal rotation around the Y-axis and ranges from `-180.0` to `180.0`. A yaw of `0.0` faces due south (+Z), `-90.0` faces due east (+X), `90.0` faces due west (-X), and `180.0` (or `-180.0`) faces due north (-Z). Pitch controls vertical tilt and ranges from `-90.0` to `90.0`, where `0.0` is looking flat at the horizon, `-90.0` is looking straight up (+Y), and `90.0` is looking straight down (-Y).

Just like spatial coordinates, rotation coordinates support relative tilde notation (`~`). Running `tp @s ~ ~ ~ ~45 ~` teleports the entity to its current location while rotating its yaw 45 degrees clockwise (to the right) and leaving its pitch unchanged. This is frequently used inside repeating functions to make custom non-mob entities spin smoothly in place.

When you want to aim a local coordinate vector without doing manual trigonometry, you can overwrite the execution rotation using `facing` or `rotated`. The subcommand `facing <x y z>` or `facing entity <target> <eyes|feet>` recalculates the context's yaw and pitch so that `^ ^ ^1` points directly toward that target point. Conversely, if an entity is looking steeply up or down and you want `^ ^ ^1` to move horizontally across the ground without flying into the air or digging into the dirt, insert `rotated ~ 0` into your execute chain. This preserves the entity's horizontal yaw (`~`) while flattening the execution pitch to `0`.

{
  "format_version": "1.10.0",
  "animation_controllers": {
    "controller.animation.custom_dash": {
      "initial_state": "idle",
      "states": {
        "idle": {
          "transitions": [
            {
              "dashing": "query.is_sneaking && query.is_sprinting"
            }
          ]
        },
        "dashing": {
          "on_entry": [
            "/execute as @s at @s rotated ~ 0 if block ^ ^ ^1 air if block ^ ^1 ^1 air run tp @s ^ ^ ^1",
            "/execute as @s at @s rotated ~ 0 if block ^ ^ ^1 air if block ^ ^1 ^1 air run tp @s ^ ^ ^1",
            "/execute as @s at @s rotated ~ 0 if block ^ ^ ^1 air if block ^ ^1 ^1 air run tp @s ^ ^ ^1",
            "/playsound mob.irongolem.throw @a[r=10] ~ ~ ~ 1.0 1.2"
          ],
          "transitions": [
            {
              "idle": "1.0"
            }
          ]
        }
      }
    }
  }
}

Target selectors (`@a`, `@e`, `@p`, `@r`) allow you to filter entities by their spatial coordinates. You can override the selector's starting search position using the `x`, `y`, and `z` arguments, which also accept tilde notation (for example, `@e[x=~,y=64,z=~]`). From that starting point, you have two ways to define the search volume: spherical radius (`r` and `rm`) or a rectangular delta bounding box (`dx`, `dy`, and `dz`).

Spherical radius arguments (`r` for maximum radius, `rm` for minimum radius) measure the exact Euclidean distance from the selector's origin point to the target entity's feet. If an entity's collision box overlaps the sphere, it is still ignored unless its actual coordinate origin (bottom center of its bounding box) falls inside the radius. Because `r` checks exact floating-point distance, it is unaffected by block grid alignment.

Delta arguments (`dx`, `dy`, `dz`) work very differently and are a frequent source of bugs. First, when you use `dx`, `dy`, or `dz`, the game floors the starting `x`, `y`, and `z` coordinates to integers, snapping the starting corner to the block grid. Second, a value of `0` still encompasses a full `1x1x1` block volume; therefore, `dx=5,dy=2,dz=5` actually checks a region that is 6 blocks wide on X, 3 blocks tall on Y, and 6 blocks long on Z. Third, unlike radius selectors, delta volume selectors check for any intersection with an entity's collision hitbox, not just its feet position. Finally, you can pass negative values to `dx`, `dy`, and `dz` to extend the detection box toward negative world axes (west, down, or north).

When your add-on outgrows pure `.mcfunction` files and transitions into the `@minecraft/server` Script API, coordinate concepts remain identical, though the representation shifts to JavaScript objects. Positions are represented as `Vector3` objects with `{ x, y, z }` floating-point properties, and rotations are represented as `Vector2` objects with `{ x, y }` where `x` is pitch and `y` is yaw. Notice that in Script API rotation objects, pitch (`x`) and yaw (`y`) are named after the axis they rotate around, which is the reverse of the `yaw pitch` order used in slash commands.

If you call `dimension.runCommand()` from script, the execution origin defaults to `0, 0, 0` in that dimension unless you specify coordinates inside the command string. When calling `entity.runCommand()`, the execution context automatically sets `as @s at @s` for that entity. However, for performance reasons, you should avoid building command strings with template literals just to calculate local offsets; instead, use `entity.getViewDirection()` and `entity.getHeadLocation()` directly in JavaScript.

import { world, system } from "@minecraft/server";

// Equivalent to: execute as @s at @s anchored eyes positioned ^ ^ ^4 run ...
export function getLocalEyeOffset(entity, forwardDistance) {
  const headLoc = entity.getHeadLocation();
  const viewDir = entity.getViewDirection();

  return {
    x: headLoc.x + viewDir.x * forwardDistance,
    y: headLoc.y + viewDir.y * forwardDistance,
    z: headLoc.z + viewDir.z * forwardDistance
  };
}

system.runInterval(() => {
  for (const player of world.getAllPlayers()) {
    if (player.isSneaking) {
      const targetPos = getLocalEyeOffset(player, 4.0);
      player.dimension.spawnParticle("minecraft:villager_happy", targetPos);
    }
  }
}, 5);

Applies to Minecraft Bedrock 1.19.50 and higher (which introduced the modern execute syntax). No experimental toggles are required for commands, functions, or the stable @minecraft/server spatial methods shown here.

Read out of the game itself, so the ids match the version you are building for.