Crate craydate

Expand description

Craydate

This crate and its related crates together provide a safe Rust API for the Playdate hand held gaming system. It is built on the Playdate C Api.

The name is crustacean pun, with our dear friends the crayfishes.

Using these crates requires the Playdate SDK, which has its own license. Install the SDK and add an environment variable named PLAYDATE_SDK_PATH that points to the directory where you installed it, such as PLAYDATE_SDK_PATH=C:\playdate.

This crate uses unstable features in order to provide a #![no_std] application to run on the Playdate simulator and hardware device. Thus it requires use of the Rust nightly compiler.

Getting Started

Building a #![no_std] application that is compiled for the Playdate simulator requires a bit of extra Cargo setup, which we try to make easy for you. The dependency structure of your project will look like this:

- your-game-project**
  ├── [dependencies] your-game** (`#![no_std]` crate)
  |   ├── [dependencies] craydate (`#![no_std]` crate)
  |   └── [dependencies] euclid (with `default-features = false` and `features = ["libm"]`)
  └── [build-dependencies] craydate-build
 
** = is specific to your game and provided by the game developer.

Note that your game’s crate must include the #![no_std] directive in its crate root in order to build for the Playdate device.

The euclid crate is used in the craydate public Apis, which is why you will need it. The features listed above are specified to make the crate compatible with a #![no_std] application.

If you choose not to use the root project crate talked about below, then you do not need the craydate-build in [build-dependencies], but will be responsible to build the pdx image and install it yourself.

The root project crate

We provide an template of a root project crate at craydate-project, which will act as the coordination point to build your game for the Playdate simulator and the Playdate device. To use it, please rename and customize it for your game.

To start using it, download the latest release, unzip it and edit it as follows. See below for more details.

