sdk.math

Tile-grid position helpers. Chebyshev is the default distance (Tibia walk/attack range). Direction numbers match Canary/TFS: N=0 E=1 S=2 W=3 SW=4 SE=5 NW=6 NE=7 None=8. Spec: docs/superpowers/specs/2026-08-21-sdk-position-design.md

local M = require("sdk.math")

position

function · position(x, y, z)

Returns Pos.

Parameters

Name	Type	Summary
x	number	—
y	number	—
z	number	—

Returns

Type	Summary
Pos	—

equals

function · equals(a, b)

True when two positions have the same x,y,z.

same_floor

function · same_floor(a, b)

True when two positions share z.

offset_x

function · offset_x(a, b)

Signed x delta from a to b.

offset_y

function · offset_y(a, b)

Signed y delta from a to b.

offset_z

function · offset_z(a, b)

Signed z delta from a to b.

distance_x

function · distance_x(a, b)

Absolute x distance.

distance_y

function · distance_y(a, b)

Absolute y distance.

distance_z

function · distance_z(a, b)

Absolute floor distance.

chebyshev

function · chebyshev(a, b)

Same-floor walk/attack range: max(|dx|, |dy|). z is ignored here; use same_floor / in_range for floors.

Parameters

Name	Type	Summary
a	Pos	—
b	Pos	—

Returns

Type	Summary
number|nil	—

manhattan

function · manhattan(a, b)

Manhattan distance on the same floor; nil when z differs.

distance

alias · distance = chebyshev

Same as chebyshev.

Alias

Same as chebyshev.

in_range

function · in_range(a, b, tiles)

True when Chebyshev distance is at most tiles.

parse_direction

function · parse_direction(s)

Parse a direction name or alias to a dir id.

direction_offset

function · direction_offset(dir)

Tile step {dx,dy} for a direction.

translated

function · translated(p, a, b, c)

Copy a position offset by dx,dy,dz.

neighbors

function · neighbors(p)

Eight adjacent tiles (no floor change).

direction_name

function · direction_name(dir)

Canonical direction string for a dir id.

direction_away

function · direction_away(here, threat)

Compass from threat toward here (the opposite of direction_to).

Parameters

Name	Type	Summary
here	Pos	—
threat	Pos	—

Returns

Type	Summary
integer	—

direction_to

function · direction_to(a, b)

Returns integer.

Parameters

Name	Type	Summary
a	Pos	—
b	Pos	—

Returns

Type	Summary
integer	—

to_string

function · to_string(p)

Format a position as x,y,z.