system

menuitem( index, [label], [callback] )

This function will add or remove additional options in the Pause Menu of the game. You can add up to 5 additional items in the menu.

This is the default pause menu (press "P" on the keyboard, or start button on a controller while a game is running):

This is an example adding all 5 slots in the pause menu:

menuitem( 1 , "item 1" )

menuitem( 3 )

menuitem( 2, "invert Y", invert )

menuitem( 5, "difficulty: "..diff, change_mode )

Some configuration settings are available within PICO-8 and customizable through commands. Watch our video tutorial all about that, also applicable to the free Education Edition.

Config Commands

If you purchased PICO-8 then you have more configuration settings available in the config.txt file. Here is that file from version 0.2.6b.

// - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Configuration for pico-8
// 
// config.txt is read on startup and saved on exit.
// To generate the default config.txt, delete this file.
// 
// - - - - - - - - - - - - - - - - - - - - - - - - - - - -


// :: Video Settings

window_size 0 0 // window width, height
screen_size 0 0 // screen width, height (stretched to window) 
show_fps 0 // Draw frames per second in the corner


// :: Window Settings

windowed 1 // 1 to start up in windowed mode
window_position -1 -1 // x and y position of window (-1, -1 to let the window manager decide)
frameless 0 // 1 to use a window with no frame
fullscreen_method 1 // 0 maximized window (linux)  1 borderless desktop-sized window  2 hardware fullscreen (warning: erratic behaviour under some drivers)
blit_method 0  // 0 auto  1 software (slower but sometimes more reliable)  2 hardware (can do filtered scaling) 



// :: System Settings

foreground_sleep_ms 2 // number of milliseconds to sleep each frame. Try 10 to conserve battery power

background_sleep_ms 10 // number of milliseconds to sleep each frame when running in the background

sessions 74 // number of times program has been run

// (scancode) hold this key down and left-click to simulate right-click
rmb_key 0 // 0 for none  226 for LALT

// Desktop for saving screenshots etc. Defaults to $HOME/Desktop
desktop_path 

// 1 to allow controller input even when application is in background
read_controllers_in_background 0



// :: Audio Settings (use "volume" for PICO-8)

sound_volume 192 // 0..256
music_volume 256 // 0..256


// :: usually 1024. Try 2048 if you get choppy sound

mix_buffer_size 1024


// :: map scancodes. Format: 44=47,80=89,..  (scancode a, scancode b -- when press a, generates b)
// run the program with -scancodes to determine which scancodes to use
map_scancodes 


use_wget 0 // (Linux) 1 to use wget for downloads instead of libcurl (must be installed)



// :: pico-8 

version 0.2.6b

// audio volume: 0..256 
volume 192


// Location of pico-8's root folder
root_path C:/Users/USER/AppData/Roaming/pico-8/carts/


// Location of cartridge save data
cdata_path C:/Users/USER/AppData/Roaming/pico-8/cdata/


// Specify which player index joystick control begins at (0..7)
joystick_index 0


// Treat the first n controllers as if they were a single merged controller
// e.g. merge_joysticks 2 --> P0 gets controllers 0,1, P1 gets controller 2..
merge_joysticks 0


// Custom keyboard scancodes for buttons. player0 0..6, player1 0..5, menu_button, player2 0..5, player3 0..5
button_keys 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 

// Play notes as they are plotted in frequency mode
live_notes 0

// iff 1: when using keyboard cursor, snap to closest pixel / map cel
cursor_snap 0

// 0 default  1 dark blue background in code editor  2 black background in code editor   3 gray background in code editor   
gui_theme 1

// scale of screenshots and gifs // 2 means 256x256
screenshot_scale 3
gif_scale 3

// maximum gif length in seconds (0..120; 0 means no gif recording)
gif_len 120

// when 1, reset the recording when pressing ctrl-9 (useful for creating a non-overlapping sequence)
gif_reset_mode 0

// 0 for off. 1 for auto. 2 to allow control of a cart's framerate due to host machine's cpu capacity
host_framerate_control 1

// filter splore cartridges
// 0 off   1 on (exclude cartridge tagged as 'mature' by community)
splore_filter 0

// tab display width (1 ~ 4 spaces)
tab_width 2

// 0 off 1 on: draw tab characters as small vertical lines
draw_tabs 1

// 0 off 1 on: record the current cartridge and editor view every 3 seconds (see [appdata]/activity.log.txt)
record_activity_log 1

// 0 off 1 on: allow F6..F9 (alternative: ctrl 6..9)
allow_function_keys 1

// 0 off 1 on: automatically check for a newer version of a BBS cart each time it is run.
check_for_cart_updates 1

// hide mouse cursor for n seconds when typing.
auto_hide_mouse_cursor 5

// 0 off 1 on: backup with a new timestamped filename on every run
// normally not needed -- was used for debugging crash-on-run
aggressive_backups 0

// back up cartridge in editor every n minutes when not idle (0 for no periodic backups)
periodic_backups 20

// global screen transformations:
//  129 flip horizontally
//  130 flip vertically
//  133 rotate CW 90 degrees
//  134 rotate CW 180 degrees
//  135 rotate CW 270 degrees
transform_screen 0

// 0 off  > 1: colour to draw pixel grid in the gfx editor at zoom:8 and zoom:4 (16 for black)
gfx_grid_lines 0

// file naming for screenshot / gif / wav captures
// 0 sequential (foo_0.png, foo_1.png)    1 timestamp (foo_20240115_120823.png)
capture_timestamps 0


  

backup

This command will save a backup .p8 file of the currently loaded game in your backups folder. It will save under the current filename, or as "untitled_#.p8" if you haven't yet saved and given the data a filename.

After using this command, you will be notified in PICO-8 that it has been saved and under what name:

To open the backups folder, either navigate to {appdata}/pico-8/backup or use the folder command and specify "backup":

The above command will not notify you in PICO-8, but it will open the backups folder in your file explorer and should look like this (in Windows):

PICO-8 uses the standard SDL2 scheme to handle game controllers. When you start PICO-8, it will automatically detect common controllers. So make sure you plug in your controller before running PICO-8. It will also check for any custom controller settings saved in a file called sdl_controllers.txt, which should be in the same folder as config.txt. In sdl_controllers.txt, each controller setting is written on a separate line.

To create a custom setting for your controller, you can use a program called controllermap that comes with SDL2, or visit this website: Gamepad Tool.

To find your controller’s ID (as recognized by SDL2), open log.txt after running PICO-8, and search for "joysticks" or "Mapping." Keep in mind that this ID might be different depending on the operating system you're using. From this BBS Post, it is recommended to use the mapping from log.txt, paste it into sdl_controllers.txt and then modify it to your liking.

If you want to configure which keyboard keys will act like joystick buttons, you can do that using the *KEYCONFIG* tool."

Anytime inside of PICO-8, whether you are in-game or in an editor, you can take a screenshot by pressing Ctrl+6 (Cmd+6):

This will saves a screenshot to the folder specified in your config file (Default location is $HOME/Desktop). You can change this behavior by editing the PICO-8 config.txt file. See Customize Configurations on how to do that.

Taking screenshots like this also works in the PICO-8 Education Edition, as well as any online PICO-8 player in a browser. However, it does not automatically download. There may be a pause of the game while it is working, then a small thumbnail preview of the image you just captured will be presented in a popup window at the top left of the PICO-8 player. You must right-click on this image and choose Save image as.. to download.

Alternatively, you can press F6:

Warning: This hotkey does not work in your browser.

Anytime inside of PICO-8, whether you are in-game or in an editor, you can take a screenshot by pressing Ctrl+7 (Cmd+7):

