Lua

Lua is a programming language designed primarily for embedded systems. It is popular in the video game industry as a language that can be embedded in a larger game engine.

PICO-8 implements a subset of Lua for writing game cartridges. Because it is a subset, not all features of Lua are supported. Most notably, PICO-8 does not include the Lua standard library, and instead provides a proprietary collection of global functions.

* Official Lua documentation
* Lua (Wikipedia)

# Features of PICO-8 Lua

The following are the major language features of Lua as implemented and extended by PICO-8.

## Comments

PICO-8 code comments are preceded by two hyphens (`--`) and go to the end of the line. They also support a multi-line syntax using double-brackets (`--[[ ... ]]`).

```
-- one-line comment
--[[ multi-line
comment ]]

```

You can quickly toggle between active and inactive multi-line comments by adding an extra hyphen. This allows for quickly switching on and off different portions of the code (for example, to help with debugging).

Be sure that the closing set of brackets has their own double-hyphen so that you aren't left with hanging brackets when using this trick.

```
--[[
code that i don't
want to be active
--]]

---[[
code that is
now active
--]]

```

## Values

PICO-8 supports these fundamental types of values:

* Numbers, in the range supported by signed 16.16 bit fixed point:
	+ Minimum value: hex `0x8000.0000`, decimal `-32768.0`, binary `0b1000000000000000.0000000000000000`
	+ Maximum value: hex `0x7fff.ffff`, decimal `32767.9999847412109375`, binary `0b0111111111111111.1111111111111111`
	+ Number literals can use decimal (`17.25`), hexadecimal (`0x11.4`), or binary (`0b10001.01`).
	+ Things to be aware of:
		- PICO-8 prints and converts numbers to decimal strings by rounding off to four decimal places. This has the side effect that the maximum number rounds up to `32768.0`, which is actually not a valid PICO-8 number. It also means that the tiniest negative fraction below 0 displays as the somewhat-unintuitive `-0`.
		- This range is narrow in comparison to modern platforms. Be aware of situations where you might overflow, e.g. calculating the distance between corners of the screen requires calculating 128\*128+128\*128, which will overflow and wrap to -32768.
* Booleans (`true` and `false`)
* Strings
	+ String literals can use single quotes (`'hello'`) or double quotes (`"hello"`), and the quote character can appear in the string escaped with a leading backslash (`"you said \"hello\", yes?"`).
* Nil (`nil`)
* Functions (see below)
* Coroutines (see below)
* Tables
	+ Sequences, indexed from 1: `x = {2, 3, 5, 7, 11}`; `x[1] == 2`
	+ Mappings: `x = {a=1, b=2, c=3}`; `x.a == x['a'] == 1`
	+ Unset indexes evaluate to `nil`: `x[0] == nil`

As in Lua, all composite and custom data types are based on tables.

## Arithmetic operators

PICO-8 supports these arithmetic operators:

* negation: `-a`
* addition: `a + b`
* subtraction: `a - b`
* multiplication: `a * b`
* division: `a / b`
* division + floor: `a \ b`
* modulo: `a % b`
* exponentiation: `a ^ b`

Arithmetic operators take numbers as arguments and return a number.

Note: The integer division operator is similar to `div` operators in other languages. It performs regular division and then floors the result to produce an integer. It is faster than evaluating the equivalent `flr(a / b)` expression.

## Bitwise operators

PICO-8 supports these bitwise operators:

* not: `~a`
* or: `a | b`
* and: `a & b`
* xor: `a ^^ b`. Lua synonym: `a ~ b`
* shift left: `a << b`
* arithmetic shift right: `a >> b`
* logical shift right: `a >>> b`
* rotate left: `a <<> b`
* rotate right: `a >>< b`

Bitwise operators take numbers as arguments and return a number.

Note: Arithmetic shifts maintain sign by filling empty bits with the top bit of the shifted value, while logical shifts fill empty bits with 0:

```
> v = -2
> print(tostr(v, true))   -- tostr(v, true) converts v to a hex string
0xfffe.0000
> print(v >> 1)
-1
> print(tostr(v >> 1, true))
0xffff.0000
> print(v >>> 1)
32767
> print(tostr(v >>> 1, true))
0x7fff.0000

```

## Memory operators

PICO-8 provides shorthand for accessing memory directly, offering three prefix operators that mirror the functionality of `peek()`, `peek2()`, and `peek4()`:

* peek: `@address`
* peek2: `%address`
* peek4: `$address`

Using these operators appears to be significantly faster than calling the corresponding `peek()` functions.

## Relational operators

PICO-8 supports these relational operators:

* less than: `a < b`
* greater than: `a > b`
* less than or equal to: `a <= b`
* greater than or equal to: `a >= b`
* equal: `a == b`
* not equal: `a ~= b`; PICO-8 synonym: `a != b`

Relational operators take numbers as arguments and return either `true` or `false`.

## Logical operators

PICO-8 supports the following logical operators:

* and: `a and b`
* or: `a or b`
* not: `not a`

In logical expressions, both `false` and `nil` are treated as false, and all other values are treated as true.

Logical expressions "short circuit," which is to say they stop evaluating expressions left to right as soon as the value of the expression is known. For example, "`is_alive() and can_shoot()"` will first call `is_alive()`, and will only call `can_shoot()` afterwards if `is_alive()` returns true.

**"Is there logical xor operator?"**

If your operands are *guaranteed* to be boolean values, i.e. *only* true or false, then the `~=` operator does what an xor operator does. If they are *not* guaranteed, then an ugly-but-functional alternative is `not b ~= not c`.

**"Is there a ternary operator?"**

A useful equivalent of the choice-making [wikipedia:?: `?:` "ternary operator"] from the C-family languages is `a and b or c`, which evaluates to `b` if `a` is true, or `c` if `a` is false. One important and useful aspect of a ternary operator is that it uses the short-circuiting feature of logical operators to avoid invoking unwanted side effects or costs. **There is one caveat:** if `b` is false or nil, the expression will fall through and choose `c`.

Much more detail and additional approaches can be found in the official Lua documentation. Among them is the suggestion to use a ternary *function*, and it is good to note here that a ternary function uses the same number of PICO-8 tokens per invocation as the logical-operator approach, while also removing the need for isolating complex expressions with parentheses, but with the downsides that short-circuiting is lost and performance is a bit poorer.

## String operators

PICO-8 supports the string concatenation operator: `a..b`

`a` must be a string. `b` can be a string or a number (which is coerced into a string).

No other type of value can be concatenated with a string. You can use the `tostr()` function to convert other value types to strings:

```
print("a > b: "..tostr(a > b))

```

You can determine the length of a string using the sequence length operator (#):

```
x = "hello there"
print(#x)            -- 11

```

See also `sub()`.

## Assignment operators

In Lua, *assignment* places a value in a variable or a table element, like so:

```
a = b
t.a = b

```

PICO-8 also has *assignment operators*, where an operation is done on the destination variable and the result is assigned back to it. Similar operators are found in languages like C/C++/Java/etc.

This is a list of PICO-8 assignment operators, and the expressions each operator is shorthand for:

```
a += b       -- a = a + b
a -= b       -- a = a - b
a \*= b       -- a = a \* b
a /= b       -- a = a / b
a \= b       -- a = a \ b
a %= b       -- a = a % b
a ^= b       -- a = a ^ b
a ..= b      -- a = a .. b
a |= b       -- a = a | b
a &= b       -- a = a & b
a ^^= b      -- a = a ^^ b or a = a ~ b
a <<= b      -- a = a << b
a >>= b      -- a = a >> b
a >>>= b     -- a = a >>> b
a <<>= b     -- a = a <<> b
a >><= b     -- a = a >>< b

```

It's worth noting that there is not a `~=` assignment operator to match the 0.2.5 addition of the `~` bitwise-xor operator. This is likely due to difficulties in having PICO-8's Lua regex-based pre-processor, which silently converts these assignment operators into vanilla lua assignments, successfully recognize the difference between the existing `~=` inequality operator and such an assignment operator.

## Operator priorities

In math and programming, an expression is evaluated using a certain *order of operations*. One operator will take *priority* over another based on its *precedence* value.

This is the full list of operators, ordered from first-evaluated to last-evaluated:

Note that *associativity* dictates which order operations are done when more than one in the same group appear in sequence. For instance, multiply and divide are in the same group, and it's possible to test their associativity by adding explicit parentheses to force the order of operations:

```
> ?4/2*8      -- this is what lua does implicitly
16
> ?4/(2*8)    -- let's try forcing the right operation first
0.25
> ?(4/2)*8    -- ok, that didn't match, so try the left
16

```

Forcing the left operator to happen first matches what happens when there are no parentheses, so this group of operators is left-to-right associative. Similarly, the opposite would be true for right-to-left associativity.

## Variables

PICO-8 supports global variables accessible to the entire program, and local variables accessible only within the function where they are declared. If a variable is not declared as local, then it is global.

```
-- a global variable
player\_pos = {20, 60}

function move\_player(newx, newy)
  player\_pos = {newx, newy}
end

function circumference(r)
  -- a local variable
  local pi = 3.14
  return 2 \* pi \* r
end

```

**Caution:** A mistyped variable name is often interpreted as a global variable with no value assigned, which evaluates to `nil`. Most uses of unexpectedly `nil` values result in a runtime error, but these are not always easy to find.

Note that, unlike vanilla Lua, there is no access to the hidden `_G` table containing all global values.

However, the table of all global values can still be accessed via the `_ENV` variable. Inside of PICO-8 this may be referenced by using `Ctrl`+`P` to switch to the "puny" font and entering its name in lowercase (uppercase and lowercase are swapped on PICO-8). Be warned: this is an undocumented feature; it is *not* guaranteed to survive until version 1.0, and what is found in `_ENV` is not guaranteed to be the same from one version of PICO-8 to the next.

## Functions

A function is a collection of statements that can be executed by calling it. The behavior of a function can be parameterized, and a function may return a value as a result.

```
function distance(x1, y1, x2, y2)
  return sqrt((x2 - x1)^2 + (y2 - y1)^2)
end

```

PICO-8 includes many built-in global functions, such as the `sqrt()` in this example. See APIReference.

If control reaches a `return` statement, then the function exits. If `return` includes a value, then the function call evaluates to that value. If control reaches the end of the function's statement block without seeing a `return` statement, then the function returns `nil`.

A function in Lua is a "first class" value, just like other values. A named function in the outermost block is equivalent to a global variable whose value is a function. A named function can also appear inside another function, which is equivalent to a local variable.

A function can omit the name if it is called right away or otherwise used as a value (an "anonymous function").

```
x = {2, 3, 5, 7, 11}
foreach(x, function(v) print(v^2) end)

```

Parentheses can be omitted when there is only one argument and it is a table or a literal string:

```
add\_particle{type=snow, x=rnd(128), y=0, c=7}
print"hello, winter!"

```

Lua functions are lexically scoped.

## Conditional statements

The Lua `if` statement takes a condition and a block of statements, and executes the statements only if the condition is true:

```
if score >= 1000 then
  print("you win!")
  score = 0
end

```

An `if` statement can include any number of `elseif` sections to test multiple conditions until one is found true, and an optional final `else` section to evaluate if none of the conditions were true. The general form is:

```
if cond1 then
  ...
elseif cond2 then
  ...
else
  ...
end

```

PICO-8 extends standard Lua with an abbreviated, single-line `if` statement, differentiated by having parentheses around the condition and no `then` or `end` keywords. You may use `else`, but it must be on the same line. There is no support for `elseif`. Some examples:

```
if (cond1) print("cond1")

if (cond2) print("cond2") else print("not cond2")

```

A common misconception is that you must compare a boolean variable to `true` or `false` in an `if` statement, but a condition *is* a boolean, so you can drop any boolean variable straight into an `if` statement:

```
-- these two blocks are functionally identical

if cond == true then
  print("cond")
elseif cond == false then
  print("not cond")
end

if cond then
  print("cond")
else
  print("not cond")
end

```

The only time you might need to compare a boolean variable to a value is when it may not be initialized yet. When variables are uninitialized, their value will be `nil`. When a `nil` value is used as a conditional expression, it is treated the same as `false`. Thus, if you have a boolean variable that may not be set yet, you should check for `nil` and initialize it before testing it as a boolean.

## while and repeat loops

The `while` statement executes a block of statements repeatedly as long as a given conditional expression is true:

```
x = 0
while x < 5 do
  print(x)
  x += 1
end

```

PICO-8 extends standard Lua with an abbreviated, single-line `while` statement, differentiated by having parentheses around the condition and no `do` or `end` keywords. Some examples:

```
-- same as the example above, but very terse
x=0 while(x<5) print(x) x+=1

-- stop and wait synchronously for any button to be pressed
while(btn() == 0) flip()

```

The `repeat` statement executes a block of statements repeatedly until a given conditional expression is true:

```
x = 0
repeat
  print(x)
  x += 1
until x > 4

```

`while` does not execute its block if the condition is already false. `repeat` always executes its block at least once, then tests the condition.

The `break` statement anywhere in a loop terminates the loop immediately without testing the condition. If the loop is nested inside another loop, only the innermost loop is terminated.

## for loops

There are two kinds of for loops in Lua. The numeric for loop traverses a numeric sequence from start to end, using an optional "stride" (with a default stride of 1).

```
-- draws 16 color bars
for c=0,15 do
  rectfill(c\*8, 0, c\*8+7, 127, c)
end

-- prints 1, 3, 5, 7, 9
for i=1,10,2 do
  print(i)
end

```

The other kind of for loop is the "generic for." In PICO-8, this is most commonly used with the `all()` and `pairs()` built-ins for traversing tables:

```
tbl = {2, 3, 5, 7, 11}
for v in all(tbl) do
  print(v)
end

tbl = {a=1, b=2, c=3}
for k,v in pairs(tbl) do
  print(k.."="..v)
end

```

The generic for statement expects the "in" expression to return a special kind of value called an *iterator*. The built-ins `all()` and `pairs()` return iterators. For information on how to create your own iterators, see Iterators and the Generic for in the Lua manual.

As with `while` and `repeat`, you can use the `break` statement to terminate a for loop immediately.

## Tables

Tables are the primary composite data structure in Lua. They are used as containers, especially sequences (like lists or arrays) and mappings (also known as dictionaries or hashtables). Tables can be used as general purpose objects, and when combined with metatables (see below) can implement object-oriented concepts such as inheritance.

See Tables for a complete introduction to using tables in PICO-8.

## Methods

A method is a function that is stored as a value in a table. Lua has special syntax for defining and calling methods that cause the table itself to be passed to the method as a parameter named `self`.

```
ball = {
  xpos = 60,
  ypos = 60
}

function ball:move(newx, newy)
  self.xpos = newx
  self.ypos = newy
end

print(ball.xpos)           -- 60

ball:move(100, 120)
print(ball.xpos)           -- 100

```

In both the definition and the method call, using the colon (`:`) instead of the dot (`.`) implies the `self` behavior. If you define the method as a simple property of the table, you must remember to explicitly mention the `self` argument. This is equivalent:

```
ball = {
  xpos = 60,
  ypos = 60,

  -- without the colon syntax, must mention self argument explicitly
  move = function(self, newx, newy)
    self.xpos = newx
    self.ypos = newy
  end
}

-- using the colon, ball is passed as self automatically
ball:move(100, 120)

-- using the dot, must pass self explicitly
ball.move(ball, 100, 120)

```

## Metatables

The metatable for a table defines the behavior of using the table as a value with Lua operators. You can customize a table's metatable to specify custom operator behaviors.

The most common use of metatables is to implement object-oriented inheritance by redefining the `__index` operator. The new definition tells Lua to check for a given property on a parent prototype object if the property is not set on the current object.

```
function myclass:new(o)
  o = o or {}
  setmetatable(o, self)
  self.\_\_index = self
  return o
end

```

PICO-8 supports the `setmetatable()`, `getmetatable()`, `rawset()`, `rawget()`, `rawlen()`, and `rawequals()` built-ins. It does not support any other related Lua functions.

See `setmetatable()` for more information, links to references, and a more complete example.

## Coroutines

A coroutine is a special kind of function that can yield control back to the caller without completely exiting. The caller can then resume the coroutine as many times as needed until the function exits.

PICO-8 supports coroutines using built-in global functions instead of Lua's `coroutine` library. See `cocreate()`, `coresume()`, `costatus()`, and `yield()`.

See Cutscenes and Coroutines for a complete description and example of using coroutines for driving animations.

# Differences from Lua

PICO-8 does not include the Lua standard library. See Math for a description of the PICO-8 mathematical functions. See APIReference for a complete list of PICO-8 built-in functions.

josefnpat wrote a list of technical differences between PICO-8's Lua and the official Lua 5.2.

* List of differences: https://gist.github.com/josefnpat/bfe4aaa5bbb44f572cd0
* Discussion: http://www.lexaloffle.com/bbs/?tid=2611