Internals

Quick Install

curl -fsSL https://raw.githubusercontent.com/playdate-go/pdgo/main/install.sh | bash

# test 
chmod +x examples/build_all.sh 
chmod +x examples/*/build.sh
./examples/build_all.sh

This installs everything you need:

pdgoc - the build tool
Custom TinyGo with Playdate support (for device builds)
Configures your PATH automatically

Build Times

Platform	With System LLVM	Without (build from source)
Linux	~1 minute	~25-30 minutes
macOS	N/A (must build)	~25-30 minutes

Important

macOS users: Homebrew LLVM does not include static LLD libraries required to build TinyGo. The install script will automatically compile LLVM from source (~25-30 minutes, only needed once).

Pre-install LLVM (Linux only - speeds up build)

Ubuntu/Debian

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 20
sudo apt install clang-20 llvm-20-dev lld-20 libclang-20-dev

Fedora

sudo dnf install llvm20-devel clang20-devel lld20-devel

Arch Linux

sudo pacman -S llvm clang lld

ARM Toolchain

macOS: Included with Playdate SDK - no separate installation needed
Linux: Install via package manager: sudo apt install gcc-arm-none-eabi

Options

# Skip TinyGo build (simulator-only, instant install)
SKIP_TINYGO=1 curl -fsSL https://raw.githubusercontent.com/playdate-go/pdgo/main/install.sh | bash

# Custom parallel jobs
JOBS=8 curl -fsSL https://raw.githubusercontent.com/playdate-go/pdgo/main/install.sh | bash

What the installer does

Installs pdgoc - go install github.com/playdate-go/pdgo/cmd/pdgoc@latest
Clones TinyGo - downloads TinyGo v0.40.1 to ~/tinygo-playdate
Sets up LLVM - uses system LLVM (Linux) or builds from source (macOS)
Adds Playdate support - injects custom files into TinyGo:
- playdate.json - target config (Cortex-M7, custom GC, no scheduler)
- playdate.ld - linker script (memory layout, entry point)
- runtime_playdate.go - platform runtime (time, console output via SDK)
- gc_playdate.go - custom GC that delegates to Playdate SDK's realloc
Builds TinyGo - compiles with Playdate support
Configures PATH - adds pdgoc and tinygo to your shell

Result: ~/tinygo-playdate/build/tinygo - a TinyGo compiler that accepts -target=playdate

Warning

Windows is not currently supported. Linux and macOS only.

Overview

Note

This project is currently under active development, all API covered but not all features have been fully tested or implemented yet, PRs are always welcome.
Tested on macOS, tinygo 0.40.1 darwin/arm64, go1.25.6, LLVM 20.1.1, Playdate OS 3.0.2.

Note

Playdate SDK >= 3.0.2 is required
Golang >= 1.21 is requred

Hi, my name is Roman Bielyi, and I'm developing this project in my spare time as a personal initiative. This project is an independent effort and is neither endorsed by nor affiliated with Panic Inc.

As a Go developer, I immediately wanted to bring Go to the Playdate. It wasn’t straightforward, but I got it working -- hope you’ll enjoy experimenting with it.

Important

The main objective now is to release a stable 1.0.x version. To achieve this, we need to rewrite all official Playdate SDK examples from C/Lua into Go and ensure that the Go API bindings are mature, stable, and provide complete coverage of all subsystems.

Usage

pdgoc is a command-line tool that handles everything for building Go apps for Playdate, both Simulator and Device builds.

Important

Always use pdgoc for building. Do not try to run go build or tinygo build directly because pdgoc handles all the complexity: SDK paths, CGO flags, temporary files, etc.

Tip

The sim and device flags can be combined to build for both Simulator and Device simultaneously.

Flag	Description
`sim`	Builds project for the Playdate Simulator only
`device`	Builds project for the Playdate console only
`run`	Builds and runs project in the Playdate Simulator
`deploy`	Deploys and runs on connected Playdate device (requires `-device`)

Flag	Description
`name`	Sets the `name` property for pdxinfo
`author`	Sets the `author` property for pdxinfo
`desc`	Sets the `description` property for pdxinfo
`bundle-id`	Sets the `bundleID` property for pdxinfo
`version`	Sets the `version` property for pdxinfo
`build-number`	Sets the `buildNumber` property for pdxinfo
`image-path`	Sets the `imagePath` property for pdxinfo
`launch-sound-path`	Sets the `launchSoundPath` property for pdxinfo
`content-warn`	Sets the `contentWarning` property for pdxinfo
`content-warn2`	Sets the `contentWarning2` property for pdxinfo

Note

To use the pdgoc CLI tool, navigate to the project root directory -- the one containing the Source folder with your .go source files, go.mod, go.sum, and any assets.
Simply execute pdgoc from there. It will detect the 'Source' directory automatically.

Example:
If your structure looks like this:

your-project/
├── Source/
│   ├── main.go
│   ├── go.mod
│   ├── go.sum
│   └── assets/ (images, sounds, etc.)
└──

Then cd your-project/ and run pdgoc.

Example:

pdgoc -device -sim \
  -name=MyApp \
  -author=YourName \
  -desc="My App" \
  -bundle-id=com.yourname.myapp \
  -version=1.0 \
  -build-number=1

The main.go:

package main

import (
	"github.com/playdate-go/pdgo"
)

// A global pointer to the Playdate API. 
//Initialized automatically when the game starts. 
//All SDK calls go through this variable: pd.Graphics.DrawText(...), pd.System.DrawFPS(...), etc.
var pd *pdgo.PlaydateAPI


// Called once when the game launches (during kEventInit).
// Use this to load images, sounds, fonts, and initialize your game state. The Playdate API (pd) is fully available here.
func initGame() {
	
}

// The main game loop. Called every frame (~30 FPS by default). Here you:
// Handle input (pd.System.GetButtonState())
// Update game logic
// Draw graphics (pd.Graphics.DrawText(), pd.Graphics.DrawBitmap())
// Return value: 1 to tell Playdate the display was updated and needs refresh. Return 0 if nothing changed (saves battery).
func update() int {
	
}

// Must exist but remains empty. 
//Playdate doesn't use Go's normal main() entry point, instead, the SDK calls eventHandler which is generated by pdgoc
func main() {}

Internals

Device:

For Playdate hardware pdgoc uses a custom TinyGo build with full Playdate hardware support instead of standard Go build tools.

Custom GC:
Custom TinyGo build for Playdate achieves minimal binary sizes through custom Playdate GC: Instead of including traditional garbage collection logic (mark, sweep, write barriers), we delegate all allocations to the Playdate SDK's realloc function. This results in minimal GC wrapper code in the final binary. The Playdate OS already provides a robust allocator optimized for the hardware, and we simply use it!

click to see: gc_playdate.go

//go:noinline
func alloc(size uintptr, layout unsafe.Pointer) unsafe.Pointer {
    size = align(size)
    gcTotalAlloc += uint64(size)
    gcMallocs++

    ptr := _cgo_pd_realloc(nil, size)
    if ptr == nil {
        runtimePanic("out of memory")
    }

    // Zero the allocated memory
    memzero(ptr, size)
    return ptr
}

func GC() {
    // No-op - Playdate SDK manages memory
}

func SetFinalizer(obj interface{}, finalizer interface{}) {
    // No-op
}

No Static Heap:
Standard TinyGo embedded targets reserve heap space in BSS section. Our runtime configuration eliminates this by setting needsStaticHeap = false. As a result, BSS is reduced from approx. 1MB to approx. 300 bytes.

click to see: gc_playdate.go

const needsStaticHeap = false

func initHeap() {
    // No initialization needed - Playdate SDK handles it
}

Minimal Runtime Configuration:
No scheduler, no threading, no dynamic stack management. A fixed stack size of ~60KB is used instead of Go's traditional growable stacks.

click to see: playdate.json

{
    "inherits": ["cortex-m"],
    "llvm-target": "thumbv7em-unknown-unknown-eabihf",
    "cpu": "cortex-m7",
    "features": "+armv7e-m,+dsp,+hwdiv,+thumb-mode,+fp-armv8d16sp,+vfp4d16sp",
    "build-tags": ["playdate", "tinygo", "gc.playdate"],
    "gc": "playdate",
    "scheduler": "none",
    "serial": "none",
    "automatic-stack-size": false,
    "default-stack-size": 61800,
    "cflags": ["-DTARGET_PLAYDATE=1", "-mfloat-abi=hard", "-mfpu=fpv5-sp-d16"]
}

LLVM Optimization:

Target: thumbv7em-unknown-unknown-eabihf
CPU: cortex-m7 with FPU (-mfpu=fpv5-sp-d16, -mfloat-abi=hard)
Features: Thumb-2, DSP, hardware divide, VFP4
Dead Code Elimination: Unused functions stripped via linker script
Link-Time Optimization: Cross-module inlining via LLVM

click to see: playdate.json & playdate.ld

Target configuration:

{
    "llvm-target": "thumbv7em-unknown-unknown-eabihf",
    "cpu": "cortex-m7",
    "features": "+armv7e-m,+dsp,+hwdiv,+thumb-mode,+fp-armv8d16sp,+vfp4d16sp",
    "cflags": ["-DTARGET_PLAYDATE=1", "-mfloat-abi=hard", "-mfpu=fpv5-sp-d16"]
}

Linker script (dead code elimination):

ENTRY(eventHandlerShim)

SECTIONS
{
    .text : ALIGN(4) {
        KEEP(*(.text.eventHandlerShim))
        KEEP(*(.text.eventHandler))
        KEEP(*(.text.updateCallback))
        KEEP(*(.text.runtime_init))
        *(.text) *(.text.*) *(.rodata) *(.rodata.*)
        KEEP(*(.init)) KEEP(*(.fini))
        . = ALIGN(4);
    }
    ...
    /DISCARD/ : { *(.ARM.exidx*) *(.ARM.extab*) }
}

/DISCARD/ removes unused ARM exception sections, KEEP() preserves only critical entry points.

Simulator:

pdgoc uses Go's native build tools to compile apps for the Playdate Simulator.

Under the hood, it automatically runs:

go build -ldflags="-w -s" -gcflags="all=-l" \
  -trimpath -buildvcs=false -race=false \
  -buildmode=c-shared \
  -o "some/output" "some/input"

All flags are optimized: stripping debug info (-w -s), disabling race detector, and producing a C-shared library with -buildmode=c-shared needed for Simulator instead of binary executable. In Unix systems it's .so and in macOS it's .dylib

Flag	Purpose
`-ldflags="-w -s"`	`-w`: Strip debug info (DWARF). `-s`: Strip symbol table. Shrinks binary ~30-50%
`-gcflags="all=-l"`	Disable function inlining & optimizations for simulator compatibility
`-trimpath`	Remove local filesystem paths from binaries (security/portability)
`-buildvcs=false`	Skip embedding VCS data (git info) - faster builds
`-race=false`	Explicitly disable race detector (already off by default)
`-buildmode=c-shared`	Key: Build as C-shared library (`.dylib`/`.so`) for Playdate Simulator

Why Not Go But TinyGo

No Bare-Metal ARM Support:
Standard Go compiler (gc) only supports these targets:

Flag	Purpose
linux	amd64, arm64, arm, 386, ...
darwin	amd64, arm64
windows	amd64, arm64, 386

Playdate requires: thumbv7em-none-eabihf (ARM Cortex-M7, no OS), and this is simply impossible:
GOOS=none GOARCH=thumbv7em go build # not supported

Size:
Standard Go runtime includes Garbage Collector, Goroutine Scheduler, Stack Management and Reflection, binary size approx. 2-5 MB minimum. Playdate constraints are 16 MB total RAM (shared with game data, graphics, sound), games typically 50 KB - 2 MB.

Feature	Standard Go	TinyGo
Bare-metal support	No	Yes
GOOS= not required	No	Yes
ARM Cortex-M	No	Yes thumbv7em target
Minimal runtime	No approx. 2MB	Yes approx. 1-4 KB
Custom GC	No	Yes pluggable (gc.playdate)
No OS required	No	Yes
Relocatable code	No	Yes via LLVM
CGO on bare-metal	No	Yes (with custom runtime)

In short:

Go Source -> TinyGo Frontend -> LLVM IR -> LLVM Backend -> ARM Thumb-2 ELF
                                              |
                              Cortex-M7 optimizations
                              Position-independent code
                              Dead code elimination

Summary: Standard Go is designed for desktop/server environments, full operating systems, abundant memory (GB). Playdate requires: bare-metal ARM Cortex-M7, no operating system, tiny runtime, SDK-managed memory.

TinyGo bridges this gap by reimplementing Go compilation targeting embedded systems with LLVM backend. Our custom TinyGo build supports CGO on bare-metal Playdate hardware through a unified C wrapper layer (pd_cgo.c).

Flow:

Device Build

┌─────────────────────────────────────────────────────────────┐
│  pdgoc -device                                              │
├─────────────────────────────────────────────────────────────┤
│  1. Copy pd_cgo.c from pdgo module to build/pd_runtime.c    │
│  2. Create Source/main_tinygo.go                            │
│  3. Run go mod tidy                                         │
│  4. Create /tmp/device-build-*.sh                           │
│  5. Execute build script:                                   │
│     ├── Compile pd_runtime.c -> pd_runtime.o -> libpd.a     │
│     ├── Create build/playdate.ld                            │
│     ├── Create ~/tinygo-playdate/targets/playdate.json      │
│     ├── TinyGo build -> pdex.elf                            │
│     ├── pdc -> GameName.pdx/                                │
│     └── Delete build/ directory                             │
│  6. Delete Source/main_tinygo.go                            │
│  7. Delete Source/pdxinfo                                   │
└─────────────────────────────────────────────────────────────┘

Simulator Build

┌─────────────────────────────────────────────────────────────┐
│  pdgoc -sim                                                 │
├─────────────────────────────────────────────────────────────┤
│  1. Create Source/main_cgo.go                               │
│  2. go build -buildmode=c-shared -> pdex.dylib + pdex.h     │
│  3. Delete Source/pdex.h                                    │
│  4. Delete Source/main_cgo.go                               │
│  5. pdc -> GameName_sim.pdx/                                │
│  6. Delete Source/pdex.dylib                                │
│  7. Delete Source/pdxinfo                                   │
└─────────────────────────────────────────────────────────────┘

Temporary files created by pdgoc during build:

Device Build Files

pd_runtime.c - Copied from pd_cgo.c in the pdgo module. This C file provides all Playdate SDK wrappers that Go code calls via CGO. It includes TinyGo runtime support functions (_cgo_pd_realloc, _cgo_pd_logToConsole, _cgo_pd_getCurrentTimeMS) and the eventHandler entry point. Compiled with -DTARGET_PLAYDATE=1 to enable device-specific code.

main_tinygo.go - Contains the //export go_init and //export go_update directives that tell TinyGo to expose these functions as C-callable symbols. The C runtime calls these functions to initialize the game and run the update loop. This file is separate from the user's main.go to avoid polluting their code with build-specific exports.

playdate.ld - The linker script tells the ARM linker how to arrange code and data in memory. It defines the entry point (eventHandlerShim), ensures critical functions appear at the beginning of the binary, and sets up BSS/data sections.

playdate.json - TinyGo's target configuration file. It specifies the CPU architecture (Cortex-M7), compiler flags, which garbage collector to use (gc.playdate), and links to the linker script. This file tells TinyGo exactly how to compile for Playdate hardware.

libpd.a - A static library compiled from pd_runtime.c. TinyGo links against this library to resolve the C function references. Static linking ensures all SDK wrapper code is embedded directly in the final binary.

File	Location	Purpose	Cleanup
`pd_runtime.c`	`build/`	C wrappers (copy of pd_cgo.c)	Deleted with `build/` dir
`main_tinygo.go`	`Source/`	TinyGo entry points (`//export`)	Deleted after build
`device-build-*.sh`	`/tmp/`	Embedded build script	Deleted after build
`playdate.ld`	`build/`	Linker script	Deleted with `build/` dir
`playdate.json`	`~/tinygo-playdate/targets/`	TinyGo target config	Overwritten each build
`pdex.elf`	`build/`	Compiled ELF binary	Deleted with `build/` dir
`pd_runtime.o`	`build/`	Compiled C object	Deleted with `build/` dir
`libpd.a`	`build/`	Static C library	Deleted with `build/` dir
`pdxinfo`	`Source/`	Game metadata	Deleted after build

Simulator Build Files

The simulator build uses the same pd_cgo.c from the pdgo module as the device build, but compiled for the host architecture. The C wrappers are linked directly into the shared library via standard Go CGO.

main_cgo.go - Contains import "C" and //export eventHandler directive that tells the standard Go compiler to generate a C-callable entry point. The simulator runs on your host machine (macOS/Linux), where CGO is fully supported.

pdex.h - Automatically generated by go build -buildmode=c-shared. This header file contains C function declarations for all exported Go functions. We immediately delete it since Playdate doesn't need it - the SDK already knows the expected function signatures.

pdex.dylib / pdex.so - The compiled shared library containing your Go game code and the C wrappers. The Playdate Simulator dynamically loads this library at runtime and calls eventHandler when your game starts. This file is moved into the .pdx bundle by pdc.

File	Location	Purpose	Cleanup
`main_cgo.go`	`Source/`	CGO entry points (`//export`)	Deleted after build
`pdex.h`	`Source/`	CGO header (auto-generated)	Deleted after build
`pdex.dylib` / `pdex.so`	`Source/`	Compiled shared library	Deleted after build
`pdxinfo`	`Source/`	Game metadata	Deleted after build

API Bindings

The latest full documentation for API bindings is hosted here: https://pkg.go.dev/github.com/playdate-go/pdgo#section-documentation

Examples

Note

We will add more complex examples as the project progresses

To build all examples please do this:

# in project repo root
chmod +x examples/build_all.sh 
chmod +x examples/*/build.sh
./examples/build_all.sh

