Exporters & Importers

Exporters / Importers

The EXPORT command can be used to generate png, wav files and stand-alone html and native binary cartridge applications. The output format is inferred from the filename extension (e.g. .png).

You are free to distribute and use exported cartridges and data as you please, provided that you have permission from the cartridge author and contributors.

Sprite Sheet / Label (.png)

> IMPORT BLAH.PNG   -- EXPECTS 128X128 PNG AND COLOUR-FITS TO THE PICO-8 PALETTE
> EXPORT BLAH.PNG   -- USE THE "FOLDER" COMMAND TO LOCATE THE EXPORTED PNG

When importing, -x and -y switches can be used to specify the target location in pixels: -s can 
be used to shrink the image (3 means scale from 384x384 -> 128x128)

> IMPORT BLAH.PNG -X 16 -Y 16 -S 3

Use the -l switch with IMPORT and EXPORT to instead read and write from the cartridge's label:

> IMPORT -L BLAH.PNG

When importing spritesheets or labels, the palette is colour-fitted to the current draw state 
palette.

SFX and Music (.wav)

To export music from the current pattern (when editor mode is MUSIC), or the current SFX:

> EXPORT FOO.WAV  

To export all SFXs as foo0.wav, foo1.wav .. foo63.wav:

> EXPORT FOO%D.WAV

MAP and CODE

A cartridges map or source code can be exported as a single image named .map.png or .lua.png:

> EXPORT FOO.MAP.PNG
> EXPORT FOO.LUA.PNG 

Map images are 1024x512 (128x32 8x8 sprites). Lua images are sized to fit, but each line is 
fixed (and cropped) at 192 pixels wide.

Cartridges (.p8, .p8.png, .p8.rom)

Using EXPORT to save a cartridge is the same as using SAVE, but without changing the current 
working cartridge. This can be useful for example, to save a copy in .p8.png format for 
distribution without accidentally continuing to make changes to that file instead of the 
original .p8 file.

EXPORT can also be used to perform cartridge file format conversions from commandline. For 
example, from a Linux shell:

> pico8 foo.p8 -export foo.p8.png

Web Applications (.html)

To generate a stand-alone html player (mygame.html, mygame.js):

> EXPORT MYGAME.HTML

Or just the .js file:

> EXPORT MYGAME.JS

Use -f to write the files to a folder called mygame_html, using index.html instead of 
mygame.html

> EXPORT -F MYGAME.HTML

Optionally provide a custom html template with the -p switch:

> EXPORT MYGAME.HTML -P ONE_BUTTON

This will use the file {application data}/pico-8/plates/one_button.html as the html shell,  
replacing a special string "##js_file##" (without quotes), with the .js filename, and 
optionally replacing the string "##label_file##" with the cart's label image as a data url.

Use -w to export as .wasm + .js:

> EXPORT -W MYGAME.HTML

When exported as .wasm, the page needs to be served by a webserver, rather than just opening it 
directly from the local file system in a browser. For most purposes, the default .js export is 
fine, but .wasm is slightly smaller and faster.

Binary Applications (.bin)

To generate stand-alone executables for Windows, Linux (64-bit), Mac and Raspberry Pi:

> EXPORT MYGAME.BIN

By default, the cartridge label is used as an icon with no transparency.  To specify an icon 
from the sprite sheet, use -i and optionally -s and/or -c  to control the size and 
transparency.

    -I N  Icon index N with a default transparent colour of 0 (black).
    -S N  Size NxN sprites. Size 3 would be produce a 24x24 icon.
    -C N  Treat colour N as transparent. Use 16 for no transparency.

For example, to use a 2x2 sprite starting at index 32 in the sprite sheet,  using colour 12 as 
transparent:

    > EXPORT -I 32 -S 2 -C 12 MYGAME.BIN

To include an extra file in the output folders and archives, use the -E switch:

    > EXPORT -E README.TXT MYGAME.BIN 

Windows file systems do not support the file metadata needed to create a Linux or Mac 
executable. PICO-8 works around this by exporting zip files in a way that preserves the file 
attributes. It is therefore recommended that you distribute the outputted zip files as-is to 
ensure users on other operating systems can run them. Otherwise, a Linux user who then 
downloads the binaries may need to "chmod +x mygame"  the file to run it, and Mac user would 
need to "chmod +x mygame.app/Contents/MacOS/mygame"

Uploading to itch.io

If you would like to upload your exported cartridge to itch.io as playable html:

    1. From inside PICO-8: EXPORT -F MYGAME.HTML
    2. Create a new project from your itch dashboard.
    3. Zip up the folder and upload it (set "This file will be played in the browser")
    4. Embed in page, with a size of 750px x 680px.
    5. Set "Mobile Friendly" on (default orientation) and "Automatically start on page load" on.
        // no need for the fullscreen button as the default PICO-8 template has its own.
    6. Set the background (BG2) to something dark (e.g. #232323) and the text to something light (#cccccc)

Exporting Multiple Cartridges

Up to 32 cartridges can be bundled together by passing them to EXPORT, when generating 
stand-alone html or native binary players.

> EXPORT MYGAME.HTML DAT1.P8 DAT2.P8 GAME2.P8

During runtime, the extra carts can be accessed as if they were local files:

RELOAD(0,0,0X2000, "DAT1.P8") -- LOAD SPRITESHEET FROM DAT1.P8
LOAD("GAME2.P8")              -- LOAD AND RUN ANOTHER CART

Exported cartridges are unable to load and run BBS cartridges e.g. via LOAD("#FOO")

Running EXPORT from the host operating system

Use the -export switch when launching PICO-8 to run the exporter in headless mode. File paths 
are relative to the current directory rather than the PICO-8 file system.

Parameters to the EXPORT command are passed along as a single (lowercase) string:

pico8 mygame.p8 -export "-i 32 -s 2 -c 12 mygame.bin dat0.p8 dat1.p8"