---
name: wintermuted/playdate-build-workflow
source: https://app.decimal.ai/s/wintermuted-playdate-build-workflow@1/SKILL.md
source_sha256: fd8aa40623ce
---

# 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 |