Standardize and document way to distribute games & first class support

This is more of a general feature request, and not specifically about the SDK. I didn't know where else to file it.

The SDK docs and help pages refer to the "game" unit in different ways, and there's no specified recommended way for developers to bundle and distribute games. Please provide one.

The following is a list of several conflicting behaviors and documentation I found, followed by how I naturally "expect" things to work (whether or not it's feasible or not is up to you - this isn't a criticism. I'm also assuming you probably thought about some of this stuff already)

  1. The Compiling a project section of the SDK refers to "pdx" being the output folder, but doesn't explicitly say that this is what you should distribute to players. On itch, some developers are distributing "" files, and some just a zip file which contains a .pdx directory, along with maybe other materials. Which is preferred?
  2. The dev page has the FAQ "How do I distribute my Playdate game?" but doesn't really address file formats. It should.
  3. The sideloading guide says to "Drag or select the .pdx game file (or zipped .pdx) to upload it.". Problem is, the "pdx game file" is not really a file. It's a directory (or "folder", depending on parlance). It's my understanding that it only kinda looks like a file in Mac, which not everyone uses.
  4. When you download a game from Pulp, the file is named like -- why not include .pdx in the file name?
  5. When running the simualtor with a file as the first argument it gives the cryptic error " "(null)" was built with an old version of the SDK." (another thread about this). It should at least detect it's not pointed at a folder. (Opened a separate bug about this). It would be better if it could "read" zip files without complaint.

I think it would be really helpful if files were "first-class" citizens, and were supported by the simulator and playdate itself -- is this feature missing as a performance tradeoff? Sideloading through the website supports "zipped pdx files", but sideloading over USB doesn't. It means that players who download "" files via itch have to go through the technical step of unzipping the file.

I think it's much more natural for players to think of "games" as single files, rather than directories with "file extensions" in their name, which is a very foreign concept (at least in the windows and linux world)


I can answer some of these right here.

The canonical form of an installable Playdate game is the .pdx folder, which works mostly like a single file on Macs that have our SDK installed — you can double-click a .pdx to run it in the Simulator, for example.

You can also drag a .pdx folder onto our sideloading UI if your browser supports this (Safari for Mac does; not sure about other platforms). But a zipped .pdx folder is also accepted there. Since it's difficult to send folders around the internet intact, a zipped .pdx is the generally recommended format for distribution. I'll see if we can clarify that in the docs.

Pulp using .zip instead of was most likely a stylistic choice. It's also possible that downloaded games might (or might one day) contain other files alongside the .pdx, which would make the double extension inappropriate. But also, I don't think MacOS can be taught to treat as a distinct file type from .zip, which is probably why we didn't try to solve this differently.

#5 — yeah, this is something we should improve. I'll file it as a suggestion, thanks!

1 Like


You should not assume everyone is on MacOS.
Majority of Windows users in the wild, an not negligable part of Linux users.

As a Windows and linux user, i didn't know MacOS take car of extensions in folder name. A folder is a folder. Extension and mimetype is used to know wich application open wich kind of file.

Maybe we can keep executable folder game with .pdx
And for game distributed on internet create a New extension .pdz or .pdxz.
And add support on sideloading website or this extension, Pulp export .pdz, and put install mecanism when put a pdz in playdate over USB


Best regards