commands


folder

Opens the current folder in a new window, outside of PICO-8. The default selected folder when you open PICO-8 is the .../pico-8/carts/ folder.

To change the designated location for your saved carts folder, see How to Save Your Game.


You can specify other folders you want to open as well right in the command line:

folder backups = open the ".../pico-8/backup/" folder, to see all backed up .p8 files

folder config open the ".../pico-8/" folder, for easy access to the config.txt file.

folder bbs open the ".../pico-8/bbs/" folder, to see all splore related files including the games you played from splore, downloaded locally as png carts and their labels.

folder desktop open a folder to view your desktop files, this is the default location of saved PICO-8 screenshots and video gifs.

1899

12 May 2023


load [game_name]

Loads the game if that game file is in the folder already open. Navigate to the parent folder of the game with the change directory ( cd ) command.

Use Tab on the keyboard to help auto-complete game file names.

You do not need to include the filetype such as.p8 or .p8.png.



load #game_name

(internet connection required) Loads the game from the Lexaloffle BBS library of games. You can find the specific game name by looking under the BBS player at the bottom left corner, just after the cart icon. Here's an example:

BBS Cart ID Location

The dash and number that appears at the end is the version of the game. You don't need to include that when using the load command, unless you want to load a specific version.

For example: load #puzzlesofthepaladin (no version number) will load the latest version automatically.


926

10 Oct 2024


save [game_name]

saves the loaded game into the folder already open

or anywhere in PICO-8, press:

This shortcut only works after saving the currently loaded game locally at least once using the full command "save".

218

5 Feb 2023


ls or dir

ls = "list"

dir = "directory" (folder)

shows all files and folders inside the folder currently open

769

19 Apr 2023


run

run = play the currenty loaded game

or anywhere in PICO-8, press:

If nothing happens, then you do not have a game loaded. An empty game cart is loaded everytime you open PICO-8, so nothing happens when you try to run this.

806

5 Feb 2023


Stops the running cart.


stop( [message] )

Stop the cart and optionally print a message.

838

4 Nov 2023


assert( condition, [message] )

If CONDITION is false, stop the program and print MESSAGE if it is given. This can be useful for debugging cartridges, by ASSERT()'ing that things that you expect to be true are indeed true.

855

4 Nov 2023


reboot

Reboot = "restart"

restarts the whole PICO-8 system, make sure you save first!

681

5 Feb 2023


reset()

Reset the values in RAM from 0x5f00..0x5f7f to their default values. This includes the palette, camera position, clipping and fill pattern. If you get lost at the command prompt because the draw state makes viewing text impossible, try typing RESET! It can also be called from a running program.

(temporarily copied from manual - to be edited)

738

5 Feb 2023


info()

Print out some information about the cartridge: Code size, tokens, compressed size


Also displayed:

UNSAVED CHANGES   When the cartridge in memory differs to the one on disk

EXTERNAL CHANGES  When the cartridge on disk has changed since it was loaded

  (e.g. by editing the program using a separate text editor)

691

4 Nov 2023


Flip the back buffer to screen and wait for next frame. This call is not needed when there is a _DRAW() or _UPDATE() callback defined, as the flip is performed automatically. But when using a custom main loop, a call to FLIP is normally needed:

::_::
CLS()
FOR I=1,100 DO
  A=I/50 - T()
  X=64+COS(A)*I
  Y=64+SIN(A)*I
  CIRCFILL(X,Y,1,8+(I/4)%8)
END
FLIP()GOTO _

If your program does not call FLIP before a frame is up, and a _DRAW() callback is not in progress, the current contents of the back buffer are copied to screen.


(temporarily copied from manual - to be edited)

905

5 Feb 2023


printh()

Print to the console.

926

5 Feb 2023


time() or t()

This function returns the number of seconds as a decimal up to ten-thousands of a second since the running your game. This is calculated by counting the number of times _update or _update60 is called.

For _update, which runs 30 times per second, time() increases by .0333.

For _update60, which runs 60 times per second, time() increases by .0167.

If you want to use this as a counter in your game, you should store it once per frame because multiple calls of time() from the same frame will return the same result, wasting tokens.

elapsed_seconds = time()

1059

12 Apr 2023


stat(x)

Get system status where X is:

0 Memory usage (0..2048)
1 CPU used since last flip (1.0 == 100% CPU)
4 Clipboard contents (after user has pressed CTRL-V)
6 Parameter string
7 Current framerate
46..49 Index of currently playing SFX on channels 0..3
50..53 Note number (0..31) on channel 0..3
54 Currently playing pattern index
55 Total patterns played
56 Ticks played on current pattern
57 (Boolean) TRUE when music is playing
80...85 UTC time: year, month, day, hour, minute, second
90...95 Local time
100 Current breadcrumb label, or nil
110 Returns true when in frame-by-frame mode

789

5 Feb 2023



extcmd( string , [param1], [param2] )

Some of the commands accept parameters (shown as "param1" and "param2" above).


Command Strings Simple
"pause" request the pause menu be opened
"reset" request a cart reset
"go_back" return to the previous cart if there is one
"label" set cart label
"shutdown" quit cartridge (from exported binary)
"folder" open current working folder on the host operating system
"audio_rec" start recording audio
"rec" set .gif video start point (F8)
"rec_frames" set video start point in frames mode


Command Strings with Parameters param1 param2
"screen" save a screenshot (F6) number, scaling factor save location, 0 = desktop, 1 = current folder
"video" save a .gif to desktop (F9) number, scaling factor save location, 0 = desktop, 1 = current folder
"audio_end" save recorded audio to desktop (no supported from web) save location, 0 = desktop, 1 = current folder  
"set_filename" set the filename for screenshots / gifs / audio recordings "filename"  
"set_title" set the host window title "title"  

