The Panic Playdate is a tiny, just-for-fun indie game console. Rust is a drop-in replacement for C that is fast and memory safe. This post will discuss getting started with the Panic Playdate using Rust. It is a follow-up to my post on getting started with Playdate.

crank and crankstart will be used because they are working, existing solutions for using Rust to develop applications for the Playdate. The post will cover installation, running examples, as well as building and running a couple of existing crankstart projects: Klondike solitaire, and Nine Lives.

Familiarity with Rust and the command line are assumed. It is also assumed that the Playdate SDK has already been installed from the Playdate Developer Page and that Rust has been installed with rustup.

Software Versions

$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-10-04 18:23:42 +0000
$ uname -vm
Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 12.6
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
Copyright (C) 2007 Free Software Foundation, Inc.
$ cat "${HOME}/Developer/PlaydateSDK/VERSION.txt"
1.12.3
$ cargo --version
cargo 1.66.0-nightly (f5fed93ba 2022-09-27)

Instructions

Installation

First, install crank according to the README.

PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crank.git
cd crank
cargo install --path . --force

Next, clone the crankstart repository to run the examples.

PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crankstart.git

Running Examples

The hello_world and life examples can simply be run.

PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
EXAMPLE="hello_world"
crank run --release --example "${EXAMPLE}"
EXAMPLE="life"
crank run --release --example "${EXAMPLE}"

Assets from the C_API need to be copied in before running the sprite_game example.

cp -a "${PLAYDATE_SDK_PATH}/C_API/Examples/Sprite Game/Source/images/." sprite_game_images
EXAMPLE="sprite_game"
crank run --release --example "${EXAMPLE}"

Klondike Solitaire

The author of crank and crankstart wrote a Klondike solitaire game in Rust. Use the following commands to build and run it.

PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crankstart-klondike.git
cd crankstart-klondike
crank run --release

Nine Lives

A third party, bravely, wrote the Nine Lives game in Rust. It can be built and run as follows.

PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:bravely/nine_lives.git
cd nine_lives
crank run --release

Running on Hardware

cargo-xbuild is required to build for hardware.

cargo install cargo-xbuild

xbuild requires source to be installed, so it needs to be installed with rustup.

rustup component add rust-src

The build subcommand takes a –device flag that can be used to target hardware exclusively. Alternatively, the package subcommand can be used to build binaries for both the device and the simulator. To upload a PDX file to hardware, first, run it in the simulator. Then either “Upload Game to Device” from the “Device” menu or Playdate icon on the lower lefthand corner of the simulator (with the crank controls collapsed). Once the game is on the device, pdutil can be used to launch it.

# example (build)
EXAMPLE="life"
PDX_FILE="Life"
PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank build --device --release --example "${EXAMPLE}"
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device > Upload Game to Device
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"

# example (package)
EXAMPLE="hello_world"
PDX_FILE="Hello World"
crank package --example "${EXAMPLE}"
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device > Upload Game to Device
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"

# project (build)
PROJECT="crankstart-klondike"
PDX_FILE="Klondike"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank build --device --release
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device" > "Upload Game to Device"
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"

# project (package)
PROJECT="nine_lives"
PDX_FILE="Nine Lives"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank package
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device" > "Upload Game to Device"
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"

The run subcommand should work like the build subcommand, but it is not working on the author’s machice in the latest version of the SDK. The latest version of the SDK also seems to have trouble booting PDX files with spaces in the filename using the simulator and pdutil, but the game can be launched on the device after it has been uploaded.

# example
EXAMPLE="sprite_game"
PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank run --device --release --example "${EXAMPLE}"

# project
PROJECT="nine_lives"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank run --device --release

More Information

Note that the Playdate C API documentation (and to a lesser extent, the Lua documentation) are useful when developing applications in Rust. This post is based on the Rust development thread from the Playdate Developer Forum.

References: