Minimal Fennel Love2D Setup

In the lead up to the semi-annual Autumn Lisp Game Jam I thought I’d look into Phil Hegelberg’s approach to last Aprils Jam, using love2d in concert with fennel. Phil outlines his approach on his blog.

This repo contains the minimal viable setup to get started with Phil Hegelberg’s game design process, plus some additional libraries.

Alternatives

This repo is slowly expanding from a truly minimal setup to one that comes with a few batteries included. If you want a barebones setup to get you started check out: absolutely-minimal-love2d-fennel by @benthor.

If you want to just start coding up some fennel and love with no makefile or manual installation on linux check out love-fennel

Getting Started

The following commands will clone this project and duplicate its structure into a new folder $PROJECT_NAME

git clone https://gitlab.com/alexjgriffith/min-love2d-fennel.git 
./min-love2d-fennel/.duplicate/new-game.sh $PROJECT_NAME

Check out the makefile and conf.lua files in $PROJECT_NAME, updating them with information relevant to your game.

You can enter love . in the $PROJECT_NAME directory to run your game, or make run. If you are on Windows, using lovew . will allow you to use the REPL.

The following lines with Update should be changed in the makefile and love.conf to reflect your game.

VERSION=0.1.0
LOVE_VERSION=11.4
NAME=change-me # Update
ITCH_ACCOUNT=change-me-too # Update
URL=https://gitlab.com/alexjgriffith/min-love2d-fennel # Update
AUTHOR="Your Name" # Update
DESCRIPTION="Minimal setup for trying out Phil Hagelberg's fennel/love game design process." # Update
GITHUB_USERNAME := $(shell grep GITHUB_USERNAME credentials.private | cut -d= -f2) # Optional (needed for Love V 12.0)
GITHUB_PAT := $(shell grep GITHUB_PAT credentials.private | cut -d= -f2) # Optional (needed for Love V 12.0)

love.conf = function(t)
   t.gammacorrect = true
   t.title, t.identity = "change-me", "Minimal" -- Update
   t.modules.joystick = false
   t.modules.physics = false
   t.window.width = 720
   t.window.height = 450
   t.window.vsync = false
   t.version = "11.4"
end

Emacs Setup

Once you install the latest version of fennel-mode, you can run C-u M-x fennel-repl followed by love . to launch a repl.

Default Project Structure

The make process as-is will only compile the contents of the root folder and the lib/ folder+subfolders, so make sure to put your game files in either of those.

Specifically, every .fnl file needed at runtime needs to be situated in the root folder, and every file which is not a .lua or .fnl file needs to be put inside lib/.

In order to use macros, they have to be put in .fnl files inside lib/.

Separate your Code into a /src directory

If you want a more opinionated layout, you can use pass in a --layout parameter when creating your project.

./min-love2d-fennel/.duplicate/new-game.sh $PROJECT_NAME --layout=seperate-source

This build uses gamestate rather than Phil’s approach to scene separation and puts all your .fnl files into a /src directory. It also provides a separate makefile that handles this layout.

Note, any macros will have to be placed in the root of the project or in the lib folder (this can be modified in main.lua)

Presently the only layouts are clone and seperate-source. If you want to make your own check out the .duplicate directory to see how they work.

Release Process

Use make linux, make windows, make mac, or make web to create targets for each platform, or make release to make all four. Check out the makefile for more commands, and remember to edit your game data in it!

Adjusting the screen size

For those of us working with window managers it would be nice if our games behaved while we are developing. Below is code adapted from Phil’s 2022 lisp game jam entry https://codeberg.org/technomancy/lisp-jam-2022/src/branch/main/wrap.fnl . Adapt it to modify your wrap.fnl to handle window resizing automatically and adjust your mouse position.

Note this is not a complete solution. You still need to handle the translation of love.mouse.getPos and love.graphics.inverseTransform. But, if your game dosn’t use those, the snippet below should work out of the box!

;; define the size of your window. From your program's perspective
;; your window will always be this size regardless of size
(local window-w 1280)
(local window-h 720)
(var scale 1)

;; Love provides a handy resize callback. Hook into it to adjust the display size
;; of your window.
(fn love.resize [w h]
  (set scale (math.floor (math.max 1 (math.min (/ w window-w)
                                               (/ h window-h))))))

;; Changing the display size means that you need to translate from the "display size"
;; to the size your game thinks the window is.
(fn love.mousepressed [x y b]
  (when mode.mousepressed
    (safely #(mode.mousepressed (/ x scale) (/ y scale) b set-mode))))

(fn love.mousemoved [x y dx dy istouch]
  (when mode.mousemoved
    (safely #(mode.mousemoved (/ x scale) (/ y scale) (/ dx scale) (/ dy scale)
                              istouch))))

(fn love.mousereleased [x y b]
  (when mode.mousereleased
    (safely #(mode.mousereleased (/ x scale) (/ y scale) b set-mode))))

Targeting the development branch of love (12.0) - LINUX ONLY

You can target the development branch of love (version 12.0) by setting the `LOVE_VERSION` parameter in the makefile to 12.0. Note that because we are working from a github artifact, rather than a release, you will also have to pass in your github username and a github PAT.

Getting a PAT

To download artifacts created by the Github actions CI you will need to get an access token from “settings -> developer settings -> personal access tokens”. The token needs `workflow` and `actions:read` permissions.

Creating a credentials.private file

By default the makefile looks for `credentials.private` in the root directory of the project. `*.private` is part of `.gitignore` so personal information stored here will not be part of the git history or get pushed to a remote server.

The contents should look something like this:

GITHUB_USERNAME=username
GITHUB_PAT=PAT

Note: this is presently linux only, however it may be expanded in the future to cover macos and windows.

Phil’s Modal Callbacks (PMC)

Phil Hegelberg’s exo-encounter-667 is structured using a modal callback system. Each game state has a mode and each mode has a series of specific callbacks.

If you design your game as a series of states in a very simple state machine, for example start-screen, play and end, with unidirectional progression, you can easily separate the logic for each state into state/mode specific callbacks. As an example, in order to have state dependant rendering that differs between start-screen,play and end you could provide a draw callback for each of those states. Similarly if we need state dependent logic and keyboard input we could provide update and keyboard callbacks. As you iterate you can add and remove callbacks and states/modes as needed with very little friction.