Getting your games ready for Playdate OS 2.0

Follow these steps! (And be sure to note the items marked IMPORTANT.)

① Install the Playdate OS 2.0 SDK beta

Download it from here. Note: with this beta SDK release, you will not be able to install the OS onto your Playdate device, but you will be able to run OS 2.0 on the Simulator.

② If your game has C code, rebuild it

Mid-way through Group 4 delivery of Playdates, we switched to Rev B hardware. IMPORTANT: If your game contains code written in C, you will need to rebuild your game with the 2.0 SDK to make it compatible with Rev B Playdates. (If you do not, upon launch of your game, users will see a dialog asking them to run Game Update or contact the game’s developer.) In addition, click here if you use your own custom linker or build scripts.

If your game is written in Pulp or Lua, it does not need to be re-built: your existing .pdx will run on both Rev A and Rev B Playdates.

③ Create a List View icon for your game

To make life easier for users with many Playdate games, OS 2.0 introduces a new Launcher List View mode. This mode defines a new icon format for your game, in addition to the existing card format.

Specifying custom List View icons

Add one or more of the following files into the folder specified by the imagePath parameter in your pdxinfo file:

icon.png

The game’s icon, visible in the launcher when the view mode is set to “list”. Must be exactly 32 x 32 pixels. Note: if you do not specify a custom List View icon, Playdate will display a generic icon next to your game’s title when in List View.

icon-pressed.png

Displayed on an A button down event in the Launcher when the view mode is set to “list”. Must be exactly 32 x 32 pixels.

icon-highlighted/

A folder of images that will be played in in a loop when your game is selected in the launcher when the view mode is set to “list”. Images should be named 1.png, 2.png, etc. Each image must be exactly 32 x 32 pixels. This folder can optionally contain a text file called animation.txt for finer-grained control over the animation. This uses the same format as described for card-highlighted. See Inside Playdate for details.

Testing your icon

If you’ve installed the 2.0 SDK, you can use the Simulator to preview your icon in the Launcher:

1. Copy your game .pdx into the [PlaydateSDK]/Disk/Games/ folder.
2. Launch (or re-launch) the Simulator.
3. Choose View As: list via the Simulator’s Menu button.

④ Test your game on OS 2.0

We’ve tried to minimize the number of changes to OS 2.0 (besides the features mentioned above), so ideally your game will run the same as it always has. But it’s always a good idea to try it out and make sure.

⑤ Publish your 2.0 build

IMPORTANT: Please wait to distribute the 2.0 build of your game until OS 2.0 goes final and is made available to everyone. Playdates on OS 1.x will not be able to launch your 2.0 build, but will display a dialog asking the user to upgrade their Playdate’s OS. If OS 2.0 is not available to the public, the user will not be able to run your game.

Any questions?

Please contact us via Dev Forum.

Appendix: Compilation requirements

This is all taken care of in the 2.0+ SDK, but for anyone creating their own linker and build scripts, please read on.

Build Requirements

In order to generate the pdex.bin binary, pdc needs to know about relocations that the loader needs to perform. We have chosen to modify our flags to add the following:

CPFLAGS += -mword-relocations -fno-common
LDFLAGS += -nostartfiles -Wl,--emit-relocs

Your build also now needs to output a pdex.elf into the Source/ directory that pdc is to be run on. When pdc is run, it will process pdex.elf and generate a pdex.bin in the output .pdx bundle.

Linker Requirements

The linker file must specify:

1. The game’s entry point.
2. Sections without a specified load address.

Here is an abridged example:

ENTRY(eventHandlerShim)
GROUP(libgcc.a libc.a libm.a)

SECTIONS
{
    .text :
    {
        *(.text)
        *(.text.*)
        *(.rodata*)
        /* Other code here */
    }
    .data :
    {
        *(.data*)
        /* Other data here */
    }
    .bss :
    {
        *(.bss*)
        /* Other bss here */
    }
}

If you would prefer to specify the entry point on the command line, you can modify your LDFLAGS to contain --entry eventHandlerShim.

Compatibility Chart

Here’s the compatibility matrix for different combination of our Rev A and Rev B hardware, OS version, and game builds created with different versions of the Playdate SDK.