gopdsdk v1.0.1 - Stable Offline Playdate Go SDK

gopdsdk v1.0.0 is the first stable release of the independent, cross-platform Go SDK for building offline Playdate games.

This release freezes the documented public API, ownership and error contracts, callback ordering and lifetime rules, CLI surface, device Go profile, compatibility policy, and semantic-versioning guarantees for the v1.x line.

Changed Git username

gopdsdk v1.0.0 - Stable Offline Playdate Go SDK

gopdsdk v1.0.0 is the first stable release of the independent, cross-platform Go SDK for building offline Playdate games.

This release freezes the documented public API, ownership and error contracts, callback ordering and lifetime rules, CLI surface, device Go profile, compatibility policy, and semantic-versioning guarantees for the v1.x line.

Highlights

• Complete public Go contract for materially useful offline Playdate SDK capabilities.
• Stackless playdate/schedule scheduler with:
  • fixed task capacity;
  • deterministic FIFO execution;
  • cancellation-safe task IDs;
  • delayed, deadline, and repeating tasks;
  • bounded non-blocking queues;
  • deterministic round-robin polling.
• Bounded, reflection-free playdate/json package.
• Verified conservative-device support for:
  • normal-return defer;
  • the documented public reflection subset;
  • runtime.GC;
  • pure time.Duration parsing and formatting.
• Complete offline audio graph support, including:
  • nested channel routing;
  • borrowed post-effects channel outputs;
  • dry and wet level modulation signals;
  • LFO initial phase, deterministic random seeding, and continuous global update.
• Explicit ownership, close, expiry, callback, and termination behavior across native resources.
• Stable SemVer, migration, support, compatibility, and deprecation policies.

Device Go profile

Device applications use sequential Go compiled with TinyGo, conservative GC, scheduler none, and fail-stop panic handling.

Goroutines, blocking channels, select, sleep, timers, and tickers are replaced by playdate/schedule. recover, finalizers, application cgo, and undocumented reflection paths remain unsupported. See API.md for the exact contract.

Verification

The release passed:

• formatting, the complete Go test suite, vet, and git diff --check;
• external-consumer CLI tests;
• native CI on Windows, macOS, and Linux;
• the Linux race detector;
• official Playdate SDK 3.1.1 Simulator builds;
• TinyGo 0.41.1 conservative hard-float device builds;
• USB deployment and physical Playdate execution;
• the combined Simulator and physical-device acceptance regression;
• conservative-GC soak and bounded memory/resource checks;
• lifecycle cleanup and unchanged post-run crash/error logs.

Official SDK, Simulator, device-build, USB, and physical-device verification is currently established on Windows. macOS and Linux are native-CI tested, but their official SDK and hardware levels remain unverified.

Verified toolchain

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain GCC 15.3.1

Other versions are not rejected solely by version number, but remain unverified until the relevant probe and acceptance level passes.

Install

go run github.com/Djunichi/gopdsdk/cmd/gopdsdk@v1.0.0 doctor
go run github.com/Djunichi/gopdsdk/cmd/gopdsdk@v1.0.0 init --module example.com/my-game ./my-game
cd my-game
go mod tidy

gopdsdk v0.11.0 - Complete Offline Services and Media

gopdsdk v0.11.0

This release completes the P11 offline services and media scope.

JSON

• Added playdate/json, a dependency-free and reflection-free JSON package
  designed for the Playdate device runtime.
• Added bounded decoding from io.Reader or bytes.
• Preserved object ordering, duplicate names, exact number spelling, Unicode,
  and byte/path syntax diagnostics.
• Added validated compact and pretty streaming output to io.Writer.
• Added the examples/jsoncodec acceptance consumer.

Scoreboards

• Hardened both native scoreboard adapters.
• Native results are copied before deferred delivery on the update thread.
• Added a fixed four-slot completion queue.
• Enforced one pending request per operation kind.
• Immediate failures release their request slot.
• Termination clears queued work and suppresses late completions.

Scoreboards remain the sole pre-1.0 online exception; this release does not add
general networking or multiplayer.

Filesystem

• Confirmed that File.Seek preserves the official current-position behavior
  by returning tell after a successful seek.
• Added deterministic coverage for Seek(0, io.SeekCurrent).
• Added coverage for tell failure classification and copying transient
  filesystem diagnostics at the failing operation boundary.

Video-stream audit

Playdate SDK 3.1.1 does not provide a documented or usable offline input
contract for playdate_videostream. The experimental stream API was therefore
removed rather than exposing an unsafe or non-functional public contract.

