This is a small template project to build games for the Playdate console.
It allows you to program your Playdate app in Lua, Fennel, or a mix of both languages.

• Do I need a Playdate console to be able to make games for it?
  No! The Playdate SDK comes with a simulator, so you can create games for the Playdate even without owning one.
  😎

• babashka ( bb in snippets here) is used to execute build tasks. (It's recommended to add it to your PATH environment variable, so you can invoke it directly from the commandline. Alternatively just chuck the executable in your project directory and add it to the .gitignore.)
• The PlaydateSDK must be available to the build process either via the PLAYDATE_SDK_PATH environment variable, or by explicitly adding its directory path to the config section of bb.edn under :playdate-sdk-path.
• [only when using Fennel]
  The Fennel binary must be available to the build process either by a fennel executable on your PATH environment variable, or by explicitly adding a path for the binary to the config section of bb.edn under :fennel-binary-path.

All the heavy lifting is done by babashka. If you want to adapt this build process for your existing projects, all you need to do is to copy the bb.edn file into your project and maybe adjust the values in the bb.edn's config section according to your needs if necessary. If you also want the automated draft release when you push your changes to GitHub, you just need to copy the .github folder into your project as well.

If you are looking for repositories that make use of this build process and automated releases, look no further. Here are some for you to check out:

• Spin Cross fan edit GitHub repo
  A slightly modified version of jctwizard's brilliant little game "Spin Cross". Go get it on the official itch.io page!
• TBD: Spin Cross fennel port

Whether you want to write your game in Lua or Fennel, the setup is almost the same.
All that's required is a main.lua file in the source folder. By default, this file will serve as the starting point for the Playdate compiler when building your application.

When you want to use Fennel, remember that Fennel files will be compiled to Lua files of the same name, so main.fnl will become main.lua.

Here's how you'd create a "Hello World" program in either language:

function playdate.update()
  playdate.graphics.drawText("Hello *Lua* _World_", 30, 30)
end

(fn playdate.update []
  (playdate.graphics.drawText "Hello *Fennel* _World_" 30 30))

This project template is set up in such a way that you can even use both Lua and Fennel at the same time in your project if you want. For example if you want write your game in Fennel, but still want to use some of the amazing libraries for Playdate that are written in Lua. (Like Noble Engine!)

Just make sure you don't have Fennel and Lua files with the same name sit in the same directory. (for example having a utils/text.lua and utils/text.fnl file)
In such cases, the Lua file will overwrite the compiled Fennel file when the app is built.

To run a full build, start the Playdate Simulator, and have the app available in the main menu of the simulator too, just run the build-copy-sim Babashka task by executing:

bb build-copy-sim

This will compile all Fennel .fnl files (if any) in the source directory to Lua, and copy the compiled Lua files as well as any other files in the source directory into a compiled-source directory. (Note to caution: Any .lua file that has the same name as a .fnl file in the same directory will overwrite its compiled file!)
Then the Playdate compiler pdc will be called with the compiled sources as its input, and creates the PDX app.

(If there are no .fnl files to compile, the compiled-source directory won't be used, and the Playdate compiler will be called with the source directory as its input instead.)

Then the PDX app will be copied into the Simulator's games director to make it available in the Simulator's menu. (So you can check your menu artwork, animations, etc.)

Finally, the Simulator will be started with the PDX app.

I've included a .vscode/tasks.json file with 3 common tasks preconfigured. If you run the default build task (Ctrl+Shift+B), bb build-copy-sim will be run in the terminal.

To create a .pdx.zip file of your game which you can distribute online (for example on itch.io), you execute the following:

bb build-release

This will build the project and pack everything up into a .pdx.zip file in a builds subdirectory.

This template includes a GitHub action, which will create a new release (or update an existing one, depending on how its configured) for the current version in the source/pdxinfo file. By default, this action triggers whenever changes within the source folder are pushed to the main branch. This then will automatically run bb build-release on one of GitHub's machines, and (if the build succeeds) upload a .pdx.zip file of your app to a GitHub release for your current version and build number.
See the :automated-release config section in bb.edn for a bit more details.

If you don't want the automatic release build, you can just delete the .github/workflows/auto-release.yml file.

Near the top of the bb.edn file is a config map, that is used to determine where the different parts of the build process get their input and where they write their output. Here's a description of each config key:

The build-and-sim task is just a convenient predefined combination of the tasks build and start-sim.

Other available tasks are:

You can get the list of all available tasks and what they do by running:

bb tasks

I've put this project under the very permissive MIT License (unless specified otherwise in a file). For your convenience I also put the license text at the bottom of the bb.edn file, so you don't need to bother mention the original copyright and license of the file in your own projects.

When using this repository as a template for your own project, I recommend replacing the LICENSE file with a license of your choice. (Or just remove it if you prefer full restrictive ownership of your code)

If you have any questions feel free to open an issue or contact me on social media:

• Discord: .npexception (formerly NPException#2597)
• Twitter: @NPException