Lua Syntax Primer

PICO-8 programs are written using Lua syntax, but do not use the standard Lua library. The following is a brief summary of essential Lua syntax.

For more details, or to find out about proper Lua, see www.lua.org.

Comments

-- USE TWO DASHES LIKE THIS TO WRITE A COMMENT
--[[ MULTI-LINE
COMMENTS ]]

Types and assignment

Types in Lua are numbers, strings, booleans and tables:

NUM = 12/100
S = "THIS IS A STRING"
B = FALSE
T = {1,2,3}

Numbers in PICO-8 are all 16:16 fixed point. They range from -32768.0 to 32767.99999

Hexadecimal notation with optional fractional parts can be used:

?0x11        -- 17
?0x11.4000   -- 17.25

Numbers written in decimal are rounded to the closest fixed point value. To see the 32-bit hexadecimal representation, use PRINT(TOSTR(VAL, TRUE)):

?TOSTR(-32768,TRUE)      -- 0x8000.0000 
?TOSTR(32767.99999,TRUE) -- 0X7FFF.FFFF

Dividing by zero evaluates to 0x7fff.ffff if positive, or -0x7fff.ffff if negative.

Conditionals

IF NOT B THEN
    PRINT("B IS FALSE")
ELSE
    PRINT("B IS NOT FALSE")
END

-- with ELSEIF

IF X == 0 THEN
    PRINT("X IS 0")
ELSEIF X < 0 THEN
    PRINT("X IS NEGATIVE")
ELSE
    PRINT("X IS POSITIVE")
END

IF (4 == 4) THEN PRINT("EQUAL") END
IF (4 ~= 3) THEN PRINT("NOT EQUAL") END
IF (4 <= 4) THEN PRINT("LESS THAN OR EQUAL") END
IF (4 > 3) THEN PRINT("MORE THAN") END

Loops

Loop ranges are inclusive:

FOR X=1,5 DO
    PRINT(X)
END
-- PRINTS 1,2,3,4,5

X = 1
WHILE(X <= 5) DO
    PRINT(X)
    X = X + 1
END

FOR X=1,10,3 DO PRINT(X) END   -- 1,4,7,10

FOR X=5,1,-2 DO PRINT(X) END  -- 5,3,1

Functions and Local Variables

Variables declared as LOCAL are scoped to their containing block of code (for example, inside a FUNCTION, a FOR loop, or IF THEN END statement).

Y=0 
FUNCTION PLUSONE(X)
    LOCAL Y = X+1
    RETURN Y
END
PRINT(PLUSONE(2)) -- 3
PRINT(Y)          -- 0

Tables

In Lua, tables are a collection of key-value pairs where the key and value types can both be mixed. They can be used as arrays by indexing them with integers.

A={} -- CREATE AN EMPTY TABLE
A[1] = "BLAH"
A[2] = 42
A["FOO"] = {1,2,3}

Arrays use 1-based indexing by default:

A = {11,12,13,14}
PRINT(A[2]) -- 12

But if you prefer 0-based arrays, just write something the zeroth slot:

A = {[0]=10,11,12,13,14}

Tables with 1-based integer indexes are special though. The length of such an array can be found with the # operator, and PICO-8 uses such arrays to implement ADD, DEL, DELI, ALL and FOREACH functions.

PRINT(#A)   -- 4
ADD(A, 15)
PRINT(#A)   -- 5

Indexes that are strings can be written using dot notation

PLAYER = {}
PLAYER.X = 2 -- is equivalent to PLAYER["X"]
PLAYER.Y = 3

See the Table Functions section for more details.

PICO-8 Shorthand

PICO-8 also allows several non-standard, shorter ways to write common patterns.

IF THEN END statements, and WHILE THEN END can be written on a single line with

IF (NOT B) I=1 J=2

Is equivalent to:

IF NOT B THEN I=1 J=2 END

Note that brackets around the shorthand condition are required.

Assignment operators

Shorthand assignment operators can also be used if the whole statement is on one line. They can be constructed by appending a '=' to any binary operator, including arithmetic (+=, -= …), bitwise (&=, |= …) or the string concatenation operator (…=)

A += 2   -- EQUIVALENT TO: A = A + 2

Note that the LHS appears twice, so for TBL[FN()]+=1, FN() will be called twice.

!= operator

Not shorthand, but pico-8 also accepts != instead of ~= for "not equal to"

PRINT(1 != 2) -- TRUE
PRINT("FOO" == "FOO") -- TRUE (STRING ARE INTERNED)