Playdate Build Workflow

Prerequisites

| Tool | Install | |------|---------| | Playdate SDK | https://play.date/dev/ — drag PlaydateSDK to ~/Developer/PlaydateSDK | | pdc compiler | Bundled with SDK at $PLAYDATE_SDK_PATH/bin/pdc | | Playdate Simulator | Bundled with SDK | | Lua 5.4 | brew install lua (macOS) — for desktop unit tests only |

Shell Configuration

Add to ~/.zshrc:

bash
export PLAYDATE_SDK_PATH="${HOME}/Developer/PlaydateSDK"
export PATH="${PLAYDATE_SDK_PATH}/bin:${PATH}"

Reload: source ~/.zshrc

Verify: pdc --version

Build

bash
pdc src/ build/game.pdx

• Input: src/ directory containing main.lua
• Output: build/game.pdx bundle directory
• The -q flag suppresses info-level output; remove it to see all compiler messages
• pdc requires PLAYDATE_SDK_PATH to be set in the environment

Error format:

src/models/Actor.lua:12: unexpected symbol near 'end'

Run in Simulator

bash
# Direct path:
"${PLAYDATE_SDK_PATH}/bin/Playdate Simulator.app/Contents/MacOS/Playdate Simulator" build/game.pdx

# macOS open shortcut:
open -a "Playdate Simulator" build/game.pdx

The simulator reloads automatically when the .pdx bundle changes on disk.

Simulator Controls

| Key | Playdate button | |-----|----------------| | Arrow keys | D-pad | | Z | A button | | X | B button | | Backspace | Menu | | Mouse scroll | Crank |

Desktop Unit Tests

Models and systems that don't call playdate.* APIs can be tested on desktop Lua:

bash
lua tests/TurnOrder_test.lua
lua tests/Battle_test.lua

Rule: Models and systems must never call playdate.*. This keeps them testable without the simulator.

Smoke Test Script Pattern

bash
#!/usr/bin/env bash
set -euo pipefail

PLAYDATE_SDK_PATH="${PLAYDATE_SDK_PATH:-${HOME}/Developer/PlaydateSDK}"
PDC="${PLAYDATE_SDK_PATH}/bin/pdc"

# 1. Build
"${PDC}" -q src/ build/game.pdx
echo "Build: PASS"

# 2. Run desktop tests
for f in tests/*_test.lua; do
  lua "$f"
done
echo "Unit tests: PASS"

Troubleshooting

| Problem | Fix | |---------|-----| | pdc: command not found | Confirm $PLAYDATE_SDK_PATH/bin is on PATH | | PLAYDATE_SDK_PATH is not set | Export the variable in your shell profile | | Simulator doesn't launch | Verify simulator path; try open -a "Playdate Simulator" | | lua: command not found | brew install lua (for tests only) | | Build succeeds but game doesn't run | Check pdxinfo has required name, bundleID, version fields |