This will save a screenshot as a cart label to the currently loaded game.  After doing this, you can then save or export a cartridge as a .p8.png and the label image will be visible on the cover of the cart.

Taking cart label screenshots like this also works in the PICO-8 Education Edition. You cannot use the export command, but you are able to save as .p8.png and download the cart image, which you can upload to the Lexaloffle BBS or share with friends. Drag and drop this .p8.png cart into PICO-8 or the Education Edition to load the game.

Alternatively, you can press F7:

Warning: This hotkey does not work in your browser.

Anytime inside of PICO-8, whether you are in-game or in an editor, you can take a video (animated .gif file) by pressing Ctrl+9 (Cmd+9):

This will save a .gif video to your the folder specified in your config file (Default location is $HOME/Desktop). You can change this behavior by editing the PICO-8 config settings. See Customize Configurations on how to do that.

This also works in the PICO-8 Education Edition, as well as any online PICO-8 player in a browser. However, it does not automatically download. There may be a pause of the game while it is working, then a small thumbnail preview of the gif you just captured will be presented in a popup window at the top left. You must right-click on this gif and choose Save image as.. to download.

Alternatively, you can press F9:

Warning: This hotkey does not work in your browser.

Set a Starting Point

PICO-8 is always recording the screen, with a default duration of the last 8 seconds. You can increase this duration up to 120 seconds using the config settings. See Customize Configurations on how to do that. So by using the above command to save the gif, it will save the full duration of video based on this setting. However, you can also save shorter videos and control when the gif starts recording without changing these settings.

To specify a video recording starting point, first press Ctrl+8 (Cmd+8):

Alternatively, you can press F8 (again, does not work in a browser):

PICO-8 games can be shared and played in several ways, even if you use the free PICO-8 Education Edition.

1. Raw PICO-8 filetype ( .p8 )

The default file that your game is formatted and saved in is a text file with the .p8 file extension. This can be opened and edited in any text editor, but the art, sound, music, and label are encoded and while possible to edit, is very difficult to do manually. Loading this filetype in PICO-8 allows you to use the built in editors.

Find your .p8 files by using the Folder Command. The files are small enough to send as attachments in any email and most chats. 

To open this file, the recipient must open PICO-8 or run the Education Edition in a browser, then simply drag and drop the file onto the screen while viewing the command line.

2. PICO-8 Cartridge Image ( .p8.png )

This image file is formatted to hold your entire game data hidden within. It can be opened by any image viewer or editing software, however, making edits and overwriting it will likely corrupt the game data.

The Education Edition can save .p8.png files using the save command instead of the export command.

Find your .p8.png files by using the Folder Command. The files are small enough to send as attachments in any email and most chats. 

To open this file, the recipient must open PICO-8 or run the Education Edition in a browser, then simply drag and drop the file onto the screen while viewing the command line.

3. Lexaloffle BBS Online ( .p8.png )

Lexaloffle is the company that made and maintains PICO-8. The BBS (Bulletin Board System) is a forum of games, comments, questions, and tutorials, hosted by Lexaloffle as the main hub of the PICO-8 community and the massive games library that can be accessed through Splore.

You will need to make an account and login, then you can upload your cart to the BBS, which you can keep unlisted, or make publicly available to be played in its own webpage or through PICO-8's Splore.

4. Export to HTML

(not available in Education Edition)

You may want to host your game on your own website, or play through a browser while offline. Doing this will create 2 files, a .html file as the landing page and PICO-8 web player, and a .js file which holds your game data and is loaded by the .html file. You will need both files to play your game.

You can upload these two files in the same folder of your website to host your own game online, and share the URL link with your friends.

4. Export as Standalone

(not available in Education Edition)

For the easiest way to play your game offline and share with friends who do not own PICO-8, you can export your game in a fully packaged executable. Separate packages are created for different operating systems, so it doesn't matter if your friends are Windows, Mac, or Linux users.