Owned packaged PDV playback remains available through Videos.LoadVideo and
VideoPlayer. Videostream research is deferred until Panic documents a usable
source container and protocol.

Compatibility

The changes are additive for existing v0.10 applications, except for removal of
the unreleased experimental VideoStream API.

Verified toolchain:

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain GCC 15.3.1

Validation

• Formatting, go test ./..., go vet ./..., and git diff --check
• Native CI on Windows, macOS, and Linux
• Linux race detector
• Playdate SDK 3.1.1 Simulator compilation and packaging on Windows
• Conservative hard-float device compilation, linking, relocation validation,
  and packaging
• Documented Simulator and physical-device acceptance for JSON and scoreboard
  failure/sequential-request behavior

See MIGRATING.md, CHANGELOG.md, API.md, and COMPATIBILITY.md for detailed
contracts, evidence, and remaining platform limitations.

gopdsdk v0.10.0 - Complete System Integration

gopdsdk v0.10.0

This release completes the offline system and lifecycle integration planned for P10.

System control

• Added copied launch arguments and loaded-game path.
• Added restart with caller-provided launch arguments.
• Added owned 400×240 system-menu images.
• Added auto-lock and crank-sound controls with lifecycle restoration.
• Added mirror-started and mirror-ended lifecycle events.
• Added bounded ordered button callbacks with overflow reporting and termination suppression.

Clock and device environment

• Added current Playdate epoch time with millisecond precision.
• Added epoch/calendar conversion with validation.
• Added an independent high-resolution elapsed timer.
• Added copied OS version, language, and game PDX version information.
• Moved Input.DeltaSeconds to the wrapping monotonic millisecond clock so frame updates no longer reset the public elapsed timer.

Intentional omissions

Low-level delay, allocator, instruction-cache, printf-style formatting/parsing, fatal-error, and raw userdata entry points remain outside the public Go API. They are runtime plumbing or have direct Go equivalents.

Native console logging remains a development facility. FPS remains available through the existing read-only playdate.Display capability without adding a system-owned FPS drawing contract.

Validation

• Full go test ./... and go vet ./...
• Windows, macOS, and Linux native CI
• Linux race detector
• Playdate SDK 3.1.1 Simulator compilation, packaging, and interactive acceptance
• TinyGo conservative hard-float device compilation, linking, relocation validation, and packaging
• Physical Playdate installation and complete P10.1/P10.2 interaction acceptance
• Conservative-GC soak, bounded-memory validation, and unchanged post-run crashlog.txt and errorlog.txt

See MIGRATING.md for adoption guidance and CHANGELOG.md for detailed evidence.

gopdsdk v0.9.0 - Complete Offline Sound

gopdsdk v0.9.0

This release completes gopdsdk’s offline Playdate sound surface.

Highlights

• Owned audio samples with loading, reloading, borrowed data inspection, copying, decompression, playback ranges, and loop callbacks
• Streaming file-player buffering, loop ranges, reload, and underrun controls
• Explicit audio channels, routing, volume, pan, effects, and modulation
• Headphone, headset-microphone, and speaker-output state and control
• Wavetable and custom-generator synthesis
• Envelope controls, LFOs, control signals, instruments, tracks, and sequences
• Bounded update-thread PCM and custom-generator callbacks
• Fixed native callback pools and 4,096-frame rings that prevent Go re-entry from the audio thread
• Sequence, track, note, signal, and controller introspection

Raw generator userdata/function pointers remain intentionally omitted in favor
of bounded portable Go contracts. setMP3StreamSource is also omitted because
Playdate SDK 3.1.1 does not document a shipping-device contract for it;
packaged MP3 playback remains available through FilePlayer.

Compatibility and verification

The verified Windows profile uses:

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain GCC 15.3.1

The release checkout passes the full Go test and vet suites, formatting and
diff checks, Simulator c-shared compilation and packaging, and conservative
hard-float device compilation, linking, relocation checks, and packaging.

Final P9 acceptance covers routing, headphone states, samples, wavetable and
custom synthesis, callbacks, underruns, lifecycle cleanup, conservative-GC
soak, bounded memory growth, and unchanged post-run device logs.

macOS and Linux native Go CI remain supported; official SDK, Simulator, device
build, USB, and physical-device integration on those hosts remain unverified.

See CHANGELOG.md, API.md, MIGRATING.md, and COMPATIBILITY.md for the
complete contracts and evidence.