Ensure your PLAYDATE_SDK_PATH environment variable is set to the location of the Playdate SDK.
In the Cargo.toml file, change the name to include your game’s name, such as foo-project for the game crate foo.
In the Cargo.toml file, change the game dependency’s package and path to point to your game’s crate.
In the Cargo.toml file, if you want to use it, change the game-assets dependency’s package and path to point to your game’s asset-generating crate (when you have one, you can leave it commented out with a # for now).
If you have a game-assets dependency for generating assets, uncomment and fix the call to it from src/bin/make_pdx.rs (when you have one, you can ignore this for now).
If you have a game-assets dependency for generating assets, uncomment “game-assets” in the bins feature (when you have one, you can ignore this for now). It would look like bins = ["craydate-build", game-assets"].

Development Workflow

To build your game for the Playdate simulator, simply build your customized root project your-game-project crate with the Cargo --lib flag, which will build your game as a dependency.

After building the game, the root project crate (if based on craydate-project) includes 2 binaries to help you get it onto the Playdate simulator or a hardware device. Build them by building your root project your-game-project crate with the Cargo --bins flag. The binaries are:

make_pdx
run_simulator

make_pdx

Combines your built game, along with any asset files into a pdx image for the device or simulator.

The your-game-assets dependency seen above is an optional place to construct and collect assets for your game that will be included by make_pdx when building the game’s pdx image. To do so, edit the make_pdx.rs file to call your-game-assets. Assets should be collected into env!("PDX_SOURCE_DIR"). For example:

  your_game_assets::generate_assets(env!("PDX_SOURCE_DIR"))?;

The make_pdx binary would then include those assets into your game’s pdx image.

run_simulator

Runs the Playdate simulator, loading the pdx image generated by make_pdx.

VSCode

We provide configurations for VSCode in the template root project craydate-project to build and use the make_pdx and run_simulator binaries correctly. The .vscode/settings.json file configures these tasks. You should not need to change the configuration unless you move the .vscode directory out of the root project crate.

The "projectRootCrate" variable should point to the root project crate. By default, since the .vscode directory is inside that crate, it is ".".
The "rust-analyzer.linkedProjects" variable should point to the root project crate’s Cargo.toml file. By default it is "./Cargo.toml".

When running the simulator with this task, VSCode will capture the stdout and stderr output of the game and write it to a file called stdout.txt in the project’s root directory.

Panics

The Cargo.toml for the root project crate must also set panic = "abort". This is included in the template root project craydate-project crate:

[profile.dev]
panic = "abort"
[profile.release]
panic = "abort"

Otherwise you will get a compilation error:

error: language item required, but not found: `eh_personality`
  |
  = note: this can occur when a binary crate with `#![no_std]` is compiled for a target where `eh_personality` is defined in the standard library

Your first game

Your game’s crate must include a function that will be called after the Playdate system initializes. This function should contain your game’s main game loop. It’s simplest form would look like:

#[craydate::main]
async fn main(api: craydate::Api) -> ! {
  let events = api.system.system_event_watcher();
  loop {
    match events.next().await {
      craydate::SystemEvent::NextFrame { inputs, .. } => {
        // Read inputs, update game state and draw.
      }
      _ => (),
    }
  }
}

Then, handle the various events that can be returned from next(). In particular, handle input, update game state, and draw to the screen when the SystemEvent::NextFrame event happens. You can access the Playdate device through the craydate::Api parameter to main().

Logging to the Playdate simulator’s console, for debugging, is possible through the craydate::log() and craydate::log_error() functions.

Platforms

Currently the craydate project only supports development for the Windows simulator. We will expand support to the Playdate hardware device once we get access to one. Simulators on other platforms (e.g. Mac) are possible, and would only need changes to the root project crate.

The “osx.craydateHostTarget” setting may need to change if you’re working on an ARM-based mac.
The “linux.craydateHostTarget” setting hasn’t been tested to see if it’s correct.
A MacOSX simulator build has not been tested and may not link.
A Linux simulator build has not been tested and may not link.
There’s no VSCode task to install the pdx on a Playdate device yet.
The build for a Playdate device has not been tested yet and may not load at all.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Craydate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Macros

format

Reexport some of alloc, since things in alloc are not guaranteed to work in no_std as it all depends on our global allocator. This makes it clear they can be used, and avoids the need for extern crate alloc elsewhere. Creates a String using interpolation of runtime expressions.

Structs

ActiveFont

A sentinel that marks a font as the currently active font. Destroying this object will unset the font as current.

ActiveMicrophoneCallback

Api

Apis used to access the Playdate device’s display, sound, files, clock, menus, etc.

AudioSample

A buffer of audio data which can be played with a SamplePlayer or as part of a MIDI Instrument in a Synth.

BitCrusher

Bitmap

A bitmap image.

BitmapCollider

Information about a single bitmap, used in testing for collision between two bitmaps opaque pixels.

BitmapData

Metadata for an Bitmap.

BitmapDrawMode

BitmapFlip

BitmapPixels

Provide readonly access to the pixels in an Bitmap, through its BitmapData.

BitmapPixelsMut

Provide mutable access to the pixels in an Bitmap, through its BitmapData.

BitmapRef

A borrow of a Bitmap (or SharedBitmap) is held as this type.

Buttons

The state of all buttons, along with changes since the last frame.

CallbackBuilder

A builder pattern to construct a callback that will later be called when SystemEvent::Callback fires. Connects a closure to a Callbacks object which can later run the closure.

CallbackBuilderWithArg

A CallbackBuilder which includes an argument passed from the system to the callback.

CallbackSource

A SoundSource that is a user-defined function that writes to the audio buffer directly.

Callbacks

Provides an API to run a closure tied to a callback when the SystemEventWatcher reports a callback is ready to be run via SystemEvent::Callback. This type uses its type argument T to define the values that the caller will pass along to the closure when running it.

ClampedFloatInclusive

A floating point value that is clamped to be within LOW and HIGH.

ContextStackId

Holds a reference on an Bitmap that was placed into the context stack. The reference can be used to retrieve that Bitmap on a future frame, after it is released.

Control

A Control signal object is used for automating effect parameters, channel pan and level, etc.

DelayLine

DelayLineTap

A DelayLineTap provides signals that modulate a DelayLine at a position.

Display

Access to the details and configuration of the Playdate device display screen.

Envelope

An Envelope is used to modulate sounds in a Synth.

File

Access to the file system of the Playdate device.

FilePathError

An error performing an operation on a filesystem path.

FilePathTimestamp

A filesystem timestamp, which can represent when a file or folder was last accessed, modified, etc.

FilePlayer

FilePlayer is used for streaming audio from a file on disk.

Font

Font which can be used to draw text when made active with Graphics::set_font().

FontGlyph

Information about a specific character’s font glyph.

FontPage

Information about a set of 256 chars.

FramebufferStencilBitmap

A sentinel that marks a bitmap acting as the stencil for drawing. Destroying this object will unset the bitmap as the stencil.

Graphics

Access to drawing functions to draw to the Playdate device’s screen.

HighResolutionTimer

The system’s high resolution timer. There is only one timer available in the system.

Inputs

The set of all input state and/or changes since the last frame.

Instrument

Instrument collects a number of Synth objects together to provide polyphony.

Language

Lfo

An Lfo (Low-frequency oscillation) is used to modulate sounds in a Synth with a function.

MenuItem

A system menu item. The game can specify up to 3 custom menu items in the system menu.

OnePoleFilter

The OnePoleFilter is a simple low/high pass filter, with a single parameter describing the cutoff frequency: values above 0 (up to 1) are high-pass, values below 0 (down to -1) are low-pass. A OnePoleFilter acts as a SoundEffect which can be added to a

Overdrive

Pattern

A pattern is 8x8 bits of data that repeats over a surface. The pattern includes two pieces of data: 8x8 pixels of black/white colors, and an 8x8 mask which is used to draw the pixel color or omit it. Together this forms an 8x8 tri-state of (draw black, draw white, draw nothing).

Peripherals

PixelColor

A single pixel’s color, either black or white.

PolygonFillRule

RelativeTimeSpan

A span of time with a relative (signed) start and end.

RenameFilePathError

An error when trying to rename a file or folder, which comes with additional context.

RingModulator

SamplePlayer

A SamplePlayer will play an AudioSample.

Sequence

Represents a MIDI music file, as a collection of SequenceTracks that can be played together.

SequenceTrack

A SequenceTrack plays (multiple at a time) notes on an Instrument as part of a full Sequence, which represents a MIDI file.

SolidColor

Sound

Access to the speaker and headphone outputs of the Playdate device, along with the audio clock.

SoundChannel

A channel is where sound is played to, once it has been added to the system via Sound::add_channel(). Sounds can be played into a SoundChannel by attaching a SoundSource with add_source().

SoundEffect

A SoundEffect can be attached to a SoundChannel to filter/mutate the sound being played on it. They all include a mix modulator that allows adjusting how much to mix the SoundEffect into the channel, between replacing the existing signal or leaving it unchanged.

SoundFormat

SoundSource

A SoundSource produces sound that can be played into a SoundChannel, thus playing to the device’s sound outputs.

SoundWaveform

StereoVolume

A volume with two channels: left and right.

String

Reexport some of alloc, since things in alloc are not guaranteed to work in no_std as it all depends on our global allocator. This makes it clear they can be used, and avoids the need for extern crate alloc elsewhere. A UTF-8–encoded, growable string.

Synth

A collection of Synth objects make up an Instrument used to play a MIDI Sequence.

SynthGenerator

The implementation of a generator for a Synth.

SynthGeneratorVTable

A virtual function pointer table (vtable) that specifies the behaviour of a SynthGenerator.

SynthRender

Parameters for the SynthGeneraterRenderFunc.

SynthSignal

A SynthSignal represents a signal that can be used as a modulator for a Synth.

System

Access to Playdate device’s system resources such as the menu, clock, battery state, and system settings.

SystemEventWatcher

An object used to watch for the next system event. Call next() to get the next event when it is ready.

TimeDelta

The difference between two TimeTicks.

TimeSpan

A span of time with an absolute (unsigned) start and end.

TimeTicks

Represents the current device time, which is a monotonically increasing value.

TrackNote

A MIDI note which is played as part of a SequenceTrack in a SequenceTrack.

TwoPoleFilter

TwoPoleFilterType

UnownedBitmapMut

A mutable Bitmap that is not owned by the application, so can only be used as a borrowed BitmapRef.

UnownedBitmapRef

A Bitmap that is not owned by the application, so can only be used as a borrowed BitmapRef.

Vector3

A three-dimensional vector.

Video

A Video file that can be rendered into the display or a Bitmap.

VoiceId

Volume

A volume, which is a value between 0 and 1. Setting it to a value outside the valid range will result in the value being clamped to within 0 and 1.

WallClockTime

Represents a wall-clock time.

Enums

Action

AnyType

AutoLock

The state of the auto-lock system.

Button

The set of input buttons.

ButtonEvent

Events which describe changes in state for a button.

ButtonState

The current state of a button, which indicates if the player is holding the button down or not.

Checkmark

Color

Represents a method used for operations that draw to the display or a bitmap.

Crank

The status of the crank input device.

CrankSounds

Whether using the crank makes sounds when docked or undocked.

Error

The Error type for all errors in the craydate crate.

FilePathStat

Information about a file path in the filesystem.

HeadphoneState

The state of the headphone jack.

LoopTimeSpan

A span of time for sound to loop over.

MicrophoneCallbackOutput

MidiNoteRange

A range of MIDI notes, which can include all notes, a single note, or a contiguous set of notes.

Options

SystemEvent

Playdate device system events.

Constants

LCD_COLUMNS

LCD_ROWBYTES

LCD_ROWS

Traits

AsSoundSource

Provides explicit access to a type’s SoundSource methods when it can act as a SoundSource.

AsSynthSignal

Provides explicit access to a type’s SynthSignal methods when it can act as a SynthSignal.

ToOwned

Reexport some of alloc, since things in alloc are not guaranteed to work in no_std as it all depends on our global allocator. This makes it clear they can be used, and avoids the need for extern crate alloc elsewhere. A generalization of Clone to borrowed data.