Internal API Functions

This page is a clearinghouse for undocumented & internal API functions. As content here is elaborated on and fleshed out, it could be promoted to separate pages if it describes an API that's considered useful enough.

## Warning

As these are internal functions, they cannot be relied on for a game. Their functionality **will** change or be removed in future versions. Still, some may find a pragmatic use for them in tools or demos. Just be aware that you use them at your own risk.

## Message to fellow editors

Remember that relative neophytes will discover this and other undocumented API pages. PICO-8 is, for many, a learning platform. They are not yet aware of what it means to use an undocumented API function, and what risks are associated. It's your responsibility as their indirect mentor to help them understand that such functions are not actually *intended* to be used directly, even if they *are* visible at runtime, and should only be used with understanding and care.

Please be sure to include a warning similar to the one above on any functions that you break out into their own pages. This is the basic template used for existing pages, which can be adapted as necessary:

For functions and functionality that are *clearly* intended only to *support* the outer layer of the PICO-8 Lua wrapper, it'd probably be good to go farther and suggest strongly that they not be used *at all*, explaining that this documentation is only for the sake of *understanding* the inner workings of PICO-8.

Also please remember to include the page in Category:Undocumented API.

Thanks!

## Internal API Functions

* `bbsreq()`
​​​​​produces red warning popup at the bottom "can not connect to bbs req host"
behavior only happens once per PICO-8 restart
C++ definition includes a call to ​​​​​​`add_api_function_name bbsreq`
* `radio()`
has no obivous effect
returns `nil, 0`
* `set_draw_slice(n[,vertical])`
tells Voxatron what Z layer to draw the PICO-8 screen at(?)
n=0-63, or 0-127 if vertical is `true`
can be called more than once per frame for 3D effects in Voxatron?
This is now documented as an Undocumented API for PICO-8, since it IS documented on the Voxatron side.
* `_startframe()`
effect is currently same as `holdframe()`'s effect
used in PICO-8's internal header's `_mainloop()` function
called after first `_update_buttons()`, before `first _mark_cpu(0)`
global only, no closure
* `_get_menu_item_selected(n)`
returns `true` or `false` if the n-th menu item is selected (n in [1..5]), or `nil` for an invalid n
used automatically by `_mainloop()`
* `_update_buttons(n)`
used in PICO-8's internal header's `_mainloop()` function
n affects the value returned by time().
Note this already has its own Undocumented API page, due to its common use in custom main loops for tweetcarts, which zep does not seem to object to.
* `_update_framerate()`
used in PICO-8's internal header's `_mainloop()` function
called after `flip()`
* `_set_mainloop_exists(n)`
used in PICO-8's internal header
called 1-2 times. n=0 first, then n=1 if `_mainloop()` exists, otherwise n=2 and then `_mainloop()` is created
if called with n=2, `time()` no longer advances automatically.
* `_set_fps(n)`
used in PICO-8's internal header
called once based on the existence of `_update60()`, n=30 or n=60, though technically it also accepts 15
value used throughout PICO-8 code
Note this already has its own Undocumented API page, due to its common use in custom main loops for tweetcarts, which zep does not seem to object to.
* `_mark_cpu(n)`
used in PICO-8's internal header's `_mainloop()` function
called with n=0 before `_update()` or `_update60()`, n=1 after last update in `_mainloop()`, n=2 after \_draw()
no obvious effect, possibly related to `stat(1)`?
* `_set_paused(n)`
code seems to want a number parameter
no obvious effect (tested with n=0, 1, -32768, 32767, 1/32768, true, false)
* `__refund_cpu__(n)`
used in PICO-8's internal header
n=-16 and n=-17 in header
no obvious effect, tested in/after high-cpu code
function has checks in place before passing to `lua_spend_cpu()`