cookiecutter-lisp-game

An opinionated cookiecutter template for Common Lisp videogame projects. Contains an empty window with FPS counter, a basic event loop, livesupport for interactive development and deployment matters covered (automated Linux, MacOS and Windows builds).

You can choose the backend middleware library for your project from the following:

• liballegro — the recommended option. Rock-solid stability, a wide range of functionality and decent Common Lisp bindings. The only choice that supports the creation of in-game UIs, via cl-liballegro-nuklear.
• raylib — pretty much dark horse. Lacks proper error handling and doesn’t have a huge lot of functionality, but the code size is the smallest. The library itself requires manual installation, and Common Lisp bindings are only present on Ultralisp. NOTE: untested under MacOS.
• SDL2 — most popular framework, boasting abundant documentation and tutorials. However, Common Lisp bindings are in sorry state, so expect bugs and crashes.

Requirements

Install cookiecutter:

pip install cookiecutter

You’ll obviously need some Lisp implementation (SBCL is preferred) and Quicklisp package manager:

curl -O https://beta.quicklisp.org/quicklisp.lisp
sbcl --non-interactive --load quicklisp.lisp \
  --eval '(quicklisp-quickstart:install)' \
  --eval '(ql-util:without-prompting (ql:add-to-init-file))'

To use the raylib middleware, you’ll additionally need to have Ultralisp installed:

sbcl --non-interactive --eval '(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)'

Usage

cookiecutter gh:lockie/cookiecutter-lisp-game

Dont forget to symlink your project’s directory to Quicklisp’s local projects for local development:

cd your-game
ln -s `pwd` $HOME/quicklisp/local-projects/

After that, you can just (ql:quickload :your-game) in your preferred Lisp IDE, run (main) and start hacking!

IMPORTANT: Push your repo to Github, then go to Settings → Actions → General → Workflow permissions and tick the “Read and write permission” option, otherwise you’ll get “Error 403: Resource not accessible by integration” on build.

To change branding icon, replace package/icon.png with any 256x256 PNG file.

To automatically build packages for supported OSes, just add a tag to a commit and push it to your repo on GitHub; in about 10 minutes they’ll appear in Releases section of your repo.

Projects

The list of projects built with this template:

• Lispy Rogue, an Autumn Lisp Game Jam 2024 entry
• Cycle of Evil, a Spring Lisp Game Jam 2024 entry
• Mana Break, an Autumn Lisp Game Jam 2023 entry
• Thoughtbound, a Spring Lisp Game Jam 2023 entry
• feel free to add your projects here!

License

This project is licensed under the terms of the MIT License.