playdate-dev

Implements Playdate games in Lua using the official Playdate SDK APIs.

1|Updated May 6, 2026
One-click install
npx skills add https://github.com/surfingalien/FinSurfing --skill playdate-dev-surfingalien
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: playdate-dev
Source: https://github.com/surfingalien/FinSurfing/tree/main/.claude/skills/playdate-dev
Command: npx skills add https://github.com/surfingalien/FinSurfing --skill playdate-dev-surfingalien

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve? Building games for the Playdate handheld requires mastering its unique constraints: a 400x240 1-bit display, a physical crank, limited memory, and a Lua SDK with specific APIs for sprites, timers, audio, and input. This Skill provides the complete API knowledge, design guidelines, and a starter project needed to write working Playdate games without constantly consulting scattered SDK documentation. ## Core Features & Use Cases - Complete Lua API Coverage: Game loop structure, sprite system with collision detection, button/crank/accelerometer input, graphics drawing, fonts, audio (sample players and synthesizers), timers, save data, and system menu integration. - Hardware Design Guidance: Reference notes on screen legibility, font sizes, refresh rate tradeoffs, crank accessibility, and launcher asset requirements (card, icon, pdxinfo metadata). - Starter Project Template: A ready-to-copy Lua starter with main.lua and pdxinfo that compiles with the pdc compiler into a .pdx bundle. - Use Case: Ask for a crank-driven puzzle game and receive working Lua code with proper playdate.update() structure, crank delta handling with button fallbacks, sprite updates, and correct pdxinfo metadata ready to build and test in the Simulator. ## Quick Start Use the playdate-dev skill to create a Playdate game in Lua where the crank moves a paddle and the A button launches a ball.

Frequently Asked Questions about playdate-dev

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a Playdate game in Lua?

Create a Source folder with main.lua implementing playdate.update(), add a pdxinfo metadata file, then compile with pdc Source GameName.pdx. Open the resulting .pdx bundle in the Playdate Simulator or drag it to a device.

How do I use the Playdate crank for game input?

Call playdate.getCrankChange() each frame to get degrees rotated since the last update, or playdate.getCrankPosition() for absolute angle. Always check playdate.isCrankDocked() and provide button fallbacks for accessibility.

What are the Playdate screen and performance limits?

The display is 400x240 pixels, 1-bit black and white, with a default 30 fps refresh rate and 50 fps maximum. The device has roughly 16 MB RAM and a 180 MHz CPU, so profile on hardware since the simulator runs 2-3x faster.

How does sprite collision detection work in the Playdate SDK?

Set a collision rect with sprite:setCollideRect(), then use sprite:moveWithCollisions(x, y) which returns the actual position plus a list of collisions. Call playdate.graphics.sprite.update() every frame to update all sprites.

What launcher assets does a Playdate game need?

The pdxinfo file requires name, author, bundleID, version, and buildNumber fields. Launcher images include a 350x155 card, 32x32 icon, and their highlighted variants, placed in the imagePath directory.

Why does my Playdate game run slowly on hardware but fine in the simulator?

The simulator runs 2-3x faster than the 180 MHz device CPU. Reduce full-screen gfx.clear() calls, use the sprite system's dirty-rect rendering, pool objects instead of allocating per frame, and lower the refresh rate to 30 fps.