PICO-8 Wiki
(→‎Command-line flags: more missing flags, taken from the current manual)
m (formatting)
Tag: Source edit
(9 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
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 [[Printh|<code>printh()</code>]] for information about how to locate the PICO-8 command for each operating system.
+
See the entry on <code>[[Printh|printh()]]</code> for information about how to locate the PICO-8 command for each operating system.
   
 
==Command-line flags==
 
==Command-line flags==
Line 14: Line 14:
 
* When in windowed mode, the ''screen rectangle'' refers to the inset rectangle where the virtual PICO-8 screen is shown, including any padding.
 
* 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 "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 video memory.
+
* 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.
   
 
These are the flags:
 
These are the flags:
   
<code>pico8 <nowiki>[switches] [filename.p8]</nowiki></code>
+
<code>pico8 <nowiki>[flags] [filename.p8]</nowiki></code>
   
 
* <code>-run filename</code> : automatically load and run a cartridge
 
* <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>-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 [[Export]])
+
* <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>-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)
Line 29: Line 29:
 
* <code>-width n</code> : set the screen rectangle width and adjust scale to fit if not specified
 
* <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>-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 video memory, relative to the screen rectangle
+
* <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 blitting to screen (useful with -pixel_perfect 0)
+
* <code>-preblit_scale n</code> : scale the display by n before [[Wikipedia:Bit_blit|blitting]] to screen (useful with -pixel_perfect 0)
 
* <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
Line 45: Line 46:
 
* <code>-tab_width n</code> : number of spaces in a tab in the code editor (default: 1)
 
* <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 blitting mode off (0) or on (1)
+
* <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>-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>-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>-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>-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>
  +
  +
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>
 
</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