PICO-8 Wiki
load filename [breadcrumb] [param]
Loads a cartridge.
Either the name of the cartridge file, a BBS cart ID in the form "#mycartid123", 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 this system command is executed at the PICO-8 prompt, the cart currently in memory is erased and replaced with the loaded cart.

When called from within a running cart, e.g. load("filename"), the loaded cart completely replaces the current cart in memory and begins executing immediately.

If the 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 the param string is provided, the loaded cart can access this string value using stat(6). This can be used to pass arbitrary values to loaded carts. As of v0.2.0i, the maximal length of the string is 1024 (longer strings are truncated).

Data can also be passed to and from loaded carts via the general use memory region.

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

If filename is formatted like "#mycartid123", 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 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, meaning cartridges can quickly be transferred from BBS posts into the PICO-8 app.


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[]