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. 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
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)[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.

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!