APIReference

This is a list of functions provided by PICO-8's Lua-based API .

Typically you run these functions by writing them in the code editor and using the Run command to run your program. You can also call API functions from the PICO-8 command prompt.

Calling functions

Some functions have optional arguments, indicated in this guide by square brackets around the argument name. To specify a value for an optional argument, you must specify values for all other arguments to the left in the argument list.

For example, the spr() function has three required arguments and four optional arguments:

spr( n, x, y, [w,] [h,] [flip_x,] [flip_y] )

This function can be called with three arguments, accepting the defaults for the others:

spr(1, 60, 60)

To specify a value for the flip_x argument, you must also specify w and h, even if you're using their default values:

spr(1, 60, 60, 1, 1, true)

The game loop

If you define these functions in your code, PICO-8 will call them at specific times. See Game loop.

• _init()
• _update()
• _draw()

If your code doesn't use the game loop, you can call this function to copy the graphics buffer to the screen:

• flip()

Graphics

• camera([x,] [y])
• circ(x, y, r, [col])
• circfill(x, y, r, [col])
• clip([x,] [y,] [w,] [h])
• cls()
• color(col)
• cursor([x,] [y,] [col])
• fget(n, [f])
• fillp([pat])
• fset(n, [f,] [v])
• line(x0, y0, x1, y1, [col])
• pal([c0,] [c1,] [p])
• palt([c,] [t])
• pget(x, y)
• print(str, [x,] [y,] [col])
• pset(x, y, [c])
• rect(x0, y0, x1, y1, [col])
• rectfill(x0, y0, x1, y1, [col])
• sget(x, y)
• spr(n, x, y, [w,] [h,] [flip_x,] [flip_y])
• sset(x, y, [c])
• sspr(sx, sy, sw, sh, dx, dy, [dw,] [dh,] [flip_x,] [flip_y])

See also Graphics.

Tables

• add(t, v)
• all(t)
• del(t, v)
• foreach(t, f)
• pairs(t)

See also Lua, Tables.

Input

• btn([i,] [p])
• btnp([i,] [p])

Sound

• music([n,] [fade_len,] [channel_mask])
• sfx(n, [channel,] [offset])

Map

• map(cel_x, cel_y, sx, sy, cel_w, cel_h, [layer])
• mget(x, y)
• mset(x, y, v)

Memory

• cstore(dest_addr, source_addr, len, [filename])
• memcpy(dest_addr, source_addr, len)
• memset(dest_addr, val, len)
• peek(addr)
• poke(addr, val)
• reload(dest_addr, source_addr, len, [filename])

Math

• abs(x)
• atan2(dx, dy)
• band(x, y)
• bnot(x)
• bor(x, y)
• bxor(x, y)
• cos(x)
• flr(x)
• max(x, y)
• mid(x, y, z)
• min(x, y)
• rnd(x)
• shl(x, y)
• shr(x, y)
• sin(x)
• sqrt(x)
• srand(x)

See also Math.

Cartridge data

• cartdata(id)
• dget(index)
• dset(index, value)

Coroutines

• cocreate(func)
• coresume(cor)
• costatus(cor)
• yield()

Values and objects

• setmetatable(tbl, metatbl)
• getmetatable(tbl)
• type(v)
• sub(str, from, [to])
• tonum(str)
• tostr(val, [usehex])

See also Lua, Strings, Tables, Metatables.

Time

• time()

System

• menuitem(index, [label, callback])
• extcmd(cmd)

Debugging

• assert(cond, [message])
• printh(str, [filename], [overwrite])
• stat(n)
• stop() (undocumented)
• trace() (undocumented)

See also

• CommandReference
• Category:API