You can share the exported package with them and your game will come with a barebones PICO-8 game player without the ability to edit, enter commands, nor access splore. It is fully dedicated to only playing your game, much like any other game you download and run on your computer.

4. Upload to a Game Hosting Platform

You can upload your game to online gaming platforms such as itch.io, newgrounds, kongregate, Game Jolt, and even Steam (though not free). You will likely require an exported version of your game either as HTML or Standalone, and then zip them in a specified way depending on the gaming platform you are uploading to.

You can find your PICO-8 files and folders here:

You can browse your PICO-8 files on your operating system whenever you need to. You may want to when changing configuration settings, copying, renaming, or deleting files. This is the main "/pico-8" folder in Windows. 

Note: You may not have all of these folders and files, they are not all necessary. For example, if you haven't used Splore yet to favorite a game, then you won't have a favourites.txt file, but it will be created and saved here once you do so.

Main Folder

As seen above, these are the folders and files you are likely to have in this folder:

carts folder

This is your "/carts" folder, it is the home folder of the files you can browse from the PICO-8 command line. This can be opened quickly with a file explorer in your operating system by using the folder command in PICO-8. There are file navigation commands that you can use in PICO-8 to explore child folders and files within your carts folder.

/bbs folder

"PICO-8 is a fantasy console for making, sharing and playing tiny games and other computer programs. It feels like a regular console, but runs on Windows / Mac / Linux. When you turn it on, the machine greets you with a commandline, a suite of cartridge creation tools, and an online cartridge browser called SPLORE." - PICO-8 Homepage

PICO-8
Official Homepage

Console Specs
Display	128x128 16 colours
Cartridge Size	32k
Sound	4 channel chip blerps
Code	P8 Lua
CPU	4M vm insts/sec
Sprites	256 8x8 sprites
Map	128x32 tiles

Made by Lexaloffle Games LLP.
Developer: Joseph White ("Zep")
Contact: hey@lexaloffle.com

Official Manual FAQ About Lexaloffle

You may have heard of something called "ASCII" (American Standard Code for Information Interchange). It is an ordered sequence of numbers to represent individual characters in computers. The characters could be letters, numbers, punctuation marks, symbols, etc. In ASCII, each character is assigned a unique numeric value or "character code". For example, the ASCII code for the uppercase letter 'A' is 65, while the code for the lowercase letter 'a' is 97.

PICO-8 has its own sequence of characters in its own order. We call these "P8SCII" for fun. Below is the full list of P8SCII characters from 0 to 255, separated into their groups.

You can use chr() and ord() to switch between the P8SCII characters and their ordinal number values.

(0-15)  Control Codes

From numbers 0 to 16, the P8SCII "characters" are actually control codes rather than symbols. These are advanced options that you can use inside of print() to change certain settings. See more about how to use these in the Special Control Commands page.

"Ord" = Ordinal Number Value

(16 - 31) Symbols

"Ord" = Ordinal Number Value | "Chr" = Character

(32 - 126) ASCII Numbers, Letters, and Punctuation

"Ord" = Ordinal Number Value | "Chr" = Character

These all correspond to the standard ASCII numbers and characters. Note that the uppercase letters (A-Z) are actually puny font in PICO-8, while the lowercase letters (a-z) are printed as the normal PICO-8 font which looks like all caps.

(127 - 153) PICO-8 Glyphs

These are special characters unique to PICO-8. You can manually type these glyphs into PICO-8 by holding Shift while pressing a certain letter. Here are the glyphs with the corresponding letter to use with Shift. The arrow and button keys are even recognized in btn() and btnp() functions.

"Ord" = Ordinal Number Value | "Chr" = Character

(154 - 203) Japanese Hiragana

"Ord" = Ordinal Number Value | "Chr" = Character

(204 - 253) Japanese Katakana

"Ord" = Ordinal Number Value | "Chr" = Character

(254 - 255) Arcs

"Ord" = Ordinal Number Value | "Chr" = Character