Cstore

cstore( destaddr, sourceaddr, len, [filename] )

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.

You can load data 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.)

This feature only works in the PICO-8 app, and does not work in the web player or Forum.

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. Be sure to keep a copy of your original cartridge files, and test to make sure data is written to the correct file and memory location.

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')

See also

• Memory
• peek()
• poke()
• memcpy()
• reload()
• memset()