Returns information about the current runtime environment.
- The ID of the information to return. (See below.)
stat() function returns information about the current runtime environment. Each kind of information has an ID (a number), described below.
Memory and CPU usage Edit
stat(0) returns the memory usage:
- This number is in KiB. 1 would represent 1024 bytes allocated. The fractional portion is accurate, so 1.875 would represent 1920 bytes.
- Accounts for all Lua data, such as variables and tables.
- Ranges from 0 to 2048. (As of 0.1.11g, Lua is allowed up to 2 MiB of data.)
- Does not include
poke()-able RAM such as sprite or video RAM.
- Does not include cartridge ROM.
stat(1) returns the total CPU usage:
- Begins at 0 at the start of the first
_update()after the most recent
- Progresses towards 1 as it nears time for the next frame to begin. Therefore, 1 would represent 1/30s elapsed when using
_update(), or 1/60s for
- A value higher than 1 indicates that the program has gone over its processing budget for code and drawing this frame. Frames may be dropped to compensate, or overall execution may be slowed.
stat(2) returns the system CPU usage:
- This number uses the same range and behavior as
- This number only increases while work is being done in unseen code. For instance, clearing the screen about 70 times would push
stat(2)past 1.0. Almost all of the work would be done inside of calls to
cls(), which is a system call. However, spending the whole frame calculating pi wouldn't budge
stat(2), because it wouldn't involve any system calls.
Clipboard contents Edit
The system clipboard contents can be found in
stat(4), as a string.
See Clipboard for full details on usage and limitations.
Parameter string from a third-party load Edit
When a cart calls load() to load another cart, it can provide an arbitrary string as the third argument. This string is accessible to the loaded cart by calling
If the load() call also included a breadcrumb string, the loaded cart can access this with
Frame rate Edit
stat(7) returns the current frame rate, as the number of frames rendered per second.
Specifically, the frame rate is the number of times per second Pico-8 is able to call the game's _draw() function in the game loop (if provided), or the number of times the game calls flip(). When using the game loop, the expected frame rate is 30 frames per second (fps) with an _update() function or 60 fps with an
_update60() function, but may be fewer if the draw or update functions take too long and Pico-8 skips
_draw() calls to catch up. This makes frame rate an interesting measure of game performance for games that do a lot of calculation between frames.
stat(15) represents the coordinate position of the pause menu if the player were to pause the game at that moment, as the x and y coordinates of the upper left corner and bottom right corner, respectively.
Various things determine the contents of the pause menu dynamically, including menuitem() calls, load() parameters, whether the game was loaded with Splore, and possible future extensions. Pico-8 calculates the size and position of the menu based on its contents.
Sound and music status Edit
stat(19) return the index of the sound effect currently playing on the four channels, respectively. If no sound is playing on the channel,
stat() returns -1.
stat(23) return the note number (0 through 31) of the sound effect currently playing on the four channels, respectively. If no sound is playing on the channel,
stat() returns -1.
From zep: "Note that the row number may not be very precise depending on what is going on with the host operating system's audio mixer. Also in the case of the web player which needs to have a large mixing buffer, the result is often slightly earlier that what is audible."
stat(24) is the music pattern ID currently being played, or -1 if no music is playing. Music is initiated by a call to music().
stat(25) is the number of music patterns played since the most recent call to music().
stat(26) is the number of ticks (notes or rests) played on the current pattern.
Devkit mouse and keyboard mode Edit
You can enable the mouse and keyboard mode (for platforms with a mouse and keyboard) inside a cart:
Once enabled, you can use
stat(...) to read mouse and keyboard values:
- stat(30) -> true if a key is being pressed, false otherwise
- stat(31) -> the key being pressed, as a string
- stat(32) -> X coord
- stat(33) -> Y coord
- stat(34) -> button bitmask (1=primary, 2=secondary, 4=middle)
- stat(36) -> mouse wheel
With this mode enabled, a mouse cursor appears on the Pico-8 screen if the system mouse cursor is in the Pico-8 window.
When the user holds down keys, Pico-8 attempts to report all keys being pressed by changing the value of
stat(31) once per frame to each of the keys in sequence, followed by one frame of no key press (
stat(30) is false), and then the most recent key pressed for subsequent frames until the keys are released. This produces a bit of a "bounce" effect for all held keys, which you may need to account for depending on your application.
Remember that Pico-8 may be running on a machine without a keyboard or mouse connected, such as a game cabinet with only game controllers. Activating this mode displays a message to avoid confusion in exported carts, such as when running on the forum.
Time of day Edit
A Pico-8 cart can access the current time of day, in the host system's local time zone:
stat(90)-> year, e.g. 2018
stat(91)-> month of year, 1-12
stat(92)-> day of month, 1-31
stat(93)-> hour of day, 0-23
stat(94)-> minute of hour, 0-59
stat(95)-> second, 0-61 (usually 0-59, see note below)
A corresponding set of values, but in UTC time, are available at
Note: PICO-8 and/or Lua appear to be using the standard C tm_time interface to provide these values, and as such, you should be aware that the current second is allowed to go past 59, to 60 or 61, in the event of leap seconds occurring.
function _update() -- game update code... end function _draw() cls() -- game draw code... print('mem:'..stat(0), 0, 0, 7) print('cpu:'..stat(1), 0, 8, 7) end