RunningPico8

To run the PICO-8 app, you either double-click on the PICO-8 app icon, or you run it from a command console (aka terminal window). There are minor differences depending on which operating system you use.

Opening the app with the icon starts PICO-8 at the command prompt with default options.

See the entry on printh() for information about how to locate the PICO-8 command for each operating system.

Command-line flags

When you run PICO-8 from the command line, you can specify command-line flags to control certain behaviors. For example, you can specify the name of a cartridge file, and PICO-8 will load and run the cart immediately.

Note that the flags below make some assumptions:

• When in windowed mode, the screen rectangle refers to the inset rectangle where the virtual PICO-8 screen is shown, including any padding.
• The "window_x,y" position is not actually the position of the window, but instead the position of the screen rectangle, relative to the desktop. The window borders and title bar will be constructed around this rectangle.
• The "draw_rect" is the rectangle within the screen rectangle where PICO-8 will actually display the contents of screen data memory. If there is a gap between the draw rectangle and the screen rectangle, it will be filled with the color black.

These are the flags:

pico8 [flags] [filename.p8]

• -run filename : automatically load and run a cartridge
• -x : load the given cart, run it without a display, sound, or input, then exit when the cart exits
• -export param_str : run EXPORT command in headless mode and exit (see export)
• -p param_str : pass the given parameter into the cart. Can be accessed with stat(6) similar to load()
• -windowed n : set windowed mode off (0) or on (1)
• -window_x n : set the x position of the inset screen rectangle, relative to the desktop
• -window_y n : set the y position of the inset screen rectangle, relative to the desktop
• -displays_x n : sets the horizontal number of displays to render in pico8 (max 4 total)
• -displays_y n : sets the vertical number of displays to render in pico8 (max 4 total)
• -width n : set the screen rectangle width and adjust scale to fit if not specified
• -height n : set the screen rectangle height and adjust scale to fit if not specified
• -draw_rect x,y,w,h : where to display the contents of screen data memory, relative to the screen rectangle
• -frameless : frameless/borderless window mode off (0) or on (1)
• -sound n : sound volume 0..256
• -music n : sound 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)
• -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 (384x384 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 0 for the default background, 1 for a dark blue background, 2 for a black background, and 3 for a dark gray background in the code editor.
• -tab_width n : number of spaces in a tab in the code editor (default: 1)
• -timeout n : how many seconds to wait before downloads timeout (default: 30)
• -software_blit n : use software blitting mode off (0) or on (1)
• -show_fps n : turn the FPS counter off (0) or on (1) (the PICO-8 application's display fps, not the running cart's fps)
• -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 : use 1 to allow loading cartridges made with future versions of PICO-8
• -global_api : prevent PICO-8 from copying all API calls to locals (useful for debugging tools that procedurally manipulate _ENV for hooking purposes)

Examples

To open PICO-8 and automatically start Splore in Mac OS X:

/Applications/PICO-8.app/Contents/MacOS/pico8 -splore

To run a specified cart full-screen on Windows:

"C:\Program Files (x86)\PICO-8\pico8.exe" -windowed 0 -run celeste.p8