Skip to content

Commit

Permalink
Add links to craydate-project and craydate-build
Browse files Browse the repository at this point in the history
  • Loading branch information
@danakj
danakj committed Apr 26, 2022
1 parent 47334a6 commit 641c191
Show file tree
Hide file tree
Showing 2 changed files with 198 additions and 156 deletions.
177 changes: 99 additions & 78 deletions craydate/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,22 @@ This crate and its related crates together provide a safe Rust API for the
The name is crustacean pun, with our dear friends the crayfishes.

# Requirements
Using these crates requires the [Playdate SDK](https://play.date/dev/), which has [its own
license](https://play.date/dev/sdk-license). Install the SDK and add an environment variable
named `PLAYDATE_SDK_PATH` that points to the directory where you installed it, such as
Using these crates requires the [Playdate SDK](https://play.date/dev/),
which has [its own license](https://play.date/dev/sdk-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
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](https://doc.rust-lang.org/1.2.0/book/nightly-rust.html).

# 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:
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**
Expand All @@ -33,86 +35,98 @@ project will look like this:
** = 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.
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.
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](TODO: link) in `[build-dependencies]`, but will be responsible to build the pdx
image and install it yourself.
If you choose not to use the root project crate talked about below, then you
do not need the [craydate-build](https://github.com/danakj/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](TODO: link), 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.
1. Ensure your `PLAYDATE_SDK_PATH` environment variable is set to the location of the Playdate
SDK.
1. In the `Cargo.toml` file, change the `name` to include your game's name, such as
`foo-project` for the game crate `foo`.
1. In the `Cargo.toml` file, change the `game` dependency's `package` and `path` to point to
your game's crate.
1. In the `Cargo.toml` file, remove or change the `game-assets` dependency's `package` and
`path` to point to your game's asset-generating crate (when you have one, you can comment it
out with a `#` for now).
1. If you kept the `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).
We provide an template of a root project crate at
[craydate-project](https://github.com/danakj/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.
1. Ensure your `PLAYDATE_SDK_PATH` environment variable is set to the
location of the Playdate SDK.
1. In the `Cargo.toml` file, change the `name` to include your game's name,
such as `foo-project` for the game crate `foo`.
1. In the `Cargo.toml` file, change the `game` dependency's `package` and
`path` to point to your game's crate.
1. In the `Cargo.toml` file, remove or change the `game-assets` dependency's
`package` and `path` to point to your game's asset-generating crate (when
you have one, you can comment it out with a `#` for now).
1. If you kept the `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).

### 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.
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](TODO: link))
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:
After building the game, the root project crate (if based on
[craydate-project](https://github.com/danakj/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.
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
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:
```rs
your_game_assets::generate_assets(env!("PDX_SOURCE_DIR"))?;
```

The **make_pdx** binary would then include those assets into your game's pdx image.
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**.
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](TODO: link)
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`.
We provide configurations for VSCode in the template root project
[craydate-project](https://github.com/danakj/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`.

### Panics

The `Cargo.toml` for the root project crate must also set `panic = "abort"`. This is included in
the template root project [craydate-project](TODO: link) crate:
The `Cargo.toml` for the root project crate must also set `panic = "abort"`.
This is included in the template root project
[craydate-project](https://github.com/danakj/craydate-project) crate:
```
[profile.dev]
panic = "abort"
Expand All @@ -128,9 +142,9 @@ error: language item required, but not found: `eh_personality`

## 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:
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:
```rs
#[craydate::main]
async fn main(api: craydate::Api) -> ! {
Expand All @@ -145,36 +159,43 @@ async fn main(api: craydate::Api) -> ! {
}
}
```
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()`.
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.
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.
**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.
* 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.
* 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](LICENSE-APACHE) or
https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
* MIT license ([LICENSE-MIT](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.
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.
Loading

0 comments on commit 641c191

Please sign in to comment.