Pulp games can do a lot, but they don’t have access to every feature of the Playdate SDK. Pulp is intended to be a simple, friendly editor, and we try to keep it from becoming overwhelming. However, if you’re feeling adventurous, you can modify your Pulp-created game to add some fun effects to it.
NOTE: modifying the game bundle, as described below, is an advanced move; please proceed carefully. This article discusses tweaks to your Pulp game’s bundle. It’s possible to create a corrupted game this way, one which won’t run at all. While this won’t modify your Pulp game on the server, you should keep a backup of any local game files you don’t want to lose.
What can I do by editing my Pulp game?
You’ll be able to add the following cool effects to your game:
- 400 × 240 px launcher card (Pulp produces 200 × 120 images, scaled up)
- Launcher card that animates when selected
- Launcher card that animates when the game is launched
- Launch sound
- Loading image
- List view icon
- “Wrapping paper” image shown on newly-downloaded games
- Content warning
If that sounds interesting, read on!
Using the Playdate SDK
To make most of these metadata modifications, you’ll need the Playdate SDK. If you haven’t installed the Playdate SDK before, start here: play.date/dev. The SDK—available for macOS, Windows, and Linux—comes with an installer, and it includes everything you need. For help with general SDK setup, see these tutorials.
Editing your Pulp game’s .pdx bundle
The general approach for this metadata tweak is:
- Create a blank, placeholder Playdate game using the SDK
- Put your launcher images and sound into it
- Build the game to produce compiled .pdi (image) and .pda (audio) files
- Download a .pdx bundle of your Pulp game
- Copy the .pdi and .pda files to the .pdx bundle
pdxinfoinside your Pulp game
Let’s take it step by step. From here on, we’ll refer to “the Pulp game” (the downloaded .pdx of your game), and “the SDK game” (the blank, temporary game you’ll make using the SDK).
① Create a blank Playdate game using the SDK
Once you’ve got the Playdate SDK set up, create a new game project. At a minimum, this should include a file called
main.lua; see our documentation on (structuring your game project)[https://sdk.play.date/inside-playdate/#_structuring_your_project]. That
main.lua file won’t play a big role in this metadata-editing process. You can just put this code in it:
function playdate.update() end
Then ignore it for the rest of this process.
If you’ve set up the SDK to build and run games, try doing it now. The Simulator should launch with your SDK game—it won’t do much, but it shouldn’t report any errors, either. Welcome to Playdate SDK development!
② Put your launcher files into the SDK game
Once you’ve created your files according to our specifications, place them in the project folder. You might end up with something like this:
/[myProjectName] /source main.lua card.png /card-highlighted 1.png 2.png 3.png card-pressed.png icon.png /icon-highlighted 1.png 2.png 3.png icon-pressed.png launch.wav wrapping-pattern.png
③ Build the game to produce compiled files
A built, compiled .pdx game file is essentially a folder of game assets: code, images, audio, data files. For instance, we convert all images to our .pdi format, optimized for Playdate—you won’t be able to drop .GIF or PNG files into a compiled game. Editing compiled .pdx files of your Pulp game means you’ll also need to put compiled files in that bundle. In this step, the SDK does the conversion.
When you have the new .pdx file, you can inspect it by opening it. On Windows and Linux, you can just open the .pdx folder. On macOS, right-click it and choose Show Package Contents. Notice the compiled .pdi and .pda files.
(Note that these files aren’t directly editable from this point on; you can’t open a .pdi image in a graphics editor.)
④ Download a .pdx bundle of your Pulp game
When you export your Pulp game by downloading a .pdx file, what you get is, in effect, the same kind of game that the Playdate SDK produces. Behind the scenes, our server compiles it into a similar bundle of game files. If you inspect it, you should see something like this:
/[myPulpGame.pdx] card.pdi chars.pdt data.json.zip data.pdz frames.pdt main.pdz pdxinfo pipe.pdt
It might be good to make a local backup of this .pdx file before you proceed. Remember, the version on the Pulp website won’t be affected by anything we do from here on.
data.json.zip file contains importable Pulp code of your game; you could use this to load a game back into Pulp. If you don’t want to distribute this with your game, remove it from the .pdx bundle.
⑤ Copy the compiled files to the .pdx bundle
Take the compiled .pdi and .pda files from your SDK game and copy them to the .pdx bundle of your Pulp game. They’ll now be part of the game, and you’ll be able to reference them in the
pdxinfo file below.
⑥ Editing the pdxinfo file
Our SDK documentation discusses the pdxinfo file in detail. Basically, it’s a list of properties describing your game, and setting some options for it.
Some of these are already editable in Pulp, in the Game tab: name, author, version, and build number. Others aren’t available to Pulp, because it would be rather complicated to create and edit them.
It’s best to start with the existing
pdxinfo file already in your Pulp game and edit it, instead of creating a brand new one.
Here’s an example of a finished
pdxinfo Pulp file edited using the above process:
name=Hidey Spot author=Neven Mrgan description=A tiny Christmas game made with Pulp bundleID=pulp.nevenmrgan.hideyspot version=1.0.9 buildNumber=11009 imagePath=card pdxversion=11000 buildtime=740676214
Wrapping it up
At this point, build your game to ensure that it still compiles fine.
If you’d like to test the Launcher assets, you can see them in the Simulator by copying the game to the Simulator’s virtual “disk”. This should be located at
[your SDK install path]PlaydateSDK/Disk/Games/User. Any games placed here will show up on the Home screen.
If everything looks good, congratulations! You just gave your Pulp game an upgrade.
What about game updates?
Note that this whole process should be done at the end of your Pulp development, when the game is more or less finished. You won’t be able to load the edited game back in Pulp.
What happens when you update your game in Pulp? You’ll need to repeat the above process, starting with step 4. As long as you keep your blank SDK game around, you’ll be able to reuse those compiled files. Remember to edit the
pdxinfo file again, as Pulp will generate a new one.
If you have questions about this tutorial, let us know on the Developer Forum!