Set fps

WARNING The functionality described below may not be safe to use in some or many cases. Read all warnings and technical notes and understand all possible consequences before use.

_set_fps( rate )

Set the target framerate.

rate

The target framerate: 15, 30, or 60.

This internal, undocumented function is how the PICO-8 application sets the target frame rate.

When the user's code is first run, PICO-8 is in 30fps mode. Typically, the user's code will be run through, without any actual drawing being done, and then control will return to the hidden outer code that will then begin to call _update() and _draw() repeatedly.

At the point where the outer code takes over, it will check for the presence of either _update() or _update60() and then call either _set_fps(30) or _set_fps(60), respectively.

If, however, the user wishes to do some drawing before control returns to the outer code, they may change the default frame rate with this function and then create their own custom main loop that updates, draws, and calls flip(), repeatedly.

Note on 15fps mode

This mode is really most practical when calling _set_fps(15) from root user code, and then doing all updating and rendering with a custom main loop. Otherwise the outer code will take over and assign either 30fps or 60fps mode, depending on which functions are implemented.

However, if _set_fps(15) is called from within _update() (note that _init() is too early), then the outer code will begin to call _update() twice for every call to _draw(), effectively halving the draw rate to 15fps. This is both klunky and unsupported, so it would generally be better just to use standard 30fps mode and return early from every other _draw() call.

Warning

As an undocumented function, _set_fps() cannot be relied on for a game. Its functionality may change or be removed in future versions. Still, some may find a pragmatic use for it in tools or demos. Just be aware that you use it at your own risk.

Examples

-- make a reddish orange by rapidly alternating red and orange at 60fps
_set_fps(60)
while true do
  cls(8) -- red
  flip()
  cls(9) -- orange
  flip()
end

-- wait for 1 second at 15fps
_set_fps(15)
for i=1,15 do
  flip()
end