Zig Template for Playdate

Fork

This is a hard fork of the zig template creating a framework for debug tools like Dear ImGui

Overview

Write your Playdate game in Zig! Use this template as a starting point to write your games in Zig. The build.zig will allow you to generate a Playdate .pdx executable that will work both in the simulator and on hardware.

Things To Be Aware Of

• Not Everything Has Been Tested

  • With zig translate-c and a bunch of customization by hand, I converted the C API of the Playdate SDK to Zig. While I have battle tested a lot of the APIs in my upcoming Pictoblox game and in my port of UPWARD, there is much of the API here that has not been tested -- especially, the Sprite, JSON, Synth, and Sound Effect APIs. If something isn't working, please check against the headers in the Playdate SDK C API and make sure the APIs match. Please open a bug report if the APIs don't match.

• Not Officially Supported

  • While it works very well due to its interoperability with C, Zig is not officially supported on the Playdate. If you are having any issues, feel free to open a bug report here.

• Be Mindful Of The Stack

  • You only get 10KB of stack space. That's it. I have not tested much of Zig's std on the Playdate, but std was not designed for a stack this small. See how far you can get, but you might want to write a lightweight "toolbox" library, like I did for UPWARD. std.fmt.bufPrintZ works well, though!.

Requirements

• Either macOS, Windows, or Linux.
• Zig compiler 0.15.1 or 0.15.2. Pulling down the latest build from master is your best bet. UPDATE: Due to changes in build.zig API, this currently doesn't build on 0.16.x. I will update this repo once 0.16.x is released.
• Playdate SDK 3.0.0 or later installed.
• On windows Visual Studio C++ build tools

Contents

• build.zig -- Prepopulated with code that will generate the Playdate .pdx executable.
• src/playdate_api_definitions.zig -- Contains all of the Playdate API code. This is 1-to-1 with Playdate's C API
• main.zig -- Entry point for your code! Contains example code that draws the Zig logo and inverts the screen colors when "A" is held.
• panic_handler.zig -- The default Zig panic handler will cause the simulator and hardware to crash without any error message. I wrote my own handler, so panics should now be handled gracefully with proper error messages. UPDATE: As of Playdate OS 3.0.0, the panic handler currently crashes on the simulator. See the 2nd TODO in panic_handler.zig for more details.
• pdxinfo -- This contains all of the metadata for your game. Panic provides documentation for this file here.
• assets/ -- This folder will contain your assets and has an example image that is drawn to the screen in the example code in main.zig.
• vs-code-launch-config -- This contains instructions and starter configuration files for running and debugging your game on Visual Studio Code. I also made a video on how to do this as well.

Cross Compilation

Zig natively supports cross-compilation. This is leveraged to not only generate an executable that runs on the Playdate hardware, but also to generate a PDX that works across all supported OSs regardless of what OS the game is compiled on. So, any PDX generated by this template should run on the Playdate Simulator on either macOS, Windows or Linux, and also run on Playdate hardware.

NOTE for Intel Mac users: PDXs generated by this template on Windows, Linux, and M1 Macs will only run on M1 Macs. However, if you compile on an Intel Mac, it will generate a PDX that runs on Windows, Linux, and Intel Macs. But it will not run on M1 Macs. When compiling on an Intel Mac, change FORCE_COMPILE_M1_MAC in build.zig to force the template to generate that run M1 Macs instead of Intel Macs. Of crucial note: if a PDX runs on an M1 Mac, it will not run on Intel Mac, and vice versa.

Run Example Code

1. Make sure the Playdate SDK is installed, Zig is installed and in your PATH, and all other requirements are met.
2. On windows in your developer powershell for vs run editbin /STACK:10000000 "${env:PLAYDATE_SDK_PATH}\\bin\\PlaydateSimulator.exe" to increase the stack size of the simulator.
3. Make sure the Playdate Simulator is closed.
4. Run zig build run.
   1. If there any errors, double check PLAYDATE_SDK_PATH is correctly set.
5. You should now see simulator come up and look the screenshot here.
6. When you quit out to the home menu, change the home menu to view as list and you should see the "Hello Zig" program with a custom icon like here.
7. Optionally, connect your Playdate to the comupter and upload to the device by going to Device -> Upload Game to Device.. in the Playdate Simulator.
   1. It should load and run on the hardware as well!

Other Notes

• You can generate a release build with either zig build -Doptimize=ReleaseFast or zig build -Doptimize=ReleaseSafe for a slightly slower build than ReleaseFast but with safety checks like array out-of-bounds checking. For a Playdate game, you probably want ship a ReleaseFast.

Screenshot

Home Screen List View