Units and axes

Units

Of	Unit
length	metres
time	seconds
angles	radians
mass	kilograms
speed	metres a second

A player stands about 1.8 m tall and runs at about 4.8 m/s. math.rad(90) turns degrees into radians.

Axes

• +Y is up.
• A model faces +Z.
• The axes are right-handed: facing +Z with +Y up, +X is to your left.

Angles

An angle is a table, {yaw, pitch, roll}, each optional, in radians.

• Yaw turns about +Y. At 0 a player faces +Z, and a positive yaw turns them left.
• Pitch is positive looking up.
• Roll tips something to its right.

The angles library works on them, and takes anything with angles too: a marker, a player, a model or a part.

on("joined", function(e)
  local p = e.player
  local ahead = p.position + angles.forward(p) * 2 -- 2 m in front of them
  model("grenade", { at = ahead, angles = { yaw = p.yaw } })
end)

angles.forward, angles.right and angles.up give the directions an angle faces. angles.of(dir) gives the yaw and pitch of a direction. angles.delta(a, b) gives the shortest turn between two angles, from -π to π.

Points

A point or a direction is a Luau vector: vector.create(x, y, z). Wherever the engine takes one, {x, y, z} works too. vector.distance(a, b) gives the metres between two points.