APIReference

TODO: This page is largely unedited from its original PICO-8 source and a lot of this info is probably now completely or partially wrong. Needs MUUUUCH work. Haaalp.

This is a list of functions provided by Picotron'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 Picotron 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 two optional arguments:

```
spr( s, x, y, [flip_x,] [flip_y] )

```

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

```
spr(s, 60, 60)

```

To specify a value for the `flip_y` argument, you must also specify `flip_x`, even if you're using its default value:

```
spr(s, 60, 60, false, true)

```

## The game loop

TODO: not sure if this is true anymore

If you define these functions in your code, Picotron 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

TODO: dunno which of these are the same or still exist

* `camera([x,] [y])`
* `circ(x, y, r, [col])`
* `circfill(x, y, r, [col])`
* `oval(x0, y0, x1, y1, [col])`
* `ovalfill(x0, y0, x1, y1, [col])`
* `clip([x,] [y,] [w,] [h])`
* `cls([col])`
* `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])`
* `tline(x0, y0, x1, y1, mx, my, [mdx,] [mdy])`

See also Graphics.

## Tables

TODO: dunno which of these are the same or still exist. some are in table.\*

* `add(t, v, [i])`
* `all(t)`
* `count(t, [v])`
* `del(t, v)`
* `deli(t, i)`
* `foreach(t, f)`
* `ipairs(t)`
* `pack(...)`
* `pairs(t)`
* `unpack(t, [i], [j])`
* `next(t, [key])`

See also Lua, Tables.

## Input

TODO: anything else?

* `btn([i,] [p])`
* `btnp([i,] [p])`

## Sound

TODO: there's no sound right now, wait for it to be added before trying to flesh this out

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

See also Stat: PCM (undocumented)

## Map

TODO: since sprites are just userdata now, you can probably set up your own map and draw from it with spr(). dunno if any of this still exists.

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

## Memory

TODO: no idea. pretty sure peek/poke are still there

* `cstore(destaddr, sourceaddr, len, [filename])`
* `memcpy(dest_addr, source_addr, len)`
* `memset(dest_addr, val, len)`
* `peek(addr, [n])`
* `peek2(addr, [n])`
* `peek4(addr, [n])`
* `poke(addr, [value,] [...])`
* `poke2(addr, [...])`
* `poke4(addr, [...])`
* `reload(destaddr, sourceaddr, len, [filename])`
* `serial(channel, sourceaddr, size)`

## Math

TODO: some of this might be off in math.\* now

* `abs(x)`
* `atan2(dx, dy)`
* `band(x, y)`
* `bnot(x)`
* `bor(x, y)`
* `bxor(x, y)`
* `ceil(x)`
* `cos(x)`
* `flr(x)`
* `lshr(num, bits)`
* `max(x, y)`
* `mid(x, y, z)`
* `min(x, y)`
* `rnd(x)`
* `rotl(num, bits)`
* `rotr(num, bits)`
* `sgn(x)`
* `shl(x, y)`
* `shr(x, y)`
* `sin(x)`
* `sqrt(x)`
* `srand(x)`

See also Math.

## Cartridge data

TODO: unlikely to work the same

* `cartdata(id)`
* `dget(index)`
* `dset(index, value)`

* `cstore(dest_addr, source_addr, len, [filename])`
* `reload(dest_addr, source_addr, len, [filename])`

## Coroutines

TODO: do these still exist or are they in thread.\*?

* `cocreate(func)`
* `coresume(cor, [...])`
* `costatus(cor)`
* `yield([...])`

## Strings

TODO: some of this definitely exists, need to document

* `split(str, [separator, ] [convert_numbers])`
* `sub(str, from, [to])`
* `chr(num)`
* `ord(str, [index])`
* `tonum(val, [format_flags])`
* `tostr(val, [usehex])`

## Values and objects

TODO: some of this definitely exists, need to document

* `setmetatable(tbl, metatbl)`
* `getmetatable(tbl)`
* `rawequal(t1, t2)`
* `rawget(t, n)`
* `rawlen(t)`
* `rawset(t, n, v)`
* `select(i, ...)`
* `type(v)`

See also Lua, Strings, Tables, Metatables.

## Time

* `time()` (alias: `t()`)

See also Stat: Time of Day

## System

TODO: some of this probably exists, need to document

* `menuitem(index, [label, callback])`
* `extcmd(cmd)`
* `run([breadcrumb])`

## Debugging

TODO: some of this probably exists, need to document

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

## See also

* CommandReference
* Category:API
* Bitwise Operations