Std Lua Libraries
Cart scripts can call these standard Lua functions, alongside the PIXELFALLS API.
The engine opens the base, math, string, and table libraries. It also opens package internally. Do not use require() to load another project file. Project files are bundled into the cart, and node scripts are exposed as globals. See Nodes.
io, os, debug, coroutine, and utf8 are not available. Breakpoints and stepping in the IDE do not add the Lua debug library to a cart.
print and printError are PIXELFALLS functions. See Debug. Trig functions such as math.sin and math.cos take angles in radians.
assert
Raises an error when v is false or nil. Otherwise returns v.
- assert(v [, message]) -> any
Parameters
- v — Value to test.
- [message] — Optional error message when v is false or nil.
Returns
- any
Examples
-- Stop with an error when score is missing.
assert(score, "score is missing")error
Raises an error with the given message.
- error(message [, level]) -> nil
Parameters
- message — Error message.
- [level] — Optional stack level. Defaults to 1.
Returns
- nil
Examples
-- Stop and show this message.
error("level failed to load")ipairs
Returns an iterator for array-like tables with integer keys 1..n.
- ipairs(t) -> iterator
Parameters
- t — Array-like table (indexes 1, 2, …).
Returns
- iterator
Examples
-- Visit array items 1, 2, then 3.
for index, item in ipairs({ "a", "b", "c" }) do
print(index, item)
endpairs
Returns an iterator for all key–value pairs in a table.
- pairs(t) -> iterator
Parameters
- t — Table to loop over.
Returns
- iterator
Examples
-- Visit every key and value in the table.
for key, value in pairs({ x = 1, y = 2 }) do
print(key, value)
endpcall
Calls f in protected mode. Returns a status plus any values f returns.
- pcall(f, ...) -> (status, ...)
Parameters
- f — Function to call safely.
- ... — Arguments passed to f.
Returns
- (status, ...)
Examples
-- Call risky() and keep going if it errors. ok is false when it failed.
local ok, result = pcall(risky)tonumber
Converts its argument to a number. When base is given, e is parsed as an integer in that base.
- tonumber(e [, base]) -> number|nil
Parameters
- e — Value to turn into a number.
- [base] — Optional base for integer parsing.
Returns
- number|nil
Examples
-- Turn the text "12" into the number 12.
local n = tonumber("12")
-- Read FF as a hexadecimal number.
local hex = tonumber("FF", 16)tostring
Converts a value of any type to a string.
- tostring(v) -> string
Parameters
- v — Value to turn into a string.
Returns
- string
Examples
-- Turn the number 12 into the text "12".
local text = tostring(12)type
Returns the type of the given value as a string.
- type(v) -> string
Parameters
- v — Value to inspect.
Returns
- string
Examples
-- "number", "string", "table", or another type name.
local kind = type(12)math.abs
Returns the absolute value of x.
- math.abs(x) -> number
Parameters
- x — Number.
Returns
- number
Examples
-- Turn -3 into 3.
local n = math.abs(-3)math.acos
Returns the arc cosine of x, in radians.
- math.acos(x) -> number
Parameters
- x — Number in the range -1 to 1.
Returns
- number
Examples
-- Arc cosine of 1, in radians. The result is 0.
local angle = math.acos(1)math.asin
Returns the arc sine of x, in radians.
- math.asin(x) -> number
Parameters
- x — Number in the range -1 to 1.
Returns
- number
Examples
-- Arc sine of 0, in radians. The result is 0.
local angle = math.asin(0)math.atan
Returns the arc tangent of y/x, in radians.
- math.atan(y [, x]) -> number
Parameters
- y — Number.
- [x] — Optional second value. When given, the signs of y and x choose the quadrant.
Returns
- number
Examples
-- The angle of the line from (0, 0) to (1, 1), in radians.
local angle = math.atan(1, 1)math.ceil
Returns the smallest integer greater than or equal to x.
- math.ceil(x) -> number
Parameters
- x — Number.
Returns
- number
Examples
-- Round 1.2 up to 2.
local n = math.ceil(1.2)math.cos
Returns the cosine of x.
- math.cos(x) -> number
Parameters
- x — Angle in radians.
Returns
- number
Examples
-- Cosine of 0 radians. The result is 1.
local n = math.cos(0)math.deg
Converts an angle from radians to degrees.
- math.deg(x) -> number
Parameters
- x — Angle in radians.
Returns
- number
Examples
-- Turn pi radians into 180 degrees.
local degrees = math.deg(math.pi)math.exp
Returns e raised to the power of x.
- math.exp(x) -> number
Parameters
- x — Exponent.
Returns
- number
Examples
-- e to the power of 1.
local n = math.exp(1)math.floor
Returns the largest integer less than or equal to x.
- math.floor(x) -> number
Parameters
- x — Number.
Returns
- number
Examples
-- Round 1.8 down to 1.
local n = math.floor(1.8)math.fmod
Returns the remainder of x divided by y, rounded toward zero.
- math.fmod(x, y) -> number
Parameters
- x — Dividend.
- y — Divisor.
Returns
- number
Examples
-- The remainder of 7 divided by 3. The result is 1.
local n = math.fmod(7, 3)math.huge
A value greater than or equal to any other number.
- math.huge -> number
Returns
- number
Examples
-- A number larger than any ordinary number.
local big = math.hugemath.log
Returns the logarithm of x.
- math.log(x [, base]) -> number
Parameters
- x — Number greater than 0.
- [base] — Optional logarithm base. Defaults to e.
Returns
- number
Examples
-- Natural logarithm of e. The result is 1.
local n = math.log(math.exp(1))math.max
Returns the largest of its arguments.
- math.max(x, ...) -> number
Parameters
- x — First number.
- ... — More numbers. The largest is returned.
Returns
- number
Examples
-- The larger of 3 and 8.
local n = math.max(3, 8)math.maxinteger
The maximum value for an integer.
- math.maxinteger -> integer
Returns
- integer
Examples
-- The biggest whole number Lua can store.
local n = math.maxintegermath.min
Returns the smallest of its arguments.
- math.min(x, ...) -> number
Parameters
- x — First number.
- ... — More numbers. The smallest is returned.
Returns
- number
Examples
-- The smaller of 3 and 8.
local n = math.min(3, 8)math.mininteger
The minimum value for an integer.
- math.mininteger -> integer
Returns
- integer
Examples
-- The smallest whole number Lua can store.
local n = math.minintegermath.modf
Returns the integral part of x and the fractional part of x.
- math.modf(x) -> (integer, fraction)
Parameters
- x — Number.
Returns
- (integer, fraction)
Examples
-- Split 3.25 into the whole part 3 and the fraction 0.25.
local whole, fraction = math.modf(3.25)math.pi
The value of pi.
- math.pi -> number
Returns
- number
Examples
-- Pi. A full circle is 2 * pi radians.
local fullCircle = math.pi * 2math.rad
Converts an angle from degrees to radians.
- math.rad(x) -> number
Parameters
- x — Angle in degrees.
Returns
- number
Examples
-- Turn 180 degrees into pi radians.
local radians = math.rad(180)math.random
With no arguments, returns a number in the range 0 up to but not including 1. With integers, returns an integer in the requested range.
- math.random([m [, n]]) -> number
Parameters
- [m] — Optional lower bound, or the upper bound when it is the only argument.
- [n] — Optional upper bound when two integers are passed.
Returns
- number
Examples
-- A decimal from 0 up to, but not including, 1.
local decimal = math.random()
-- A whole number from 1 to 6, like a die.
local roll = math.random(1, 6)math.randomseed
Sets the seed used by math.random.
- math.randomseed([x [, y]]) -> nil
Parameters
- [x] — Optional first seed integer.
- [y] — Optional second seed integer.
Returns
- nil
Examples
-- Start the random sequence at a chosen point.
math.randomseed(123)math.sin
Returns the sine of x.
- math.sin(x) -> number
Parameters
- x — Angle in radians.
Returns
- number
Examples
-- Sine of 0 radians. The result is 0.
local n = math.sin(0)math.sqrt
Returns the square root of x.
- math.sqrt(x) -> number
Parameters
- x — Number greater than or equal to 0.
Returns
- number
Examples
-- Square root of 9. The result is 3.
local n = math.sqrt(9)math.tan
Returns the tangent of x.
- math.tan(x) -> number
Parameters
- x — Angle in radians.
Returns
- number
Examples
-- Tangent of 0 radians. The result is 0.
local n = math.tan(0)math.tointeger
Returns x as an integer when x has an integer value. Otherwise returns nil.
- math.tointeger(x) -> integer|nil
Parameters
- x — Value to convert.
Returns
- integer|nil
Examples
-- 3.0 becomes the integer 3. 3.2 becomes nil.
local n = math.tointeger(3.0)math.type
Returns "integer" or "float" when x is a number. Otherwise returns nil.
- math.type(x) -> string|nil
Parameters
- x — Value to test.
Returns
- string|nil
Examples
-- "integer" or "float" when the value is a number.
local kind = math.type(3)math.ult
Returns true when m is less than n, comparing both as unsigned integers.
- math.ult(m, n) -> boolean
Parameters
- m — Integer.
- n — Integer.
Returns
- boolean
Examples
-- True when 1 is less than 2, compared as unsigned integers.
local smaller = math.ult(1, 2)string.byte
Returns the numeric codes of the characters in s from i to j.
- string.byte(s [, i [, j]]) -> number
Parameters
- s — String.
- [i] — First character position (1-based). Defaults to 1.
- [j] — Last character position. Defaults to i.
Returns
- number
Examples
-- The character code of "A".
local code = string.byte("A")string.char
Returns a string built from the given character codes.
- string.char(...) -> string
Parameters
- ... — Zero or more character codes.
Returns
- string
Examples
-- The letter A from character code 65.
local letter = string.char(65)string.find
Looks for the first match of pattern in s.
- string.find(s, pattern [, init [, plain]]) -> (i, j)
Parameters
- s — String to search.
- pattern — Pattern to find.
- [init] — Where to start searching.
- [plain] — If true, pattern is plain text, not a pattern.
Returns
- (i, j)
Examples
-- Where "cat" starts and ends inside the text.
local startAt, endAt = string.find("the cat sat", "cat")string.format
Returns a formatted string.
- string.format(formatstring, ...) -> string
Parameters
- formatstring — Format string, similar to C sprintf.
- ... — Values to format.
Returns
- string
Examples
-- Build the text "Score: 10".
local text = string.format("Score: %d", 10)string.gmatch
Returns an iterator that yields each match of pattern in s.
- string.gmatch(s, pattern) -> iterator
Parameters
- s — String to search.
- pattern — Pattern to match.
Returns
- iterator
Examples
-- Visit each word in the text.
for word in string.gmatch("red blue", "%a+") do
print(word)
endstring.gsub
Replaces occurrences of pattern in s with repl.
- string.gsub(s, pattern, repl [, n]) -> (s, n)
Parameters
- s — String.
- pattern — Pattern to replace.
- repl — Replacement text, table, or function.
- [n] — Maximum number of replacements.
Returns
- (s, n)
Examples
-- Replace every "cat" with "dog".
local text, count = string.gsub("cat cat", "cat", "dog")string.len
Returns the length of s.
- string.len(s) -> number
Parameters
- s — String.
Returns
- number
Examples
-- The number of characters in "Hi". The result is 2.
local length = string.len("Hi")string.lower
Returns s with all letters in lower case.
- string.lower(s) -> string
Parameters
- s — String.
Returns
- string
Examples
-- Turn "Hi" into "hi".
local text = string.lower("Hi")string.match
Looks for the first match of pattern in s.
- string.match(s, pattern [, init]) -> string
Parameters
- s — String to search.
- pattern — Pattern to match.
- [init] — Where to start searching.
Returns
- string
Examples
-- The first number found in the text.
local amount = string.match("score 10", "%d+")string.rep
Returns a string of n copies of s.
- string.rep(s, n [, sep]) -> string
Parameters
- s — String to repeat.
- n — Number of copies.
- [sep] — Optional separator placed between copies.
Returns
- string
Examples
-- "Ha" copied 3 times. The result is "HaHaHa".
local text = string.rep("Ha", 3)string.reverse
Returns s with its characters in reverse order.
- string.reverse(s) -> string
Parameters
- s — String.
Returns
- string
Examples
-- Turn "Hi" into "iH".
local text = string.reverse("Hi")string.sub
Returns the substring of s from i to j.
- string.sub(s, i [, j]) -> string
Parameters
- s — String.
- i — Start position (1-based).
- [j] — End position. Omit to continue to the end of the string.
Returns
- string
Examples
-- Characters 2 through 4 of "Hello". The result is "ell".
local text = string.sub("Hello", 2, 4)string.upper
Returns s with all letters in upper case.
- string.upper(s) -> string
Parameters
- s — String.
Returns
- string
Examples
-- Turn "Hi" into "HI".
local text = string.upper("Hi")table.concat
Joins the elements of a list into a string.
- table.concat(list [, sep [, i [, j]]]) -> string
Parameters
- list — Array of strings or numbers to join.
- [sep] — Optional separator.
- [i] — Optional first index.
- [j] — Optional last index.
Returns
- string
Examples
-- Join three words with spaces. The result is "red blue green".
local text = table.concat({ "red", "blue", "green" }, " ")table.insert
Inserts value at position pos in list.
- table.insert(list, [pos], value) -> nil
Parameters
- list — Table, usually an array.
- [pos] — Optional position to insert at.
- value — Value to insert.
Returns
- nil
Examples
-- Add "c" at the end of the list.
local letters = { "a", "b" }
table.insert(letters, "c")table.move
Copies elements from index f through e, starting at index t.
- table.move(a1, f, e, t [, a2]) -> table
Parameters
- a1 — Source table.
- f — First index to copy.
- e — Last index to copy.
- t — Destination index.
- [a2] — Optional destination table. Defaults to a1.
Returns
- table
Examples
-- Copy items 1 through 2 of source into dest, starting at index 1.
local source = { "a", "b", "c" }
local dest = {}
table.move(source, 1, 2, 1, dest)table.pack
Returns a new table with the arguments stored in order, and field n set to the count.
- table.pack(...) -> table
Parameters
- ... — Values to store.
Returns
- table
Examples
-- Store 10 and 20 in a new table. The field n is 2.
local packed = table.pack(10, 20)table.remove
Removes the element at position pos and returns it.
- table.remove(list [, pos]) -> any
Parameters
- list — Table, usually an array.
- [pos] — Optional index to remove. Omit to remove the last element.
Returns
- any
Examples
-- Remove the last item and return it.
local letters = { "a", "b", "c" }
local last = table.remove(letters)table.sort
Sorts list in place.
- table.sort(list [, comp]) -> nil
Parameters
- list — Array to sort in place.
- [comp] — Optional comparison function. When omitted, sorts in ascending order.
Returns
- nil
Examples
-- Sort the list into 1, 3, 5.
local numbers = { 3, 1, 5 }
table.sort(numbers)table.unpack
Returns the elements of list from index i to j.
- table.unpack(list [, i [, j]]) -> ...
Parameters
- list — Array to unpack.
- [i] — Optional first index. Defaults to 1.
- [j] — Optional last index. Defaults to the length of the list.
Returns
- ...
Examples
-- Return the items as separate values: 1, then 2, then 3.
local a, b, c = table.unpack({ 1, 2, 3 })