Getting Started

Getting Started

Keys

keys	function
ALT+ENTER	Toggle Fullscreen
ALT+F4	Fast Quit (Windows)
CTRL-Q	Fast Quit (Mac, Linux)
CTRL-R	Reload / Run / Restart cartridge
CTRL-S	Quick-Save working cartridge
CTRL-M	Mute / Unmute Sound
ENTER / P	Pause Menu (while running cart)

Player 1 default keys: Cursors + ZX / NM / CV
Player 2 default keys: SDFE + tab,Q / shift A

To change the default keys use the KEYCONFIG utility from inside PICO-8:

> KEYCONFIG

Hello World

After PICO-8 boots, try typing some of these commands followed by enter:

> PRINT("HELLO WORLD")
> RECTFILL(80,80,120,100,12)
> CIRCFILL(70,90,20,14)
> FOR I=1,4 DO PRINT(I) END

(Note: PICO-8 only displays upper-case characters -- just type normally without capslock!)

You can build up an interactive program by using commands like this in the code editing mode along with two special callback functions _UPDATE() and _DRAW. For example, the following program allows you to move a circle around with the cursor keys. Press Esc to switch to the code editor and type or copy & paste the following code:

X = 64  Y = 64
FUNCTION _UPDATE()
    IF (BTN(0)) THEN X=X-1 END
    IF (BTN(1)) THEN X=X+1 END
    IF (BTN(2)) THEN Y=Y-1 END
    IF (BTN(3)) THEN Y=Y+1 END
END

FUNCTION _DRAW()
    CLS(5)
    CIRCFILL(X,Y,7,14)
END

Now press Esc to return to the console and type RUN (or press CTRL-R) to see it in action. Please refer to the demo cartridges for more complex programs (type INSTALL_DEMOS).

If you want to store your program for later, use the SAVE command:

> SAVE PINKCIRC

And to load it again:

> LOAD PINKCIRC

Example Cartridges

These cartridges are included with PICO-8 and can be installed by typing:

> INSTALL_DEMOS
> CD DEMOS
> LS

cardrige	description
HELLO	Greetings from PICO-8
API	Demonstrates most PICO-8 functions
JELPI	Platform game demo w/ 2p support
CAST	2.5D Raycaster demo
DRIPPY	Draw a drippy squiggle
WANDER	Simple walking simulator
COLLIDE	Example wall and actor collisions

To run a cartridge, open PICO-8 and type:

> LOAD JELPI
> RUN

Press escape to stop the program, and once more to enter editing mode.

A small collection of BBS carts can also be installed to /GAMES with:

> INSTALL_GAMES

File System

These commands can be used to manage files and directories (folders):

command	description
LS	list the current directory
CD BLAH	change directory
CD …	go up a directory
CD /	change back to top directory (on PICO-8's virtual drive)
MKDIR BLAH	make a directory
FOLDER	open the current directory in the host operating system's file browser
LOAD BLAH	load a cart from the current directory
SAVE BLAH	save a cart to the current directory

If you want to move files around, duplicate them or delete them, use the FOLDER command and do it in the host operating system.

OS	The default location for PICO-8's drive
Windows	C:/Users/Yourname/AppData/Roaming/pico-8/carts
OSX	/Users/Yourname/Library/Application Support/pico-8/carts
Linux	~/.lexaloffle/pico-8/carts

You can change this and other settings in pico-8/config.txt

Tip: The drive directory can be mapped to a cloud drive (provided by Dropbox, Google Drive or similar) in order to create a single disk shared between PICO-8 machines spread across different host machines.

Loading and Saving

When using LOAD and SAVE, the .P8 extension can be omitted and is added automatically.

SAVE FOO
SAVED FOO.P8

Cartridge files can also be dragged and dropped into PICO-8's window to load them.

• Using .p8.png filename extension will write the cartridge in a special image format that looks like a cartridge. Using .p8.rom" writes in a raw 32k binary format.
• Use a filename of "@clip" to load or save to the clipboard.
• Use a filename of "@url" to save to clipboard as a pico-8-edu.com url if it can be encoded in 2040 characters (code and gfx only).

Once a cartridge has been loaded or saved, it can also be quick-saved with CTRL-S

Saving .p8.png carts with a text label and preview image

To generate a label image saved with the cart, run the program first and press CTRL-7 to grab whatever is on the screen. The first two lines of the program starting with '--' are also drawn to the cart's label.

-- OCEAN DIVER LEGENDS
-- BY LOOPY

Code size restrictions for .p8.png / .p8.rom formats

When saving in .png or .rom format, the compressed size of the code must be less than 15360 bytes so that the total data is <= 32k.

To find out the current size of your code, use the INFO command. The compressed size limit
is not enforced for saving in .p8 format.

Using an External Text Editor

It is possible to edit .p8 files directly with a separate text editor. Using CTRL-R to run a cartridge will automatically re-load the file if:

1. There are no unsaved changes in the PICO-8 editors, AND
2. The file differs in content from the last loaded version.

If there are changes to both the cart on disk and in the editor, a notification is displayed:

DIDN'T RELOAD; UNSAVED CHANGES

Alternatively, .lua text files can be modified in a separate editor and then included into the cartridge's code each time it is run using #INCLUDE (in the desired code location):

#INCLUDE YOURFILE.LUA

Backups

When quitting without saving changes, or overwriting an existing file, a backup of the cartridge is saved to {appdata}/pico-8/backup. An extra copy of the current cartridge can also be saved to the same folder by typing BACKUP.

To open the backups folder in the host operating system's file browser, use:

> FOLDER BACKUPS

It is then possible to drag and drop files into the PICO-8 window to load them.

From 0.2.4c, periodic backups are also saved every 20 minutes when not idle in the editor, which means the backups folder will grow by about 1 MB every 5 hours. This can be disabled or adjusted in config.txt

Configuration

PICO-8 reads configuration settings from config.txt at the start of each session, and saves it on exit (so you should edit config.txt when PICO-8 is not running).

The location of the config.txt file depends on the host operating system:

OS	location
Windows	C:/Users/Yourname/AppData/Roaming/pico-8/config.txt
OSX	/Users/Yourname/Library/Application Support/pico-8/config.txt
Linux	~/.lexaloffle/pico-8/config.txt

Use the -home switch (below) to use a different path to store config.txt and other data.

Some settings can be changed while running PICO-8 by typing CONFIG SETTING VALUE. (type CONFIG by itself for a list)

Commandline parameters

// note: these override settings found in config.txt

pico8 [switches] [filename.p8]

switch	description
-width n	set the window width
-height n	set the window height
-windowed n	set windowed mode off (0) or on (1)
-volume n	set audio volume 0…256
-joystick n	joystick controls starts at player n (0…7)
-pixel_perfect n	1 for unfiltered screen stretching at integer scales (on by default)
-preblit_scale n	scale the display by n before blitting to screen (useful with -pixel_perfect 0)
-draw_rect x, y, w, h	absolute window coordinates and size to draw pico-8's screen
-run filename	load and run a cartridge
-x filename	execute a PICO-8 cart headless and then quit (experimental!)
-export param_str	run EXPORT command in headless mode and exit (see notes under export)
-p param_str	pass a parameter string to the specified cartridge
-splore	boot in splore mode
-home path	set the path to store config.txt and other user data files
-root_path path	set the path to store cartridge files
-desktop path	set a location for screenshots and gifs to be saved
-screenshot_scale n	scale of screenshots. default: 3 (368x368 pixels)
-gif_scale n	scale of gif captures. default: 2 (256x256 pixels)
-gif_len n	set the maximum gif length in seconds (1…120)
-gui_theme n	use 1 for a higher contrast editor colour scheme
-timeout n	how many seconds to wait before downloads timeout (default: 30)
-software_blit n	use software blitting mode off (0) or on (1)
-foreground_sleep_ms n	how many milliseconds to sleep between frames
-background_sleep_ms n	how many milliseconds to sleep between frames when running in background
-accept_future n	1 to allow loading cartridges made with future versions of PICO-8
-global_api n	1 to leave api functions in global scope (useful for debugging)

Controller Setup

PICO-8 uses the SDL2 controller configuration scheme. It will detect common controllers on startup and also looks for custom mappings in sdl_controllers.txt in the same directory as config.txt. sdl_controllers.txt has one mapping per line.

To generate a custom mapping string for your controller, use either the controllermap program that comes with SDL2, or try http://www.generalarcade.com/gamepadtool/

To find out the id of your controller as it is detected by SDL2, search for "joysticks" or "Mapping" in log.txt after running PICO-8. This id may vary under different operating systems. See: https://www.lexaloffle.com/bbs/?tid=32130

To set up which keyboard keys trigger joystick buttons presses, use KEYCONFIG.

Screenshots and GIFS

While a cartridge is running use:

keys	description
CTRL-6	Save a screenshot to desktop
CTRL-7	Capture cartridge label image
CTRL-8	Start recording a video
CTRL-9	Save GIF video to desktop (8 seconds by default)

You can save a video at any time (it is always recording); CTRL-8 simply resets the video starting point. To record more than 8 seconds, use the CONFIG command (maximum: 120)

CONFIG GIF_LEN 60

If you would like the recording to reset every time (to create a non-overlapping sequence), use:

CONFIG GIF_RESET_MODE 1

The GIF format can not match 30fps exactly, so PICO-8 instead uses the closest match: 33.3fps.

If you have trouble saving to the desktop, try configuring an alternative desktop path in config.txt

Sharing Cartridges

There are three ways to share carts made in PICO-8:

1. Share the .p8 or .p8.png file directly with other PICO-8 users. Type FOLDER to open the current folder in your host operating system.
2. Post the cart on the Lexaloffe BBS to get a web-playable version http://www.lexaloffle.com/pico-8.php?page=submit
3. Export the cartridge to a stand-alone html/js or native binary player (see the exporters section for details)

SPLORE

SPLORE is a built-in utility for browsing and organizing both local and bbs (online) cartridges. Type SPLORE [enter] to launch it, or launch PICO-8 with -splore.

It is possible to control SPLORE entirely with a joystick:

LEFT and RIGHT to navigate lists of cartridges
UP AND DOWN to select items in each list
X, O or MENU to launch the cartridge

While inside a cart, press MENU to favourite a cartridge or exit to splore. If you're using a keyboard, it's also possible to press F to favourite an item while it is selected in the cartridge list view.

When viewing a list of BBS carts, use the top list item to re-download a list of cartridges. If you are offline, the last downloaded list is displayed, and it is still possible to play any cartridges you have downloaded.

If you have installed PICO-8 on a machine with no internet access, you can also use INSTALL_GAMES to add a small selection of pre-installed BBS carts to /games