Here are some examples of how to use extcmd() with appropriate parameters.

extcmd("video", 4 , 1)

This will record a .gif, with a scaling factor of 4 (512x512 pixels), and save to the currently opened carts folder (user data).


810

5 Feb 2023


These are advanced options that you can use inside of print() to change certain settings.

Here are the Control Codes:

\0 terminate printing
\* repeat next character this number of times.
\# draw solid background with this color number.
\- shift cursor horizontally by a value minus 16 pixels
\| shift cursor vertically by a value minus 16 pixels
\+ shift cursor by two values minus 16 pixels on X and Y axes.
\^ special commands (more below)
\a audio commands (more below)
\b backspace
\t tab
\n newline
\v decorate previous character (more below)
\f set foreground colour (text color)
\r carriage return (move cursor to start of same line)
\014 switch to custom font (memory 0x5600)
\015 switch to default font

Some of the above commands take one or two values (similar to arguments passed to functions) immediately after the code to alter how it affects your print string or other settings.

These values can be given as single digits (0-9). Higher values can be given using letters (similar to hexidecimal code). So a=10, b=11, all the way to z=35.


Examples:

print("print this \0 but don't print this") 
--print this

- This will stop printing at the "\0" in the string.

print("\*5abc") 
--aaaaabc

- This will duplicate the letter A, 5 times.

print("\*a123") 
--111111111123

- This will duplicate the number 1, A times (which is 10).

print("print this\b") 
--print thi

- This will remove the character just before the "\b".

print("start here \n continue here") 
--start here
--continue here

- This will begin printing on the current line, then move the cursor down and continue printing on the next line.

print("start \t continue") 
--start   continue

- This will indent 11 pixels then continue printing the string.


\^

These special commands begin with "^" and then take one or two parameters immediately after.

\^# Skip this # of frames where [1,2,3,4...9] = [1,2,4,8...256]
\^c# Clear the screen to color #, and reset cursor to (0,0)
\^d# Set the delay to this # of frames for every character printed.
\^g Move the cursor position to home.
\^h Set the current cursor position as home.
\^j## Jump the cursor this first # (0...9) of pixels times 4 to the right, and this second # (0...9) of pixels times 4 down.
\^r# Set the character wrap boundary to this # times 4
\^s set tab stop width to p0 pixels used by t
\^x set character width default 4
\^y set character height default 6
Enable these Rendering Options (disable with prefix -)
\^w print in wide mode: characters scaled by 2x1 pixels
\^t print in tall mode: characters scaled by 1x2 pixels
\^= print in stripey mode: drawn only even pixels when wide or tall
\^p print in pinball mode: wide, tall, and stripey modes combined
\^i invert the foreground and background colors
\^b toggle a 1 pixel border padding on left and top (default on)
\^# (use the actual # symbol) enable solid background, disabled by default

1514

10 Sep 2023


help

Lists important commands and buttons used to navigate PICO-8 and get started. Type "help" into the command screen and press enter, you will see:


You can also type in a topic or keyword after "help" to get more information immediately.

If you type help and then one of the topics (one of the words in blue above), then you will get a list of keywords and built in functions (again, in blue). After seeing that "math" is a possible topic to ask for help on, we type "help math" and press enter. Then we see that "sqrt" is a math function we can ask about, so then type "help sqrt". Here is that interaction:

You can also directly ask for help about a specific function name. For example, type in help cls or help time and you will get brief description of these functions:



688

15 Mar 2023


install_demos

This command is used to install the PICO-8 demonstration cartridges, which are pre-made demos that showcase different features and techniques for creating games. When you use this command, a "demos" subfolder is created in the currently opened folder. This subfolder contains a collection of demonstration cartridges that you can explore using the splore or load command.

First time setup:
1) Open PICO-8 and view the welcome screen.
2) Type in "install_demos" (no quotes, no spaces, with underscore) and press Enter.
3) The demo carts have been downloaded, to navigate to them, first type "cd demos" (without quotes, with space) and press enter.
4) You can type "ls" or "dir" and press enter to view the file names in this demos folder.
5) To load a demo cart, type "load [filename]" where filename is the name of the demo cart, listed below.

The demo carts include:

api A well commented cart demonstrating many common built-in functions of the PICO-8 Lua.
automata A demo of Cellular Automata: a system where a grid of cells changes states based on simple rules and the states of their neighbors.
bounce A bouncy physics demo of a sprite inside of a ball, colliding with bounds of the screen.
cast A first-person view raycasting demo, using the 2D map and colors to define and draw a 3D space. Complete with collision and moving platforms.
collide A top-down demo of collisions with map drawn walls and animated objects such as a bouncy ball, coins, and other characters that zep named "peopleoids".
dots3d A 3D rotating and zooming cube made of many circles.
drippy An etch-a-sketch style drawing demo where the pixels slowly and colorfully bleed down the screen.
hello A wavy and colorful sprite animation demo of the classic text "hello world".
jelpi A full platformer demo with what has become the mascot character of PICO-8. It has everything from platformer movement, item pickups, powerups, enemies, collectibles, signs, puzzles, hard to reach areas, background scroll, multiple levels, particle effects, and a dragon boss.
sort A fun sorting of a table demo using giraffes of random heights to visualize it.
wander A top-down demo of a cat that can pick up apples, and wander across multiple screens on the map. Instead of a constant scroll, this demonstrates a quick screen cut such as those used in the first Legend of Zelda dungeons.
waves A wavy ripple animation effect using only pset() to draw a grid of pixels.

1498

4 Nov 2023


Images in this Guide by NerdyTeachers is licensed under CC BY-SA 4.0
Font