PICO-8 Wiki
(0.1.9 command line args)
Tags: apiedit, Visual edit
m (formatting)
Tag: Source edit
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
  +
{{DISPLAYTITLE:Running PICO-8}}
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.
+
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 [[CommandPrompt|command prompt]] with default options.
+
Opening the app with the icon starts PICO-8 at the [[CommandPrompt|command prompt]] with default options.
   
 
See the entry on <code>[[Printh|printh()]]</code> for information about how to locate the PICO-8 command for each operating system.
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.
 
   
 
==Command-line flags==
See the entry on [[Printh|printh()]] for information about how to locate the Pico-8 command for each operating system.
 
   
 
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.
Command flags:
 
   
  +
Note that the flags below make some assumptions:
<code>pico8 <nowiki>[switches] [filename.p8]</nowiki></code>
 
   
  +
* When in windowed mode, the ''screen rectangle'' refers to the inset rectangle where the virtual PICO-8 screen is shown, including any padding.
* <code>-run</code> : boot filename.p8 on startup
 
  +
* 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.
* <code>-width n</code> : set the window or screen width and adjust scale to fit if not specified
 
  +
* The "draw_rect" is the rectangle ''within'' the screen rectangle where PICO-8 will actually display the contents of [[Memory#Screen data|screen data memory]]. If there is a gap between the draw rectangle and the screen rectangle, it will be filled with the color black.
* <code>-height n</code> : set the window or screen height and adjust scale to fit if not specified
 
  +
  +
These are the flags:
  +
 
<code>pico8 <nowiki>[flags] [filename.p8]</nowiki></code>
  +
 
* <code>-run filename</code> : automatically load and run a cartridge
  +
* <code>-x</code> : load the given cart, run it without a display, sound, or input, then exit when the cart exits
  +
* <code>-export param_str</code> : run EXPORT command in headless mode and exit (see <code>[[export]]</code>)
  +
* <code>-p param_str</code> : pass the given parameter into the cart. Can be accessed with [[Stat|<code>stat(6)</code>]] similar to [[Load|<code>load()</code>]]
 
* <code>-windowed n</code> : set windowed mode off (0) or on (1)
 
* <code>-windowed n</code> : set windowed mode off (0) or on (1)
  +
* <code>-window_x n</code> : set the x position of the inset screen rectangle, relative to the desktop
  +
* <code>-window_y n</code> : set the y position of the inset screen rectangle, relative to the desktop
 
* <code>-width n</code> : set the screen rectangle width and adjust scale to fit if not specified
 
* <code>-height n</code> : set the screen rectangle height and adjust scale to fit if not specified
  +
* <code>-draw_rect x,y,w,h</code> : where to display the contents of screen data memory, relative to the screen rectangle
  +
* <code>-frameless</code> : frameless/borderless window mode off (0) or on (1)
 
* <code>-sound n</code> : sound volume 0..256
 
* <code>-sound n</code> : sound volume 0..256
 
* <code>-music n</code> : sound volume 0..256
 
* <code>-music n</code> : sound volume 0..256
 
* <code>-joystick n</code> : joystick controls starts at player n (0..7)
 
* <code>-joystick n</code> : joystick controls starts at player n (0..7)
 
* <code>-pixel_perfect n</code> : 1 for unfiltered screen stretching at integer scales (on by default)
 
* <code>-pixel_perfect n</code> : 1 for unfiltered screen stretching at integer scales (on by default)
  +
* <code>-preblit_scale n</code> : scale the display by n before [[Wikipedia:Bit_blit|blitting]] to screen (useful with -pixel_perfect 0)
* <code>-draw_rect x,y,w,h</code> : absolute window coordinates and size to draw pico-8's screen
 
* <code>-run filename</code> : automatically load and run a cartridge
 
 
* <code>-splore</code> : boot in splore mode
 
* <code>-splore</code> : boot in splore mode
 
* <code>-home path</code> : set the path to store config.txt and other user data files
 
* <code>-home path</code> : set the path to store config.txt and other user data files
  +
* <code>-root_path path</code> : set the path to store cartridge files
 
* <code>-desktop path</code> : set a location for screenshots and gifs to be saved
 
* <code>-desktop path</code> : set a location for screenshots and gifs to be saved
* <code>-screenshot_scale n</code> : scale of screenshots. default: 3 (368x368 pixels)
+
* <code>-screenshot_scale n</code> : scale of screenshots. default: 3 (384x384 pixels)
 
* <code>-gif_scale n</code> : scale of gif captures. default: 2 (256x256 pixels)
 
* <code>-gif_scale n</code> : scale of gif captures. default: 2 (256x256 pixels)
 
* <code>-gif_len n</code> : set the maximum gif length in seconds (1..120)
 
* <code>-gif_len n</code> : set the maximum gif length in seconds (1..120)
* <code>-gui_theme n</code> : use 1 for a higher contrast editor colour scheme
+
* <code>-gui_theme n</code> : 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.
  +
* <code>-tab_width n</code> : number of spaces in a tab in the code editor (default: 1)
 
* <code>-timeout n</code> : how many seconds to wait before downloads timeout (default: 30)
 
* <code>-timeout n</code> : how many seconds to wait before downloads timeout (default: 30)
  +
* <code>-software_blit n</code> : use software [[Wikipedia:Bit_blit|blitting]] mode off (0) or on (1)
  +
* <code>-show_fps n</code> : turn the FPS counter off (0) or on (1) (the PICO-8 application's display fps, not the running cart's fps)
  +
* <code>-foreground_sleep_ms n</code> : how many milliseconds to sleep between frames.
  +
* <code>-background_sleep_ms n</code> : how many milliseconds to sleep between frames when running in background
  +
* <code>-accept_future n</code> : use 1 to allow loading cartridges made with future versions of PICO-8
  +
* <code>-global_api</code> : prevent PICO-8 from copying all API calls to locals (useful for debugging tools that procedurally manipulate <code>_ENV</code> for hooking purposes)
   
  +
==Examples==
For example, to open Pico-8 and automatically start [[Splore]] in Mac OS X:
+
To open PICO-8 and automatically start [[Splore]] in Mac OS X:
   
<pre>
+
<pre class="p8sh">
 
/Applications/PICO-8.app/Contents/MacOS/pico8 -splore
 
/Applications/PICO-8.app/Contents/MacOS/pico8 -splore
 
</pre>
 
</pre>
   
  +
To run a specified cart full-screen on Windows:
  +
  +
<pre class="p8sh">
  +
"C:\Program Files (x86)\PICO-8\pico8.exe" -windowed 0 -run celeste.p8
  +
</pre>
 
[[Category:Reference]]
 
[[Category:Reference]]

Revision as of 20:20, 12 April 2021

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
  • -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