gopdsdk v0.8.0 - Complete Sprites and Collisions

gopdsdk v0.8.0 completes the offline Playdate sprite and collision surface.

Highlights

• Added sprite geometry and presentation controls:
  • center, bounds, and position getters
  • image flip, draw mode, and opacity
  • stencil images and patterns
  • clip rectangles and draw-offset policy
  • deterministic update and collision enablement
• Added explicitly owned native sprite tilemaps with validated attachment, access, and lifetime behavior.
• Added line and detailed-hit queries, non-mutating collision checks, sprite count, bulk membership operations, remove-all synchronization, and collision-world reset.
• Added bounded per-sprite draw, update, and pair-specific collision-response callbacks.
• Callback registration is limited to 64 slots per context, with deterministic cleanup and suppression after lifecycle termination.
• Expanded examples/spritepresentation into the repository-owned acceptance scene.

All additions are backward-compatible with v0.7.0.

Verification

The release passed:

• formatting, go test ./..., go vet ./..., and git diff --check
• native CI on Windows, macOS, and Linux
• Linux race detector
• external-consumer CLI checks
• official Playdate SDK 3.1.1 Simulator integration on Windows
• conservative hard-float device build
• USB installation and physical Playdate execution
• the complete presentation, query, collision, and callback acceptance matrix
• the required 60-second conservative-GC soak
• bounded memory-growth and unchanged post-run device-log checks

The accepted device artifact uses:

• 283,104 bytes of static RAM
• 1,479,780-byte ELF
• 73,656-byte PDX

Verified toolchain

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain GCC 15.3.1

Official SDK, Simulator, device-build, USB, and physical-device integration remain verified on Windows. macOS and Linux are covered by native CI, but their official SDK and device integration remain unverified.

See CHANGELOG.md, API.md, MIGRATING.md, and COMPATIBILITY.md for the complete contracts and evidence.

gopdsdk v0.7.0 - Complete Graphics and Display

gopdsdk v0.7.0 completes the P7 graphics and display scope.

Highlights

• Advanced drawing state:
  • filled polygons
  • rounded rectangles
  • line-cap styles
  • background color
  • screen-coordinate clipping
• Owned bitmap data access with explicit callback and dirty-tracking contracts
• Bitmap copying, in-place loading, tables, masks, collision, and rotation
• Persistent display-buffer snapshots
• Bounded text layout with wrapping, alignment, tracking, and leading
• Font metrics, glyph access, advance, and kerning
• Display width, height, nominal refresh rate, and measured FPS introspection
• Additive public API: existing v0.6 applications can upgrade unchanged

Verification

The acceptance scenes passed deterministic tests and official Playdate SDK
3.1.1 Simulator execution on Windows.

Conservative-GC hard-float device builds, USB installation, and physical
Playdate execution also passed. The physical soak, bounded-memory,
memory-growth, and post-run device-log checks completed successfully on
2026-08-08.

Full graphics performance regression and isolated visual assertions for every operation remain unverified and are not claimed by this release.

Verified toolchain

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1
• Arm GNU Toolchain GCC 15.3.1

See CHANGELOG.md
for the complete change list and
MIGRATING.md
for upgrade guidance.

gopdsdk v0.6.0 - Advanced Graphics, Video, and Diagnostics

gopdsdk v0.6.0

This release completes P6 with advanced graphics composition, display and
sprite redraw controls, optional PDV video playback, and bounded external-game
diagnostics.

Highlights

• Added playdate.BitmapCompositor for rotated and scaled bitmap drawing.
• Added callback-scoped stencil composition with validated ownership and
  graphics-state restoration.
• Added optional physical-display presentation controls.
• Added global dirty-region policy and per-sprite redraw invalidation.
• Added explicitly owned PDV video players with metadata, frame stepping,
  looping, and screen or offscreen targets.
• Added the allocation-free playdate/diagnostics collector for frame-time
  distributions, live-heap growth, and owned native-resource counts.
• Added deterministic composition, sprite-redraw, and video acceptance scenes.
• Embedded project-owned Simulator and device bridge sources as package assets.
• Preserved the existing playdate.Context contract through optional
  capability interfaces.

Acceptance and verification

The P6 feature set passed:

• Native Go tests and generated Simulator/device ABI regression tests.
• Official Playdate SDK 3.1.1 packaging and Windows Simulator acceptance.
• Conservative hard-float device builds.
• USB deployment and physical Playdate acceptance.
• Comparative full-redraw and dirty-region checks.
• Bounded-memory and native-resource regression checks.
• Physical-device soak and post-run device-log inspection.
• External gopdsdkgame diagnostics runs in the Simulator and on hardware.

The verified toolchain remains:

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain 15.3.1

macOS and Linux native Go CI is covered. Official SDK, Simulator, device-build,
USB, and physical-hardware execution on those hosts remains unverified.

Upgrade

Existing v0.5 applications can update without changing their base
playdate.Context usage:

go get github.com/Djunichi/gopdsdk@v0.6.0

gopdsdk v0.5.0 - Advanced Audio and Microphone Support

Highlights

gopdsdk v0.5.0 completes the P5 advanced audio and music milestone.

This release adds advanced playback controls, audio routing and modulation, synthesizers, instruments, sequencing, effects, permission-gated microphone input, WAV recording, and playback of captured PCM audio.

What’s new

Advanced sample playback controls, fades, and completion callbacks

Owned audio channels and routing graphs

Waveform synthesizers and modulation signals

Instruments, tracks, sequences, and typed audio effects

Permission-gated microphone recording

Separate microphone and audio error domains

Callback-scoped microphone sample access with bounded copying

Device microphone delivery through a bounded native FIFO

Creation of native-owned PCM players from signed 16-bit mono samples

Microphone example with live peak monitoring, recording controls, WAV persistence, and audible playback

Compatibility

Existing v0.4 applications can upgrade without changes. The new functionality is exposed through optional capabilities and does not widen the base playdate.Context interface.

gopdsdk remains pre-v1. Minor releases may contain intentional API changes documented in the release notes and migration guide.

Validation

The release passed:

Full Go test suite

Go vet

Public API and generated ABI regression tests

Official Playdate Simulator microphone acceptance on Windows

Physical Playdate microphone recording, stop/start, WAV saving, and audible PCM playback

Physical-device acceptance for the advanced P5 audio features

The accepted microphone example used 282,824 bytes of static RAM and produced a 50,601-byte hard-float PDX.

See MIGRATING.md for upgrade guidance and COMPATIBILITY.md for detailed evidence and remaining validation boundaries.

gopdsdk v0.4.0 - Persistence and Playdate System Integration

Highlights

gopdsdk v0.4.0 adds durable game state and the Playdate system facilities needed by a complete offline game.

Persistence

• Owned Playdate filesystem operations with portable error classification
• Bounded, checksummed, versioned stores
• Atomic replacement with backup recovery
• Explicit step-by-step save migrations
• Deterministic corruption and failed-write handling

Playdate system integration

• Owned action, checkmark, and options System Menu items
• System language and localized string lookup
• Accelerometer support with explicit enablement
• Battery, power, volume, timezone, clock-format, and reduce-flashing status
• Exit to Launcher through the normal lifecycle path

Optional facilities

• Bounded asynchronous scoreboards API
• Simulator and serial debug-message FIFO
• Callback cleanup and suppression after termination

Integrated acceptance game

Crank Caverns now integrates the complete P1–P4 surface using only public gopdsdk APIs:

• Persistent settings, progress, score, and best time
• Explicit save/load checkpoints
• Continue Run and Start New flows
• Four generations of save-schema migration
• Localized System Menu settings
• Battery status and Launcher exit
• Simulator and physical-device packaging/deployment

Compatibility changes

• Tile-map draw failures continue to classify as both playdate.ErrTileMapDraw and their underlying cause, but no longer concatenate arbitrary cause text.
• Store migration failures continue to classify as store.ErrMigration; their direct cause is also available through errors.Is.
• Device validation now distinguishes unsupported channel operations from safe runtime.chanLen and runtime.chanCap helpers retained by TinyGo reflection tables.

Applications must not parse error strings. Use errors.Is or concrete error types.

Verified profile

• Go 1.26.5
• Playdate SDK 3.1.1
• TinyGo 0.41.1 with LLVM 20.1.1
• Arm GNU Toolchain GCC 15.3.1
• Windows Simulator and conservative-GC device build
• USB installation and device launch through COM3

macOS and Linux native Go behavior is covered by CI. Official SDK, Simulator, and physical-device execution on those hosts remains unverified.

Extended physical-device soak, memory-growth measurement, live configured scoreboards, and injected power-loss testing remain outside this release’s verified evidence.

Upgrading

Existing v0.3 applications can upgrade without adopting the new optional capabilities.

See:

• Migration guide
• Public API
• Compatibility and evidence
• Release procedure