Playdate SDK Core — Lua Development Patterns

Playdate SDK Core — Lua Development Patterns

Runtime Environment

Playdate games run Lua 5.4 on-device via the Playdate SDK runtime. The same Lua 5.4 interpreter runs on desktop for unit tests, but the playdate.* API is absent on desktop.

Key consequence: never call playdate.* APIs in models or systems. Those modules must be importable and testable on desktop Lua without a simulator.

Global Module Pattern

The Playdate SDK uses import (not require). Imported modules declare a global table:

-- src/models/Actor.lua
Actor = {}
Actor.__index = Actor

function Actor.new(def)
  local a = setmetatable({}, Actor)
  a.name = def.name
  a.maxHP = def.maxHP
  a.hp = def.maxHP
  return a
end

function Actor:isDead()
  return self.hp <= 0
end

Callers reference the global directly after import:

import "models/Actor"   -- declares global Actor
local hero = Actor.new(PARTY_DATA.player)

Import Paths

• import resolves relative to the project src/ root (the path passed to pdc)