load filename [breadcrumb] [param]

Loads a cartridge.

The name of the cartridge file, a BBS cart ID (#1234), or @clip to load a cartridge from the system clipboard copied from the BBS.
When called from within a cart with this parameter, this adds an item to the pause menu to return to the original cart.
An arbitrary string value that can be accessed by the loaded cart using stat(6).

When you execute this system command at the Pico-8 prompt, the cart currently in memory is erased and replaced with the loaded cart.

When called as a function (load('filename')), the loaded cart completely replaces the current cart in memory and begins executing immediately.

If a "breadcrumb" string is provided, a menu option with that text is added to the pause menu of the new cart that reloads the original cart. No state is preserved when following the breadcrumb: the cart is loaded and run from the beginning. The loaded cart can access this string programmatically using stat(100). (See stat.)

If a "param" string is provided, the loaded cart can access this string value using stat(6). You can use this to pass arbitrary values to loaded carts.

Pico-8 can load cartridges in .p8 format or .p8.png format. If you specify the filename without an extension, Pico-8 assumes .p8, even if another file ending in .p8.png exists.

If the filename is #nnn where nnn is a number, it loads the cart with that ID from the Pico-8 forum. (This requires a connection to the Internet.) The ID can also be for the forum post containing the cart. Only local carts and carts loaded from the forum can load carts from the forum, not carts running in standalone players created through export.

If the filename is @clip, Pico-8 attempts to load the contents of the system clipboard as a cartridge. The value on the clipboard must be in the format used by save @clip. This is the same format provided by the "Copy" feature of the Pico-8 BBS, so you can quickly transfer cartridges from BBS posts into the Pico-8 app.

Examples Edit

At the Pico-8 prompt:

> load demos/jelpi.p8

Loading from the clipboard:

> load @clip

Loading from the forum (network connection required):

> load #1234

In source code:

-- load a cart

In source code with a breadcrumb menu item back to the original cart:

load('demos/jelpi.p8', 'back to menu')

See also Edit