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 yourPATH
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 ofbb.edn
under:playdate-sdk-path
. - [only when using Fennel]
The Fennel binary must be available to the build process either by afennel
executable on yourPATH
environment variable, or by explicitly adding a path for the binary to the config section ofbb.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:
language | main file name | file content |
---|---|---|
|
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:
ββββββββKeyββββββββ | Description |
---|---|
:release-name |
The name that the zip file will get which is created by the build-release task. Can take placeholders for values from the pdxinfo file. |
:playdate-sdk-path |
The location of the Playdate SDK. If this is empty, the build process will try to get the path from the PLAYDATE_SDK_PATH environment variable. |
:fennel-binary-path |
The location of the Fennel binary. If this is empty, the build process checks if fennel is available on the PATH environment variable. |
:sources |
A list of possible directories in which all your code and asset files are expected to be. The first directory found will be used. |
:fennel-macros |
A path relative to the :sources directory where Fennel macro modules are kept. These are only used by Fennel during compilation, and will not be compiled themselves. Non-.fnl files will still be picked up by the Playdate compiler if present. |
:compiled-sources |
The directory where the combination of compiled .fnl files and copies of all other files in the :sources directory will be put by the compile task. It is also the directory that is used as input for the Playdate compiler. If there are no .fnl files to compile, this directory is unused. |
:main-file |
A relative path to the Lua file with which the Playdate compiler will start compilation. This is usually the file which defines the playdate.update() function. (If your main Fennel file is game.fnl , then put game.lua as the main file.) |
:build-output |
The directory where the PDX app built by the Playdate compiler will be put. |
:automated-release |
Options that are use by the automated-release GitHub action. See the comments on that section in bb.edn for details. |
The build-and-sim
task is just a convenient predefined combination
of the tasks build
and start-sim
.
Other available tasks are:
ββββββββTaskββββββββ | Description |
---|---|
clean-compiled |
Deletes the directory generated via the compile task. |
compile |
Compiles all Fennel files using fennel and copies all other files to the :compiled-sources directory. Does nothing if there are no .fnl files in the project. |
clean |
Removes the PDX build output directory |
create-pdx |
Builds all files in the :compiled-sources directory into a Playdate PDX app. |
build |
Compiles Fennel (if necessary) and builds everything into a Playdate PDX app. |
copy-pdx-to-sim |
Copies the PDX app to the Playdate simulator's games directory, so it can be selected in the simulator's menu. |
start-sim |
Starts the Playdate simulator with the PDX app in the build output directory |
build-and-sim |
Calls the build task and then starts the Playdate simulator. |
build-copy-sim |
Calls the build and copy-pdx-to-sim tasks, then starts the Playdate Simulator. |
build-release |
Increments the buildNumber in pdxinfo (if sources changes since last release), calls build and puts the resulting PDX app in a zip. The name of the zip is determined by the :release-name config key. |
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