- Store a region of memory in the cartridge file, or another cartridge file.
- destaddr
-
- The address of the first byte of the destination in the cartridge.
- sourceaddr
-
- The address of the first byte in memory to copy.
- len
-
- The length of the memory region to copy, as a number of bytes.
- filename
-
- If specified, the filename of a cartridge to which data is written. The default is to write to the currently loaded cartridge.
The cstore() function copies a region of memory to the cartridge, modifying the cartridge file.
This is useful for building PICO-8 development tools inside PICO-8, such as a specialized graphics editor that saves sprite or map data to another cartridge.
Data can be loaded from an arbitrary cartridge file using the reload() function.
If a filename is provided and there exists a cartridge with that name, the data is patched into the appropriate location. If there is no file with the given name, a new empty cartridge is created with the data patched in. Unlike reload(), the filename must end in .p8 or .p8.png if the intended cartridge file has that extension. (The filename extension is not inferred from existing files.)
The memory layout for cartridge data is identical to PICO-8 memory for the address region 0x0000-0x4300. See Memory for an explanation of memory and cartridge data, and for a description of the memory layout.
Caution: The cstore() function modifies the cartridge file. This operation cannot be undone, so it might be wise to keep a copy of the original cartridge files, and test to make sure data is written to the correct file and memory location.
BBS Behavior[]
This function is supported on the BBS:
- If called without the filename argument, it will modify the cartridge in the user's local storage - meaning it will affect the data that'll get loaded the next time the user will run your BBS cart.
- If called with the filename argument, it will write a cartridge with this name to the user's local storage. (Readable by reload() from any BBS cart)
Note that:
- When uploading an updated version of a previously-uploaded BBS cart, any cstore() calls made without the filename argument in the previous versions will not affect the new version.
- It is not possible to write to any other BBS cart with the filename argument.
Examples[]
Consider a utility cartridge that generates map data and saves it to a different cartridge:
-- generate some map data
generate_map()
-- save the map data to a separate cartridge
cstore(0x2000, 0x2000, 0x1000, 'mygame.p8')