pi-playdate
Playdate game development for Pi. Build, run, and deploy Playdate games in Lua and C.
A pi extension for developing Playdate games. Provides typed tools for building, running, inspecting, and deploying Playdate projects in Lua and C.
Install
pi install git:github.com/aliou/pi-playdateQuick Start
> Create a new Playdate game called "Bounce" in Lua
# Agent reads the playdate skill, creates Source/main.lua and Source/pdxinfo
> Build and run it
# Agent calls playdate_build then playdate_run_sim
> Take a screenshot so I can see it
# Agent calls playdate_screenshot, returns the imageTools
| Tool | Description |
|---|---|
playdate_doctor | Check SDK installation, pdc, simulator, ARM toolchain, device |
playdate_build | Compile Lua or C project to .pdx bundle |
playdate_build_release | Compile Lua or C project to a release .pdx bundle (pdc -s for Lua) |
playdate_run_sim | Launch the Playdate Simulator |
playdate_stop_sim | Stop the running simulator |
playdate_sim_log | Read recent simulator output from process logs and DAP console/output events |
playdate_screenshot | Capture simulator screenshot (returned as image) |
playdate_sim_input | Send D-pad/A/B/menu input to the simulator |
playdate_sim_crank | Set simulator crank angle and dock state |
playdate_sim_accel | Set simulator accelerometer values |
playdate_sim_state | Read simulator hardware state (crank, accel, buttons, FPS, battery, time) |
playdate_sim_game_state | Check the __pi_state() convention and dump structured game state |
playdate_sim_game_state_write | Apply structured game state via __pi_state_write() using patch or replace |
playdate_sim_eval | Evaluate Lua expressions in the running simulator |
playdate_device_log | Read serial log output from a connected Playdate device |
playdate_run_device | Deploy .pdx to a connected Playdate |
playdate_install_device | Build, deploy, and launch a Playdate project on device |
Commands
| Command | Description |
|---|---|
/playdate:doctor | Check environment health |
/playdate:sim | Build and run in simulator |
/playdate:device | Build and deploy to device |
/playdate:settings | Configure SDK path, build mode, etc. |
Settings
Stored at ~/.pi/agent/extensions/playdate.json (global) and .pi/extensions/playdate.json (project).
| Setting | Default | Description |
|---|---|---|
sdkPath | $PLAYDATE_SDK_PATH | Override SDK path |
defaultTarget | "simulator" | Default build target |
buildMode | "debug" | C build mode |
armToolchainPath | auto-detect | ARM toolchain for C device builds |
autoOpenSimulator | true | Auto-open simulator after build |
simulatorLogLines | 200 | Simulator log ring buffer size |
Requirements
- Playdate SDK installed
PLAYDATE_SDK_PATHenvironment variable set (or configured via settings)- For C projects:
cmake,arm-none-eabi-gcc(device builds)
Runtime inspection and control
For common simulator loops, prefer the typed tools over generic eval:
playdate_sim_inputfor D-pad / A / B / menuplaydate_sim_crankfor real crank position + dock stateplaydate_sim_accelfor accelerometer valuesplaydate_sim_stateto confirm hardware state in one round-tripplaydate_sim_game_statefor stable structured game-state dumps via__pi_state()playdate_sim_game_state_writeto apply structured state via__pi_state_write()withpatchorreplaceplaydate_sim_logfor recent simulator/runtime output before falling back to deeper inspectionplaydate_sim_evalonly for game-specific state or debugging
Game code can expose a global __pi_state() function that returns a plain Lua table. Then playdate_sim_game_state verifies the convention and dumps that table.
Games that support state injection can also expose __pi_state_write(payload, mode). Then playdate_sim_game_state_write sends plain JSON-like data with mode = "patch" | "replace".
playdate_sim_log reads the shared in-memory log ring buffer fed by simulator stdout/stderr and DAP output events when available. Use it early in crash/debug loops.
playdate_sim_eval still supports:
- bare expressions: auto-serialized, e.g.
playdate.readAccelerometer()->(0.1, 0.2, 0.3) p <expr>for raw valueseval <code>for statements with capturedprint()output- optional table-inspection controls for bare expressions:
depthto cap nestingstartto page through array-like tableskeypathto inspect a subtree likecards.13keysOnlyto inspect only table keys
Examples:
playdate_sim_eval(expression="__pi_state()", keysOnly=true)playdate_sim_eval(expression="__pi_state()", keypath="cards", start=13)playdate_sim_eval(expression="__pi_state()", keypath="cards.1", keysOnly=true)
Skill
The extension ships a playdate skill with reference docs for the Lua API, C API, CoreLibs, project layout, templates, performance tips, and common patterns. The agent loads these on demand when working on Playdate projects.
Dev docs
These are implementation docs for extension contributors, not end-user usage docs: