I was looking into methods for extending the spritesheet memory of a cartridge, but the only result I could find on google (after an admittedly short search) was a post that was slightly inefficient when it loaded the spritesheet into memory, making it only suitable for use in fullscreen graphics like a title screen. This was noted in the post, but I thought that I could make some improvements.
Limitations
This code is very small when inserted into the cart, other than the actual spritesheet data. The current data is stored in a completely uncompressed binary string, which in the worst case can balloon up to 16-20k characters.
(NOTE: This is only when storing a completely black spritesheet, which should ideally be never. If your spritesheet has large portions of completely black (color 0) space, try replacing it with some other color you're not using, or using palette swapping.) The average spritesheet should be able to be stored in 8-10k characters.
Currently my implementation only supports replacing the entire spritesheet at once, though this could be easily improved to allow copying 64x64, 32x32, 16x16, and 8x8 chunks individually.
Possible future improvements:
As mentioned earlier, this is severely limited by a lack of compression. It would be relatively easy to implement an RLE compression for the strings, then decompress them at runtime. Alternatively, it would also be easy implement PX9 compression for the spritesheet before it is loaded into a string, then decompress it at runtime.
Usage:
Export:
This cart includes all of the functions to export a spritesheet from a cart. To use: Load cart in an offline instance of PICO-8, uncomment the line "reload(0,0,"mycart.p8"), and replace "mycart.p8" with the name of the cart you wish to export the spritesheet from. Alternately, draw a new spritesheet into this cartridge or use PICO-8's drag and drop feature to import an image. Run the cart, which will save the string to your clipboard.
Usage in your own carts:
^^Example^^: look at code for sample importing of a string.
Once you have your data saved into the clipboard, you can put it into your cartridge.
When you are going to paste this string into your own game, make sure to press CTRL-P to enable puny font. This method will not work properly without doing this.
Paste the clipboard data into a new string in your game.
Now, you're going to need to add these two methods to your game: (146 tokens)
function spritesheet_to_table()
local tbl={}
for y=0,127 do
for x=0,15 do
tbl[(y<<4)+x]=$((y<<6)+(x<<2))
end
end
return tbl
end
function string_to_table(str)
local tbl={}
for i=0,8191,4 do
local al,ah,eal,eah=
(ord(str,i+1)),
(ord(str,i+2)),
(ord(str,i+3)),
(ord(str,i+4))
tbl[i\4]=
al|(ah<<>8)|
(eal<<>16)|(eah<<>24)
end
return tbl
end
function table_to_spritesheet(tbl)
for y=0,127 do
for x=0,15 do
poke4((y<<6)+(x<<2),
tbl[(y<<4)+x])
end
end
end |
The first method should be called in your _init function like this:
('original_spritesheet_table' is the data for your base cartridge spritesheet, so that it can be loaded efficiently later.
'your_spritesheet_table' will be initialized here, replace the name with what you want to call it later. 'your_str' is what you named the string that you pasted into.)
original_spritesheet_table=spritesheet_to_table() your_spritesheet_table=string_to_table(your_str) |
This will load the string into Lua memory, which should come at almost no cost to your final product.
Now, whenever you want to switch to your other spritesheet, simply call
table_to_spritesheet(your_spritesheet_table) |
To restore the original spritesheet, you need to call
table_to_spritesheet(original_spritesheet_table) |
This function only takes 7% of the CPU time on a single frame (at 30fps), but since it needs to be called twice if you're going to use both spritesheets every frame, plan to have it use 15% of the CPU time.
NOTE: If you don't care about performance, but are low on tokens, you can remove the entire 'spritesheet_to_table()' function and instead use reload(0,0,0x1fff) to reset the spritesheet. However, this is vastly more inefficient, taking 20% of the CPU time of a frame at 30fps.
Explanation
These methods are not new, I just couldn't find any documentation of them for people to easily make use of them on the BBS.
This method makes use of the fact that a single number value in a Lua table is 4 bytes long, so you can easily make use of poke4 to quickly load a large amount of data into memory. This method first uses peek4 every 4 bytes in the spritesheet, loading the values directly into a table with no fiddling around with byte ordering. This allows it to entirely ignore the endianness of the functions. When you want to load a table back into memory, it's easy enough to just loop through the table again calling poke4 with each value of the table to quickly load 8px of the spritesheet in a single function call.
The most confusing part of this method, and the most easily breakable part, is the actual saving of this data. When loading it into a string, it is most efficient to store it in plaintext binary form. This storage is detailed by zep in this post:
https://www.lexaloffle.com/bbs/?tid=38692
However, a single character can only store a single byte. So whenever you save it as a string, and load it from a string, you need to decompose and recompose the 4 bytes of the number into 4 individual characters. This is only an intermediary form, so other than cartridge size, how this is stored is almost entirely independent of final performance. This means that in future, this could be optimized using methods like RLE or PX9 without affecting the final performance of the functions at all, as long as the decompression step comes before loading the data into the table.
Possible optimizations:
Currently the most of the saving/loading functions use nested for loops, but this could be simplified relatively easily to use a single larger for loop for more efficiency.
There may be other optimizations I missed/didn't implement, feel free to suggest them/show code for them if you find any!
[Please log in to post a comment]
