Loads a cartridge.
- The name of the cartridge file, a BBS cart ID (
@clipto 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
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 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). This can be used to pass arbitrary values to loaded carts.
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
If the filename is
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, 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 load('demos/jelpi.p8')
In source code with a breadcrumb menu item back to the original cart:
load('demos/jelpi.p8', 'back to menu')