Optimizing Larger Pulp Projects - ART&.. More v1.6 post-mortem

ART&.. More v1.60 is out now on Catalog and on itch.io, but getting it across the finish line (stable on device) was a learning process that I'd like to share for folks looking to push Pulp to its limits.

TLDR It is possible to make a game too big in Pulp to launch on hardware, but this can be mitigated.

When I say stable, I mean in particular able to launch and load consistently without crashing on hardware. The in-game code runs pretty reliably at 18-20 fps excepting when entering a room with a large work of art in it. (The tiling code for artwork runs a while loop on the enter event and depending on the size of the piece can dip the framerate for a quarter/half second. That code is described in my post here: Pulp How-To: Drawing Frames from a Single Tile - Playdate Developer Forum )

As one of the larger Pulp titles that I'm aware of, I built the game with one particular limitation in mind - the frametable limit I encountered when I originally developed ART7 (again see previous post Pulp not resetting Frame count after Exceeding 'frames-table-8-8.png' limit - Playdate Developer Forum). This limits the literal amount of frames in the game to 32,768. Artwork takes somewhere between 32-375 frames per piece so there is an upward cap on what I can do within the game in order to get Pulp to build the PDX.

When I started the whole ART gallery idea, I wanted to update it all in one file forever, but with Pulp that's just not feasible. So each game gets its own PDX and now I have a series of free galleries coming out that will have their own PDX as well!

What I didn't anticipate for this latest update was a soft-cap in terms of complexity of the game itself. While I was able to keep my frames just under the 32k hard limit (artwork, character sprites, environment tiles etc), the game environment itself is BIG and every piece of art is displayed in a first-person view in its own room. So considering the gallery rooms, the exteriors/secret areas, the arcade game rooms, all of the sea creatures and the individual rooms for every piece of ART, I have at last count 252 rooms that comprise the whole of ART&.. More. That's a lot!

Nearly every single room contains custom code and while my game and player scripts are much tighter this time vs previous games due to lessons learned in the development of CHEK, I still have a good amount of code in those scripts to handle some global behavior.

ART& v1.06 was the previous version of the game and launched stably on release, but when I did the initial production and upgrade to v1.5 I began experiencing crashing issues. The game ran fine in browser and on Simulator, but as we all know, these are very different hardware than the Playdate itself. I plugged the system into my laptop and ran it with the Simulator's console open to see what was going on.

Pulp can be a little frustrating to debug. If it runs, it should just.. run. Otherwise, the launch process is a bit opaque. I had logs for tons of different events in the game player and room scripts not to mention sprites but I was getting a lot of this:

Sim Console

Watchdog Reset

The Watchdog Reset kept kicking in and crashing on hardware. This is a legitimate function of the design of Pulp. If a single frame is taking longer than 10 seconds to run, the system assumes there's something wrong and resets. This is a known safeguard.

What I was Not expecting was for the 1st Frame of ART& to load for a bit more than that and trigger it. Compounding the issue - initially, triggering it was inconsistent. The game would load in some cases and crash on it in others.

I found that depending on how I was handling save data could have a minor effect or whether save data existed at all.

Through logs and examining the order of triggered functions in game and player I was able to narrow down what was taking so long and it pointed to my load and enter functions in both player and game scripts. Because the ART series games have such large environments, your lastroom and x/y position is saved so you can come back where you left off. I consider this a pretty core function of the games, so I couldn't just axe it, but that is primarily what those functions dealt with.

Talking to @orkn who has helped SO MUCH and is a Pulp Wizard (and contributed the equivalently wizardly TILE HILL to the arcade in ART&), we determined a way to bring down startup time was essentially to jettison the entire load and enter functions into their own refactored class tiles and drop the player into a splashscreen at the beginning.

Enter splashscreen

With this method, I was able to avoid running a ton of initial code on launch and could trigger it when you leave this room - things like configs and the aforementioned lastroom and coordinate code.

I rolled back to an earlier stable update, implemented this method and then slooooowly rebuilt all the additions in v1.5 to creep back up to content complete and make sure the game was booting on system with/without save data - v1.6!

This was later confirmed by @arisa in part as she was able to get me a little more detail on what Pulp is doing on launch. Namely, Playdate builds a Pulp game on each boot, just like it does on the web - it has to load in the code and iterate over every room load and enter functions. To make this update work I was shaving miliseconds off the load frame with the above method, but adding in more tiles and code was creeping back up to the watchdog reset limit.

I went so far as to cull even bulky, unneeded comments, trimmed out a bunch of unused prototype rooms and even axed some signage art (that I didn't much care for). I was nearing the point of cutting some of my own actual pieces of art from the game in order to make this work when I was able to get it to launch stably averaging about 9.5-9.7 seconds :playdate_cry_laugh:

That's cutting it REAL CLOSE but in testing has proved reliable.

To wrap up, the changes to v1.6
-fixed a bug and added a system to Fishing to make it easier to fill out the Xaniaquarium
-fixed a bug with the Memory Portal
-added Purrrgatory bonus mode in HEAVEN
-reconfigured Lazer Shark to extend playtime if you kill a certain number of fish, scaling
-added SLOTMACHINEGUN as a wholly new arcade game to the PROTOCADE
--The bulk of this code is probably what did me in and caused all of this. It added 3 rooms, 25+ new tiles with a ton of custom code.

I would LOVE to hear from anyone else with more info on ways to optimize Pulp games. And I'm not sure if we have a guide for using sprites as class tiles on here, but I'm sure it's been mentioned and has been an absolutely key tech for building these larger projects and keeping the dev process sane.

If I'm able to keep the code minimal enough, I miiiiight be able to add a TV/idle mode to the game. But right now it's really pushing it on launch so this is a big Maybe. Anyways, thanks for reading and if you haven't taken a stroll through the gallery yet, go get it! or at least grab a free ARTtOO from the itch page :playdate_shocked:


Great writeup, thanks for sharing! Seems like you really got into the weeds and were pushing right up against the edges of Pulp, but the end result speaks for itself! Glad to have been some small help in you getting there :slightly_smiling_face: