pico-8 api cheatsheet

camera([x, y]) -- set camera position
circ(x, y, r, [col]) -- draw circle
circfill(x, y, r, [col]) -- draw filled circle
clip([x, y, w, h]) -- set screen clipping region
cls() -- clear screen
color(col) -- set default color
cursor(x, y) -- set cursor and CR/LF margin position
fget(n, [f]) -- get values of sprite flags
flip() -- flip screen back buffer
fset(n, [f], v) -- set values of sprite flags
line(x0, y0, x1, y1, [col]) -- draw line
pal(c0, c1, [p]) -- switch colour 0 to colour 1; p = 0 = draw palette; p = 1 = screen palette
palt(c, t) -- set transparency for colour to t (bool)
pget(x, y) -- get pixel colour
print(str, [x, y, [col]]) -- print string
printh(str) -- print string to terminal
pset(x, y, [c]) -- set pixel colour
rect(x0, y0, x1, y1, [col]) -- draw rectangle
rectfill(x0, y0, x1, y1, [col]) -- draw filled rectangle
sget(x, y) -- get spritesheet pixel colour
spr(n, x, y, [w, h], [flip_x], [flip_y]) -- draw sprite
sset(x, y, [c]) -- set spritesheet pixel colour
sspr(sx, sy, sw, sh, dx, dy, [dw, dh], [flip_x], [flip_y]) -- draw texture from spritesheet

add(t, v) -- add v to t
all(t) -- used in 'for v in all(t)' loops
count(t) -- returns number of elements in the table
del(t, v) -- delete first instance of v in t
foreach(t, f) -- call f() for each v in t
pairs(t) -- used in 'for k,v in pairs(t)' loops

btn([i, [p]]) -- get button i state for player p
btnp([i, [p]]) -- only true when the button was not pressed the last frame. repeats every 4 frames after button held for 15 frames

music([n, [fade_len, [channel_mask]]]) -- play music, -1: stop
sfx(n, [channel, [offset]]) -- play sfx, -1: stop in channel, -2: release loop in channel

map(cel_x, cel_y, sx, sy, cel_w, cel_h, [layer]) -- draw map, layers from flags, sprite 0 is empty
mget(x, y) -- get map value
mset(x, y, v) -- set map value

cstore(dest_addr, src_addr, len) [filename] -- copy bytes from ram to rom [load from filename]
memcpy(dest_addr, src_addr, len) -- copy bytes
memset(dest_addr, val, len) -- set len bytes to val
peek(addr) -- read byte in ram address
poke(addr, val) -- write val in ram address
reload(dest_addr, src_addr, len) [filename] -- copy bytes from rom to ram [load from filename]

# types:

1. base ram (32kB)
2. cart rom
3. lua ram (256kB)

# ram layout:

0x0  - gfx
0x1000 - gfx2/map2 (shared)
0x2000 - map
0x3000 - gfx_props
0x3100 - song
0x3200 - sfx
0x4300 - user data
0x5e00 - persistent cart data (256 bytes)
0x5f00 - draw state
0x5f40 - hardware state
0x5f80 - gpio pins (128 bytes) // in development
0x6000 - screen (8k)

abs(x) -- x absolute value
atan2(dx, dy) -- convert (dx, dy) to an angle in [0..1]
band(x, y) -- bitwise conjunction
bnot(x) -- bitwise negation
bor(x, y) -- bitwise disjunction
bxor(x, y) -- bitwise exclusive disjunction
cos(x) -- x cosine, [0..1]
flr(x) -- round down
-flr(-x) -- not a function per se, but will work as ceil(x)
max(x, y) -- x/y maximum
mid(x, y, z) -- x/y/z middle value
min(x, y) -- x/y minimum
rnd(x) -- random, 0 <= n < x
sgn(x) -- returns argument sign, -1, 0, 1
shl(x, y) -- shift left
shr(x, y) -- shift right
sin(x) -- x sine, [0..1]
sqrt(x) -- x square root
srand(x) -- set random seed

#s -- string length
"three "..4 -- string concatenation
sub(str, from, [to]) -- substring

cartdata(id) -- open cart data named id (once per execution!)
dget(idx) -- get number at index
dset(idx, val) -- set number at index to value

help -- show summary of system commands

cd .. -- change to parent directory
cd [dirname] -- change directory
dir() -- list items
export(filename.wav) -- export the current SFX
export(filename%d.wav) -- export all sound effects as numbered files
export(filename.png) -- export spritesheet
folder() -- open carts folder in operating system
import(filename.png) -- import spritesheet. expects 128x128 png and colour-fits to the pico-8 palette
install_demos -- install demo p8 carts alongside pico-8 app
keyconfig -- keyboard configuration for player buttons
load(filename) -- load cart
ls() -- list items
mkdir(dirname) -- create directory
reboot() -- reboot pico8
resume() -- resume cart execution
run() -- boot cart
save(filename) -- save cart
shutdown() -- close pico-8 app
splore -- explore cartridges
stat(x) -- 0 = mem; 1 = cpu;
info() -- print cart info

pico-8 [switches] [filename.p8]

-run -- boot filename.p8 on startup
-width n -- set the window or screen width and adjust scale to fit if not specified
-height n -- set the window or screen height and adjust scale to fit if not specified
-scale n -- set the size of each PICO-8 pixel. "-scale 3" gives pixels rendered at 3x3
-windowed n -- set windowed mode off (0) or on (1)
-sound n -- sound volume 0..256
-music n -- sound volume 0..256
-joystick n -- joystick controls starts at player n (0..7)
-aspect n -- set the aspect ratio. 420 means 1:1 (default), 560 for 4:3, 525 for 5:4 etc. 
-run filename -- automatically load and run a cartridge
-splore -- boot in splore mode