- Loads a region of data from the cartridge, or from another cartridge, into memory.
- destaddr
-
- The address of the first byte of the destination in memory.
- sourceaddr
-
- The address of the first byte in the cartridge data.
- len
-
- The length of the memory region to copy, as a number of bytes.
- filename
-
- If specified, the filename of a cartridge from which to read data. The default is to read from the currently loaded cartridge.
The reload() function copies data from the cartridge into a location in memory.
Cartridge data is copied to memory addresses 0x0000-0x4300 when the cartridge is loaded for the first time. After that point, the program is allowed to modify memory with memcpy(), poke(), mset(), sset(), or fset(). These operations do not modify the original cartridge data. You can use reload() to restore modified data, or otherwise access data that has been overwritten in memory.
If the optional filename argument is provided, reload() will attempt to load from that cartridge file, which does not need to be the currently loaded cartridge. You can use this to store large amounts of game data over multiple cartridges.
reload() is equivalent to reload(0, 0, 0x4300).
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.
Note: When loading data from a named file, the current cart must be saved to disk. If reload() is called with a filename but it appears to be loading from the current cart instead, try saving the current cart with a name, rebooting, and reloading the cart.
Examples
Consider a game that stores the locations of collectible treasures in the map data, and removes them from the map with mset() when the player collects them. To reload the original map data from the cartridge:
reload(0x2000, 0x2000, 0x1000)
Consider a game that uses very large maps stored in multiple cartridges. To load the map for a new area from cartridges stored in carts named "biggame_lvl1.p8", "biggame_lvl2.p8", etc.:
function load_area(lvl)
reload(0x2000, 0x2000, 0x1000, 'biggame_lvl'..lvl..'.p8')
end
load_area(2)