Lua Syntax Primer

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.

1. 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 short-hand condition are required.

2. 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

3. != 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)