Editing Pulp game metadata using the Playdate SDK
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. 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
- Edit
pdxinfo
inside 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. That main.lua
file won’t play a big role in this metadata-editing process. 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.
NOTE: The 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!