PlaydateKit

PlaydateKit provides Swift bindings for the Playdate C API. It is designed to be "Swift-y" by:

• Replacing error pointers with throwable functions.
• Avoiding manual pointer management and memory management where possible.
• Providing wrapper types for resources like Sprite, Bitmap, and FileHandle that handle automatic allocation and deallocation.
• Adding documentation comments to all functions (derived from the Playdate SDK docs).

PlaydateKit provides several essential modules for game development:

• Display: Manage the screen and visual output.
• Sprite: Handle moving, animated, or interactive game objects.
• System: Interface with Playdate hardware and system-level functions.
• Graphics: Low-level drawing and image manipulation.
• Sound: Play audio and manage sound effects.
• File: Read from and write to the device storage.
• JSON: Parse and generate JSON data for configuration or save files.
• Scoreboards: Manage high scores and player rankings.

To use Xcode for development:

1. Set the Toolchain: Go to Xcode > Toolchains and select the Development Snapshot toolchain.
2. Run the Project: Select the Run icon or press Cmd+R. This automatically triggers the pdc package plugin and launches the Playdate simulator.

Troubleshooting: If the game fails to launch from Xcode, run swift package pdc in the terminal to identify build errors.

PlaydateKit includes a package plugin that handles renaming all necessary files correctly. Use the swift package rename command to change your package name from the default PlaydateKitTemplate to your game's name.

swift package rename --allow-writing-to-package-directory --from PlaydateKitTemplate --to <new-name>

PlaydateKit requires a recent nightly version of the Swift toolchain that supports the Embedded Swift experimental language feature.

It is recommended to use Swiftly to manage these toolchains. Follow these steps to install Swiftly and the latest Swift nightly toolchain:

# Install Swiftly
curl -O https://download.swift.org/swiftly/darwin/swiftly.pkg
installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
~/.swiftly/bin/swiftly init --quiet-shell-followup
. ~/.swiftly/env.sh
hash -r

# Install the latest Swift nightly toolchain
swiftly install main-snapshot

To use PlaydateKit, follow these setup steps:

1. Install a recent nightly Swift toolchain: Use Swiftly and run swiftly install main-snapshot.
2. Install the Playdate SDK: Download from the official Playdate developer site.
3. Initialize a project: Create a new repository using the PlaydateKitTemplate.
4. Build and Run:
   • Use Xcode to build and run directly in the simulator.
   • Or use the CLI command swift package pdc.

When using swift package pdc, the resulting .pdx game file is located at: .build/plugins/PDCPlugin/outputs/PlaydateKitTemplate.pdx.

To build games with PlaydateKit, you must install the official Playdate SDK.

1. Navigate to the Playdate Developer page.
2. Agree to the Playdate SDK License and select Download Playdate SDK.
3. Open and install the downloaded PlaydateSDK.pkg on your system.

To build your package into a .pdx file using the command line, follow these steps:

1. Ensure a compatible Swift toolchain

You must use a recent nightly Swift toolchain. If you use swiftly, run this in your project's root directory:

swiftly install --use main-snapshot

Note: If you manually installed a toolchain, you may need to use $(xcrun -f swift -toolchain "swift latest") instead of swift in subsequent commands.

2. Run the PDC plugin

PlaydateKit provides a pdc package plugin to compile your package into a .pdx file. Run this from your project root:

swift package pdc

3. Locate the output

The resulting .pdx file will be located at: .build/plugins/PDCPlugin/<YourPackageName>.pdx

You can open this file directly in the Playdate simulator.

To start a new project, use the PlaydateKitTemplate repository as a base:

1. Navigate to the PlaydateKitTemplate GitHub repository.
2. Select Use this Template > Create a new repository.
3. Name your new repository and select Create repository.
4. Clone your new repository locally.

In PlaydateKit, you manage your game's lifecycle by subclassing PlaydateGame. This object receives lifecycle events such as gameWillPause and deviceWillSleep.

You must implement the update() method, which returns a Bool (returning true keeps the game loop running).

Example implementation:

import PlaydateKit

final class Game: PlaydateGame {
    init() {
        // Example of adding a menu item to the system checkmark menu
        System.addCheckmarkMenuItem(title: "check me") { isChecked in
            print(isChecked ? "checked!" : "not checked")
        }
    }

    func update() -> Bool {
        System.drawFPS()
        return true
    }

    func gameWillPause() {
        print("Paused!")
    }
}