克雷日期

本库及其相关库共同为 Playdate 手持游戏系统提供安全的 Rust API。它是基于 Playdate C API 开发的。

这个名字是甲壳类动物的玩笑，以我们亲爱的螃蟹朋友们为灵感。

要求

使用这些库需要 Playdate SDK，它有自己的许可证。安装 SDK 并添加一个名为 PLAYDATE_SDK_PATH 的环境变量，该变量指向您安装 SDK 的目录，例如 PLAYDATE_SDK_PATH=C:\playdate。

本库使用不稳定的功能来提供在 Playdate 模拟器和硬件设备上运行的 #![no_std] 应用程序。因此，它需要使用 Rust 夜间编译器。

入门指南

构建为 Playdate 模拟器编译的 #![no_std] 应用程序需要一些额外的 Cargo 设置，我们尽量让它变得简单。你的项目依赖结构将如下所示

- 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.

请注意，你的游戏库必须在它的 crate root 中包含 #![no_std] 指令，以便为 Playdate 设备编译。

craydate 公共 API 中使用了 euclid 库，这就是你需要它的原因。上述列出的功能是为了使库与 #![no_std] 应用程序兼容而指定的。

如果您选择不使用下面提到的根项目crate，则不需要在[build-dependencies]中的craydate-build，但您需要自己构建pdx镜像并安装。

根项目crate

我们在craydate-project提供了根项目crate的模板，它将作为协调点来构建您的游戏，用于Playdate模拟器和Playdate设备。要使用它，请将其重命名并为您自己的游戏进行定制。

要开始使用它，请下载最新版本，解压并按照以下方式编辑。更多详细信息请见下文。

1. 请确保您的环境变量PLAYDATE_SDK_PATH设置为Playdate SDK的位置。
2. 在Cargo.toml文件中，将name更改为包含您游戏的名字，例如，对于游戏crate foo，可以将其更改为foo-project。
3. 在Cargo.toml文件中，将game依赖项的package和path更改为指向您的游戏crate。
4. 在Cargo.toml文件中，如果您想使用它，将game-assets依赖项的package和path更改为指向您的游戏资源生成crate（当您有资源生成crate时，您可以暂时注释掉，使用#）。
5. 如果您有用于生成资源的game-assets依赖项，取消注释并修复从src/bin/make_pdx.rs中对其的调用（当您有资源生成crate时，您可以暂时忽略此步骤）。
6. 如果您有用于生成资源的game-assets依赖项，取消注释bins特性中的"game-assets"（当您有资源生成crate时，您可以暂时忽略此步骤）。它看起来像这样：bins = ["craydate-build", game-assets"]。

开发流程

要为Playdate模拟器构建您的游戏，只需使用Cargo的--lib标志构建您定制的根项目crate your-game-project，这将您的游戏作为依赖项构建。

构建游戏后，根项目crate（如果基于craydate-project）包括2个二进制文件，帮助您将游戏上传到Playdate模拟器或硬件设备。通过使用Cargo的--bins标志构建您的根项目crate your-game-project来构建它们。这些二进制文件是：

• make_pdx
• run_simulator

make_pdx

将构建的游戏和任何资源文件组合成一个pdx镜像，用于设备或模拟器。

上面的your-game-assets依赖项是一个可选的位置，用于构建和收集游戏资源，当构建游戏的pdx镜像时，make_pdx会将其包含在内。要这样做，请编辑make_pdx.rs文件以调用your-game-assets。资源应该收集到env!("PDX_SOURCE_DIR")。例如

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

然后，make_pdx二进制会包含这些资源到您的游戏pdx镜像中。

run_simulator

运行Playdate模拟器，加载由make_pdx生成的pdx镜像。

VSCode

我们在模板根项目 craydate-project 中提供了 VSCode 的配置，以正确构建和使用 make_pdx 和 run_simulator 二进制文件。文件 .vscode/settings.json 配置了这些任务。除非您将 .vscode 目录移动出根项目 crate，否则您不需要更改配置。

• "projectRootCrate" 变量应指向根项目 crate。默认情况下，由于 .vscode 目录在该 crate 内部，因此它是 "."。
• "rust-analyzer.linkedProjects" 变量应指向根项目 crate 的 Cargo.toml 文件。默认情况下它是 "./Cargo.toml"。

运行此任务时，VSCode 将捕获游戏的标准输出（stdout）和标准错误（stderr）输出，并将其写入项目根目录中名为 stdout.txt 的文件。

恐慌

根项目 crate 的 Cargo.toml 必须也将 panic = "abort" 设置。这包含在模板根项目 craydate-project crate 中

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

否则您将得到编译错误

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

您的第一款游戏

您的游戏 crate 必须包含一个函数，该函数将在 Playdate 系统初始化后调用。这个函数应该包含您的游戏的主游戏循环。它的简单形式看起来像

#[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.
      }
      _ => (),
    }
  }
}

然后，处理从 next() 返回的各种事件。特别是，在 SystemEvent::NextFrame 事件发生时，处理输入、更新游戏状态和将内容绘制到屏幕上。您可以通过 craydate::Api 参数来访问 Playdate 设备，该参数在 main() 中。

可以通过 craydate::log() 和 craydate::log_error() 函数将日志记录到 Playdate 模拟器的控制台，用于调试。

平台

目前 craydate 项目仅支持 Windows 模拟器的开发。 我们将一旦获得访问权限，就扩展对 Playdate 硬件设备的支持。其他平台的模拟器（例如 Mac）也是可能的，并且只需更改根项目 crate。

• 如果您在基于 ARM 的 Mac 上工作，可能需要更改 "osx.craydateHostTarget" 设置。
• "linux.craydateHostTarget" 设置尚未测试以确定其正确性。
• MacOSX 模拟器构建尚未测试，可能无法链接。
• Linux 模拟器构建尚未测试，可能无法链接。
• 目前还没有 VSCode 任务在 Playdate 设备上安装 pdx。
• Playdate 设备的构建尚未测试，可能根本无法加载。

许可证

本项目许可方式为以下之一

• Apache License, Version 2.0, (LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0)
• MIT许可证（LICENSE-MIT 或 https://opensource.org/licenses/MIT）

由您选择。

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的，您有意提交给Craydate的任何贡献都将如上所述双授权，不附加任何额外条款或条件。