Getting Started with Playdate Development for macOS

Chris Mendez -

I'm a big fan of Panic Software, so when they announced Playdate –their version of a classic 90's Gameboy fueled by indie game developers– I had to buy it.

The only catch is that getting it in the mail took two years –or possibly buy it from AliExpress.

WOW!

I completely forgot about the purchase until just 3 three weeks ago when it appeared on my doorstep.

Here's what the device looks like.

After 2 hours of playing with the device, I felt the sudden itch to learn what it would stake to start developing a game.

The article below is for new developers who want to learn how to configure their macOS for Playdate development.

This article does not attempt to provide an exhaustive list of ways to do it. It's simply my path to make things work easily and repeatably.

Step 0 - Install XCode Command Line Tools

Open Utilities > Terminal and paste this command.

xcode-select --install

Step 1 - Download & Install Playdate SDK

Visit Playdate Developer

The SDK will install itself within /Developer > Playdate.

Step 2 - Configure Your Dev Environment

Update your environmental variables to ensure the Terminal points to the right directories. If you are on a newer macOS version, you'll likely be using zsh .

Add the following to your shell profile e.g.~/.profile, ~/.bash_profile or ~/.zshrc:

nano ~/.zshrc

Paste this within ~/.zshrc. These simply point to your Playdate SDK.

## ## ## ## ## ## ## ## ##
## Playdate SDK
## Intentionally Explicit Descriptions of Each Path
## ## ## ## ## ## ## ## ##
export PATH="$HOME/Developer/PlaydateSDK/bin/pdc:$PATH"
export PATH="$HOME/Developer/PlaydateSDK/bin:$PATH"
export PATH="$HOME/Developer/PlaydateSDK/bin/Playdate\ Simulator.app:$PATH"
export PLAYDATE_SDK_PATH="$HOME/Developer/PlaydateSDK"

Refresh your shell profile.

source ~/.zshrc

Step 2.a - Verify the Install

If you see Terminal respond with a path similar to the one above, things are working well.

which pdc

Step 3 - Pick a Starter Game

Playdate SDK comes with a suite of fantastic examples. For this example, I will pick the "Asteroids".

Change the directory to the game.

cd ~/Developer/PlaydateSDK/Examples/Asheteroids/

Step 4 - Create two Convenience Shell Scripts

These are two shell scripts I recommend creating. They make it easier to compile and test without having to remember a bunch of commands.

4.a - Create a Compile Script

In the Asheteroids directory, create a new file named compile.sh and paste a Playdate-specific command.

echo "pdc Source ./main.pdx" >> compile.sh

The command above will run the pdc executable, look within the Source directory for the default main.lua file, and create a game file named main.pdx in the same directory as the compile script.

Run the shell script. We explicitly add ```/bin/ssh `` to minimize any unexpected issues from the Terminal.

/bin/zsh ./compile.sh

4.b - Create a Test Script

Like 4.a, let's create a test.sh script.

echo "open -a ~/Developer/PlaydateSDK/bin/Playdate\ Simulator.app ./main.pdx" >> test.sh

Run the script.

/bin/sh ./test.sh

Step 5 - Adding Game Metadata

Create a new file within the Source directory.

touch Source/pdxinfo

Edit and paste your metadata into pdxinfo.

name=My First Game
author=Chris
description=My First Game
bundleID=com.chrisjmendez.myfirstgame
version=1
buildNumber=100

You can see the data inputed within the Metadata menu within the simulator.

Step 6 - Review Your Work

Step 6.a - Review your Metadata via "Show Package Contents"

Compile your project.

/bin/sh ./compile.sh && /bin/sh ./test.sh

Then inspect your .pdx file to verify things are looking good.

Step 6.b - Test Game in Simulator

If you want to see your game in a different way within the Simulator, copy the game into the SDK then turn on the simulator again.

cp ./main.pdx ~/Developer/PlaydateSDK/Disk/Games/

Step 6.c - Test Game on Physical Device

With your simulator open, plug-in your physical device and you will notice a new menu option to upload your game.

Step 6.d - Test Physical Game on Computer Screen via Mirror

Aside from Simulator, Panic also offers Mirror, a piece of software that allows you to mirror your physical device back to your computer monitor. This is useful when trying to take a video capture for promotional purposes.

Troubleshooting

Permission denied

If you happen to get a Permission denied while trying to run the shell scripts, changing the permissions to make it executable will likely fix the issue.

Make compile.sh executable.

chmod +x compile.sh

Make test.sh executable.

test.sh

Resources

  • SquidGod has a collection of fantastic videos I highly recommend watching. I appreciate the efforts he's making to empower the Playdate developer community.