stat( n )

Returns information about the current runtime environment.

The ID of the information to return. (See below.)

The stat() function returns information about the current runtime environment. Each kind of information has an ID (a number), described below.

You can display this metric on the game screen with print(), write it to the console with printh(), or perhaps use it some other way to adjust the behavior of your program.

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 peek()/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 _draw().
  • 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 _update60().
  • 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 stat(1).
  • 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 stat(6).

If the load() call also included a breadcrumb string, the loaded cart can access this with stat(100).

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.

Pause menu location Edit

stat(12) through 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(16) through 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(20) through 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:

poke(0x5F2D, 1)

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 stat(80) through stat(85).

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.

Examples Edit

function _update()
  -- game update code...
function _draw()
  -- game draw code...
  print('mem:'..stat(0), 0, 0, 7)
  print('cpu:'..stat(1), 0, 8, 7)

See also Edit