Cartridge Data

Using CARTDATA(), DSET(), AND DGET(), 64 numbers (256 bytes) of persistent data can be stored on the user's PICO-8 that persists after the cart is unloaded or PICO-8 is shutdown. This can be used as a lightweight way to store things like high scores or to save player progress. It can also be used to share data across cartridges / cartridge versions.

If more than 256 bytes is needed, it is also possible to write directly to the cartridge using CSTORE(). The disadvantage is that the data is tied to that particular version of the cartridge. e.g. if a game is updated, players will lose their savegames. Also, some space in the data sections of the cartridge need to be left available to use as storage.

Another alternative is to write directly to a second cartridge by specifying a fourth parameter to CSTORE(). This requires a cart swap (which in reality only means the user needs to watch a spinny cart animation for 1 second).

CSTORE(0,0,0X2000, "SPRITE SHEET.P8")
-- LATER, RESTORE THE SAVED DATA:
RELOAD(0,0,0X2000, "SPRITE SHEET.P8")

CARTDATA(ID)

Opens a permanent data storage slot indexed by ID that can be used to store and retrieve up to 256 bytes (64 numbers) worth of data using DSET() and DGET().

CARTDATA("ZEP_DARK_FOREST")
DSET(0, SCORE)

ID is a string up to 64 characters long, and should be unusual enough that other cartridges do not accidentally use the same id. Legal characters are a…z, 0…9 and underscore (_)

Returns true if data was loaded, otherwise false.

CARTDATA can be called once per cartridge execution, and so only a single data slot can be used.

Once a cartdata ID has been set, the area of memory 0X5E00…0X5EFF is mapped to permanent storage, and can either be accessed directly or via DGET()/DSET().

There is no need to flush written data -- it is automatically saved to permanent storage even if modified by directly POKE() 'ing 0X5E00…0X5EFF.

DGET(INDEX)

Get the number stored at INDEX (0…63)
Use this only after you have called CARTDATA()

DSET(INDEX, VALUE)

Set the number stored at index (0…63)
Use this only after you have called CARTDATA()