math

Rounds down, towards minus infinity.

print(math.floor(2.9))
print(math.floor(-2.1))
print(7 // 2)

2
-3
3

Use it to cut a value into whole parts, for example a count of items into stacks, or a pixel coordinate into a character cell:

local px = 137
local column = math.floor((px - 1) / 6) + 1  -- characters are 6 pixels wide
print("pixel " .. px .. " is in column " .. column)

pixel 137 is in column 23

See also math.ceil() math.round()

Rounds up, towards plus infinity.

math.ceil is the right tool when you need "enough" of something: crates to hold items, trips of a train, lines to show a list.

local items = 200
print(math.ceil(items / 64) .. " chest slots needed")
print(math.ceil(-2.9))

4 chest slots needed
-2

See also math.floor() math.round()

Rounds to the nearest whole number. Halves go up: 2.5 gives 3 and -2.5 gives -2.

math.round is a Brass extension (Lua has none). It is the same as math.floor(x + 0.5). To keep one decimal, scale the number first:

local speed = 12.3456
print(math.round(speed))
print(math.round(speed * 10) / 10)
print(math.round(-2.5))

12
12.3
-2

See also math.floor() math.ceil()

The absolute value: the distance between x and zero.

Handy to compare two values without caring which one is larger, for example to tell whether a contraption is close enough to its target:

local target, position = 64, 61.5
if math.abs(target - position) < 3 then
  print("close enough")
end
print(math.abs(-7))

close enough
7

The smallest of the numbers given. At least one number is required.

print(math.min(4, 2, 8))
local fuel = 30
print("burn " .. math.min(fuel, 16) .. " this round")

2
burn 16 this round

Together with math.max, it clamps a value between two limits, which you will need all the time with redstone (0 to 15) and with Create speeds (-256 to 256 RPM):

local function clamp(x, low, high)
  return math.max(low, math.min(high, x))
end
print(clamp(22, 0, 15))
print(clamp(-4, 0, 15))
print(clamp(9, 0, 15))

15
0
9

See also math.max()

The largest of the numbers given. At least one number is required.

local readings = {12, 40, 7, 33}
local best = readings[1]
for i = 2, #readings do
  best = math.max(best, readings[i])
end
print("peak: " .. best)

peak: 40

See also math.min()

Infinity: larger than every other number. -math.huge is smaller than every number.

It is the usual starting value when you look for the smallest of a list: the first value you compare is always smaller.

local distances = {48.2, 12.9, 30}
local nearest = math.huge
for _, d in ipairs(distances) do
  if d < nearest then nearest = d end
end
print(nearest)
print(math.huge, -math.huge)

12.9
inf -inf

The square root. The square root of a negative number is not a number: it prints as nan.

Its everyday use is the distance between two points, with Pythagoras:

local function distance(x1, z1, x2, z2)
  local dx, dz = x2 - x1, z2 - z1
  return math.sqrt(dx * dx + dz * dz)
end
print(math.sqrt(16))
print(distance(0, 0, 30, 40))

4
50

Raising to a power needs no function: 2 ^ 10 is 1024, and x ^ 0.5 is another way to write the square root.

e to the power x. Useful for smooth curves, like a value that decays a little every tick.

print(math.exp(0))
print(math.exp(1))

1
2.718281828459

See also math.log()

The logarithm of x: the power the base must be raised to in order to give x. Without a base, the natural logarithm.

print(math.log(100, 10))
print(math.log(1024, 2))
print(math.log(math.exp(3)))

2
10
3

A logarithm counts digits or doublings: math.floor(math.log(n, 10)) + 1 is the number of digits of a whole number n above zero, handy to align columns of numbers on a screen.

See also math.exp()

The number π, half a turn in radians.

local r = 5
print(math.pi)
print("area: " .. math.pi * r * r)

3.1415926535898
area: 78.539816339745

The sine of an angle in radians.

With math.cos, it places a point on a circle: the base of every round gauge, radar sweep or orbiting sprite drawn with gfx.

local cx, cy, radius = 100, 60, 40
for step = 0, 3 do
  local angle = step * math.pi / 2
  local x = cx + math.round(radius * math.cos(angle))
  local y = cy + math.round(radius * math.sin(angle))
  print(step, x, y)
end

0   140 60
1   100 100
2   60  60
3   100 20

On a screen, the same two lines draw a ring of dots. A screen picture like this one is made by running the code:

gfx.clear("black")
local cx, cy = 153, 90
for degrees = 0, 359, 10 do
  local a = degrees * math.pi / 180
  gfx.pixel(cx + math.round(70 * math.cos(a)), cy + math.round(70 * math.sin(a)), "lime", 3)
end
gfx.line(cx, cy, cx + 70, cy, "yellow", 2)
gfx.text(4, 4, "36 POINTS ON A CIRCLE", "white")

Screen

See also math.cos() math.pi

The cosine of an angle in radians.

print(math.cos(0))
print(math.cos(math.pi))

1
-1

A needle gauge: the needle of a speedometer sweeps half a circle, from the left (0 RPM) to the right (256 RPM). Since a function returns a single value in Brass, the tip of the needle comes back as a table:

local function needle(rpm)
  local angle = math.pi - (rpm / 256) * math.pi
  return {x = math.round(math.cos(angle) * 20), y = math.round(-math.sin(angle) * 20)}
end
local tip = needle(128)
print(tip.x, tip.y)

0   -20

See also math.sin() math.pi

The tangent of an angle in radians: the slope of a line at that angle.

print(math.round(math.tan(math.pi / 4)))

1

The arc tangent: the angle whose tangent is y / x. With two arguments it does exactly the same as math.atan2.

print(math.atan(1) * 180 / math.pi)

45

See also math.atan2()

The angle of the direction from the origin to the point (x, y), in radians. Unlike math.atan(y / x), it knows which quarter the point is in, and does not fail when x is zero.

This is the function for "which way do I turn?": the direction from a vehicle to its target.

local function heading(fromX, fromZ, toX, toZ)
  local radians = math.atan2(toZ - fromZ, toX - fromX)
  return math.round(radians * 180 / math.pi)
end
print(heading(0, 0, 10, 0))
print(heading(0, 0, 0, 10))
print(heading(0, 0, -10, 0))

0
90
180

See also math.atan()

The remainder of the division of a by b, which keeps the sign of a. The % operator differs for negative numbers: its result has the sign of b.

print(math.fmod(7, 3), 7 % 3)
print(math.fmod(-7, 3), -7 % 3)

1   1
-1  2

For positions that wrap around (a pattern that repeats, a ring of 16 lamps), % is usually what you want, because it never goes below zero.

A random number. Three forms:

Decimal bounds are rounded down. When the lower bound is above the upper one, the program stops with the error bad argument to 'random' (interval is empty).

print(math.random(1, 6))   -- a die: 1, 2, 3, 4, 5 or 6
print(math.random(10))     -- 1 to 10
print(math.random())       -- for example 0.71828...

Pick a random element of a list:

local songs = {"cat", "blocks", "chirp", "far", "mall"}
local pick = songs[math.random(#songs)]
print("now playing: " .. pick)

A chance in percent, for an event that should happen one time out of five:

if math.random() < 0.2 then
  print("a creeper appears!")
end

See also math.randomseed()

Restarts the random sequence from seed: the same seed always gives the same numbers afterwards.

Use a fixed seed to make a "random" world or puzzle that is the same every time, or the time to get a new sequence on each run:

math.randomseed(42)
local a = math.random(1000)
math.randomseed(42)
local b = math.random(1000)
print(a == b)

true

math.randomseed(os.time() + os.id() * 1000)  -- different on each computer and each run

#Common patterns

Map a reading to another scale. A redstone signal (0 to 15) to a speed (0 to 256 RPM), or a stock (0 to the capacity) to the width of a bar on the screen:

local function map(value, inLow, inHigh, outLow, outHigh)
  local t = (value - inLow) / (inHigh - inLow)
  return outLow + t * (outHigh - outLow)
end
print(map(15, 0, 15, 0, 256))
print(math.floor(map(750, 0, 2000, 0, 40)))

256
15

Smooth a jumpy reading. Sensors move every tick; a running average hides the noise. Each new reading counts for 20 % of the result:

local smooth = 0
for _, reading in ipairs({10, 12, 30, 11, 10}) do
  smooth = smooth + (reading - smooth) * 0.2
end
print(math.round(smooth * 10) / 10)

9.6

See also math.random()