playdate-dev

Playdate Dev

Overview

Build Playdate games in Lua using the official Playdate SDK. The Playdate is a small yellow handheld with a 400×240 1-bit display, a physical crank, A/B buttons, and a D-pad. Understanding its constraints and unique input is essential.

Hardware specs:

• Display: 400×240 pixels, 1-bit (black/white only)
• Memory: ~16 MB RAM (aim for <8 MB peak usage)
• CPU: 180 MHz Cortex-M7 (device is slower than simulator — always profile on hardware)
• Input: A button, B button, D-pad (up/down/left/right), crank, menu button
• Audio: 44.1kHz stereo, Synth + SamplePlayer APIs
• Accelerometer: 3-axis, opt-in to save battery

Quick Start Workflow

1. Clarify the request scope (gameplay goal, target device vs simulator, SDK version, release vs prototype).
2. Choose inputs and accessibility (buttons, crank, accelerometer; provide non-crank alternatives; respect reduce-flashing setting).
3. Choose rendering approach (sprites vs immediate draw, image sizes, refresh rate, 1x vs 2x scale).
4. Implement the core loop (define playdate.update(), update game state, call playdate.graphics.sprite.update() and playdate.timer.updateTimers() when used).
5. Add metadata and launcher assets (pdxinfo, buildNumber, launcher card and icon sizes).
6. Test in the Simulator and on hardware (screen legibility, crank feel, audio balance, performance).

Starter Project

• Copy assets/lua-starter into a new project folder.
• Keep Source/main.lua and Source/pdxinfo in the source root.
• Replace placeholder values in pdxinfo and extend the update loop.

Build with:

pdc Source GameName.pdx      # compile to .pdx bundle
# Then open GameName.pdx in the Simulator, or drag to device

Core Game Loop

-- main.lua
import "CoreLibs/object"
import "CoreLibs/graphics"
import "CoreLibs/sprites"
import "CoreLibs/timer"

local gfx <const> = playdate.graphics

-- Game state
local playerX, playerY = 200, 120

function playdate.update()
    -- 1. Handle input
    if playdate.buttonIsPressed(playdate.kButtonLeft) then
        playerX -= 2
    elseif playdate.buttonIsPressed(playdate.kButtonRight) then
        playerX += 2
    end

    -- 2. Handle crank
    local crankDelta = playdate.getCrankChange()  -- degrees since last update
    playerY += crankDelta * 0.1                    -- map crank to movement

    -- 3. Update sprites and timers (required each frame if used)
    gfx.sprite.update()
    playdate.timer.updateTimers()

    -- 4. Draw (if not using sprites)
    gfx.clear()
    gfx.fillCircleAtPoint(playerX, playerY, 10)
end