Each example includes a build.sh script that runs pdgoc with all necessary flags.

Particles -- examples/particles

Sprite Collisions -- examples/sprite_collisions

Tilemap -- examples/tilemap

JSON High and Low Level Encoding and Decoding -- examples/json | examples/json_lowlevel

Bach MIDI -- examples/bach_midi

3D Library -- examples/3d_library

Sprite Game -- examples/spritegame

Conway's Game of Life -- examples/life

Bouncing Square -- examples/bouncing_square

Go Logo -- examples/go_logo

Hello World -- examples/hello_world

Roadmap

Community

Using these links and places, you can discuss the PdGo project with each other:

Slack

Reddit:

Discord:

Playdate Development Forum (this is the main place to discuss): https://devforum.play.date/t/golang-support-for-playdate-compiler-sdk-bindings-tools-and-examples/24919

Attribution

The Go Gopher was designed by Renee French and is licensed under Creative Commons 4.0 Attribution License.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
assets		assets
cmd/pdgoc		cmd/pdgoc
examples		examples
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
api.go		api.go
common.go		common.go
display.go		display.go
file.go		file.go
gfx.go		gfx.go
go.mod		go.mod
install.sh		install.sh
json.go		json.go
lua.go		lua.go
network.go		network.go
pd_api.h		pd_api.h
pd_cgo.c		pd_cgo.c
scoreboards.go		scoreboards.go
sound.go		sound.go
sprite.go		sprite.go
sprite_callbacks.go		sprite_callbacks.go
sys.go		sys.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Menu

Quick Install

Build Times

Pre-install LLVM (Linux only - speeds up build)

Ubuntu/Debian

Fedora

Arch Linux

ARM Toolchain

Options

What the installer does

Overview

Usage

Internals

Device:

Simulator:

Why Not Go But TinyGo

Flow:

Device Build

Simulator Build

API Bindings

Examples

Roadmap

Community

Attribution

License

About

Uh oh!

Releases 13

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Menu

Quick Install

Build Times

Pre-install LLVM (Linux only - speeds up build)

Ubuntu/Debian

Fedora

Arch Linux

ARM Toolchain

Options

What the installer does

Overview

Usage

Internals

Device:

Simulator:

Why Not Go But TinyGo

Flow:

Device Build

Simulator Build

API Bindings

Examples

Roadmap

Community

Attribution

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages