You've stumbled across a barely functional, wildly incomplete and basically undocumented Rust crate whose aim is to let you write games for the Playdate handheld gaming system in Rust.
This software is not sponsored or supported by Panic.
To use this crate, you'll also need to install the crank command line tool.
From the crankstart directory where you found this README,
crank run --release --example hello_world
Should launch the simulator and load in the hello_world sample.
If you have a device attached to your desktop,
crank run --release --example hello_world --device
Should launch the hello_world sample on the device.
For the sprite_game example one needs to copy the images folder from "PlaydateSDK/C_API/Examples/Sprite Game/Source/images"
to "sprite_game_images"
.
Using this system for your own project requires some setup:
- Follow the setup for
crank
with Rust nightly'sno_std
support. - Start a new rust library project with
cargo new --lib project_name
git clone git@github.com:pd-rs/crankstart.git
at the same depth as your new project.- Go into the new project, and add the following to your
Cargo.toml
:
[package.metadata.cargo-xbuild]
memcpy = false
sysroot_path = "target/sysroot"
panic_immediate_abort = false
[profile.dev]
panic = "abort"
opt-level = 'z'
lto = true
[profile.release]
panic = "abort"
opt-level = 'z'
lto = true
[lib]
crate-type = ["staticlib", "cdylib"]
[dependencies]
crankstart = { path = "../crankstart" }
crankstart-sys = { path = "../crankstart/crankstart-sys" }
anyhow = { version = "1.0.31", default-features = false }
euclid = { version = "0.22.9", default-features = false, features = [ "libm" ] }
hashbrown = "0.14.0"
[dependencies.cstr_core]
version = "=0.1.2"
default-features = false
features = [ "alloc" ]
- Add a
Crank.toml
at the same level as yourCargo.toml
, with this minimum:
[[target]]
name = "project_name"
assets = [
]
assets
should be a list of paths to any/all assets you need copied into your project, such as sprites, music, etc.
- Inside your
lib.rs
, you only need to implement thecrankstart::Game
trait to your game's core state struct, then callcrankstart::crankstart_game!
on that struct. See theexamples
folder for examples. - To run the project, from its root, you should now be able to
crank run
successfully!
If you want an example of an independent project following these conventions, go check out Nine Lives.
If there's a newer Playdate SDK available that updates the C API, the crankstart bindings should be updated to match. Here's a guide.
- Install the dependencies for bindgen.
- Install bindgen-cli.
- Install the gcc-arm-none-eabi toolchain, either manually or through a system package, which may also be named something like "cross-arm-none-eabi-gcc".
- On Linux, install the 32-bit glibc development package, which will be called something like
glibc-devel-32bit
. - Install the new Playdate SDK, and if it's not at the default MacOS path, set
PLAYDATE_SDK_PATH
to where you unzipped it. (This should be the directory that containsC_API
,CoreLibs
, etc.) - Run
./scripts/generate_bindings.sh
- Inspect the changes to
crankstart-sys/src/bindings_*
- they should reflect the updates to the Playdate C API. If nothing changed, double-check that the C API actually changed and not just the Lua API. - Submit a PR with the changes :)