Hi everyone!
I’d like to introduce gopdsdk, an independent open-source Go SDK and toolchain for building Playdate games:
The project explores whether Go on Playdate can feel like a coherent SDK rather than a thin set of C bindings. Its design focuses on:
- one public Go API for Simulator and device builds;
- explicit ownership and deterministic cleanup of native resources;
- game logic that can be tested as ordinary Go code;
- a CLI that builds, runs, deploys and diagnoses the toolchain;
- honest separation between unit tests, Simulator checks, device builds and physical hardware acceptance.
The current release is v0.6.0. It is still pre-1.0, but it already supports complete Simulator and physical-device workflows.
Getting started
go run github.com/Djunichi/gopdsdk/cmd/gopdsdk@v0.6.0 doctor
go run github.com/Djunichi/gopdsdk/cmd/gopdsdk@v0.6.0 init \
--module example.com/my-game \
./my-game
cd my-game
go mod tidy
You can then build or launch the same game package for either target:
gopdsdk run .
gopdsdk run device .
The CLI also provides environment diagnostics and end-to-end probes:
gopdsdk doctor --probe
gopdsdk probe simulator --run
gopdsdk probe device
gopdsdk probe connection
Finding an executable is not treated as proof that the corresponding toolchain works: Simulator compilation, device compilation and USB deployment are reported as separate capabilities.
What is implemented today?
The current public SDK includes:
- lifecycle events, buttons, crank and frame timing;
- text, primitives, bitmaps, fonts and framebuffer access;
- sprites, collisions, animation, tilemaps and cameras;
- display control, offscreen drawing, transforms and stencils;
- filesystem access and versioned persistence;
- System Menu items, localization and Launcher exit;
- accelerometer, battery, power and system preferences;
- sample and streaming audio;
- channels, synths, signals, instruments, sequences and effects;
- microphone recording;
- scoreboards and debug-message delivery;
- video playback with screen and offscreen targets.
Native resources have explicit lifetimes. Owned bitmaps, sprites, fonts, files, audio players, synths and effects are closed deterministically, while borrowed values have restricted lifetimes. Correctness does not depend on finalizers.
Callbacks are bounded and suppressed after termination, and invalid operations such as use-after-close return defined Go errors rather than forwarding invalid handles to the C API.
A game built with gopdsdk
Crank Caverns is an external Playdate game built entirely against the public gopdsdk API.
It combines the SDK’s individual features in one game:
- platforming with crank-assisted movement and double jumps;
- sprites, collisions, animation, tilemaps and camera movement;
- custom fonts, bitmaps, primitives and framebuffer drawing;
- music and sound effects;
- pause, lock, resume and termination handling;
- main, pause and System Menu interfaces;
- localized settings;
- battery status and Launcher exit;
- versioned save data with migration and corrupt-save recovery;
- deterministic tests for gameplay and persistence.
The same game has been run in the official Windows Simulator and on a physical Playdate. A bounded 1,800-frame measurement reported approximately 33 ms mean frame time on both targets and a stable count of 18 explicitly owned native resources.
The physical-device build produced a 965,530-byte PDX and used 287,912 bytes of static RAM. These are bounded measurements rather than a claim of unlimited complexity or long-term performance.
Crank Caverns is useful evidence that the SDK’s features work together in a real external consumer, not only in isolated examples.
Simulator and device runtime
Simulator applications use the standard Go compiler and a native shared-library bridge.
Device applications use TinyGo 0.41.1 with:
- hard-float Cortex-M7 compilation;
- a conservative garbage collector;
- a checked 256 KiB heap;
- deterministic fail-stop behavior on panic or out-of-memory;
- official Playdate setup and linker inputs.
The current device profile is intentionally a subset of Go. It does not support goroutines, channels, select, public reflection, finalizers or device paths requiring defer/recover. These restrictions are detected during the build instead of being left as unpredictable hardware failures.
Verification status
Pure-Go tests and external-consumer CLI checks run natively on Windows, macOS and Linux.
The complete official SDK, Simulator, device build, USB deployment and physical-device profile is currently verified on Windows with:
- Go 1.26.5;
- Playdate SDK 3.1.1;
- TinyGo 0.41.1;
- Arm GNU Toolchain 15.3.1.
macOS and Linux SDK, Simulator and device integration remain explicitly unverified. Reports and contributions from developers using those hosts would be especially valuable.
Relationship to pdgo
pdgo is another independent effort bringing Go to Playdate, with a more direct mapping of the official C API. It already exposes some areas that gopdsdk does not, notably general HTTP/TCP networking and Lua integration.
gopdsdk instead emphasizes a Go-oriented capability API, explicit resource ownership, deterministic tests, toolchain diagnostics and per-feature hardware evidence.
A fair summary today is: pdgo is broader in several direct C API areas, while gopdsdk goes deeper on the contracts and verification of its implemented vertical slices.
The projects are independent. gopdsdk uses the official Playdate SDK headers, documentation, examples and observable tools as its normative sources.
What is still planned?
Before 1.0, the roadmap includes:
- completing the remaining graphics and display operations;
- completing sprite configuration, queries and callbacks;
- filling the remaining sound and system API gaps;
- completing the offline filesystem and media audit;
- hardening and documenting the TinyGo device profile;
- freezing the public API and compatibility contract.
General HTTP/TCP networking is currently reserved for post-1.0 research rather than being rushed into the initial stable release.
Feedback is welcome, especially about:
- the public API and ownership model;
- missing capabilities that block real game designs;
- macOS and Linux toolchain behavior;
- device memory and performance;
- the first-project experience.
Project:
Example game:
API:
Compatibility status:
Roadmap:
Thanks for reading! I’d be happy to answer questions about the API, toolchain or device runtime—and I’d love to see what other developers might build with Go on Playdate.
