Save

save [filename] 

Saves the current cartridge to a file.

filename

The name of the cartridge file. If this is "@clip", a .p8.png cartridge will be encoded into text and copied to the system clipboard instead.

If filename ends in ".p8", the file will be saved in the text-based .p8 file format. This format is the most flexible and is typically used during development, but cannot be uploaded to the BBS.

If filename ends in ".p8.png", the file will be exported to the binary .p8.png file format. This is what most developers will upload to the BBS.

If filename ends in ".p8.rom", the file will be exported to a raw 32KB binary file format.

If filename is "@clip", PICO-8 will not save to a file. Instead, it will write the cart to the system clipboard in a text-encoded version of the .p8.png file format, which may be pasted into a post on the BBS as an alternative upload method.

If filename doesn't have an extension, PICO-8 will automatically append ".p8".

Note that, when saving as a .p8.png file, PICO-8 generates a cartridge label. This label includes a screenshot image and two optional lines of text. These may be customized, as outlined below.

Setting the label image[]

To set the label image, run the cart, then press F7 or Ctrl+7 to take a screenshot. The label will use the most recent screenshot when you save the cartridge.

It's possible for this image to be something other than an in-game screenshot, but trickery is required. This might involve taking a screenshot while something other than the game has displayed an image. It's also possible to draw a label in another PICO-8 cartridge's sprite ram, and then load it into vram and take a screenshot with the following console command:

> reload(0x6000,0,8192,"mylabelcart.p8"); repeat until btn()!=0

Setting the label text[]

To set the label text, put up to two lines of comments at the top of the source code:

-- game title
-- by author name

These will be converted into the label text.

The .p8 format[]

The .p8 format is the one used during development of a cart. This format includes the source code, sprites, map, sound effects, music data, and an optional label image. It's a mostly-human-readable text file, and while the runtime still limits the token count, the source code may be as large as the 64K that PICO-8's editor allows. The BBS will not accept this format as an uploaded cartridge.

The .p8.png format, and the compressed code size limit[]

The .p8.png format is considered the production version of the cart, ready to be distributed and played. It is a standard PNG image file, displaying an image that resembles a game cartridge, with a label that has a screenshot with text below. The image's color data secretly contains the actual cart data, allowing it to be played either with the PICO-8 executable or the web player. This is the only format the web player can play, and the only format the BBS will accept when uploading a cartridge.

Because there is a small, fixed amount of space available to encode the cart in the image, PICO-8 uses compression to reduce the size of the cart's source code. The compressed code size must be under a certain limit for the save to succeed. As of 0.2.2c, this limit is 15,616 bytes. Use the info command to see how the code size compares to this limit. When saving to a .p8.png file in which the compressed size exceeds the limit, PICO-8 prints an error message.

You can save and load a cartridge whose compressed code size exceeds the limit by saving to a .p8 file instead. This allows you to save your program in progress before reducing its code size for publishing as a .p8.png, if necessary.

To set the label image, run the cart, then press F7 or Ctrl + 7 to take a screenshot. The label will use the most recent screenshot when you save the cartridge.

Saving to the system clipboard[]

You can save the contents of the cartridge to the system clipboard by specifying a filename of "@clip":

> save @clip

This format is designed to be pasted into a PICO-8 BBS message. It is delimited with [code]...[/code] and contains a hexadecimal representation of the cartridge as if it had been saved in .p8.png format. When you paste this into a BBS message and then preview or submit the post, the encoded text will be automatically converted into an uploaded cart and linked from your post. You will be given the opportunity to edit its title and choose which license you wish to release it under.

Examples[]

At the PICO-8 prompt:

> save                 -- saves to the last file loaded or saved

> save mygame          -- saves to "mygame.p8"

> save mygame.p8       -- saves to "mygame.p8"

> save mygame.p8.png   -- saves to "mygame.p8.png" in image-encoded format

> save @clip           -- saves to clipboard in text-encoded format