Bypassing the Android File Limit

The week between the patron bug testing release and the public release of a new version of Lab Rats 2 is normally spent bug fixing, and any extra time is either put into writing small pieces of new content or prototyping some future feature. This week I set my sights on a particularly large and onerous bug: the android file limit. I've talked about it before, but the quick version is this: Android does not provide support for folders containing more than 64k files, and the Ren'py android build process automatically clumps all of the game images together. This put a hard cap on the number of images that could be contained in LR2, a cap which we hit a couple of versions ago with the addition of new facial designs. Since then the android version has had a narrower selection of faces, and I had put a pause on adding new clothing items.

My initial hopes, and efforts to resolve this problem, were centered around finding some way to have Ren'py package the android build differently. On PC Ren'py provides the option of grouping images into archive folders, which are treated by the operating system as a single file (this is especially noticeable when you unzip LR2 after downloading; thousands of tiny images take much longer than a single archive file). I wasn't able to find any way to emulate that sort of behavior on Android, so a different approach would be needed.

The solution has been to pre-divide and package the clothing images into .zip files based on the character position those images are for, effectively creating my own archive files that I can be sure the android process will respect. The uncertain part was accessing those .zip files to retrieve the needed item images, while maintaining both performance as well as compatibility with all of the animation and region masking that had already been implemented.

The whole process was made easier by a lucky breakthrough. Inside of Ren'py's code there is a displayable class, ZipFileImage, that does exactly what I needed it to do: look through a given .zip, pull out a particular file, and treat it like a normal image. I suspect this is used internally for the official archive files, but it is otherwise completely undocumented. My initial testing showed perfect results, so I got to work changing over the core bits of the LR2 display code.

After an evening of work I have everything functioning as expected. My benchmark speeds aren't showing any slowdown between the old directly referenced images and the new zip file method. Animations, clothing colouring, and clothing masking are all working as-is, and I took the opportunity while I was looking at the code to clean up a couple of sections that had been neglected. This means I can start adding new items into LR2 in future updates, which I am looking forward to!

The only problem with the change at the moment is that I have to manually package all of the zip files instead of letting Ren'py handle it when building a new version. This is something I can and will automate in the near future.