Löve

LÖVE (also known as Love2D) is a framework for making 2D games in Lua. It is lightweight, flexible, and well-suited for rapid iteration, prototyping, and small to medium-sized games.

Website: https://love2d.org

Makefile

This Makefile provides a simple, reproducible workflow for building Love2D projects for both native distribution and web-based execution via love.js. It is designed for indie game development with automated version management and CI/CD deployment support.

Overview

The workflow is based on four core ideas:

• Lua source code is syntax-checked and packaged into .love files
• Web distribution is handled by bundling the .love package with love.js
• Version management is handled automatically from metadata.json or git commit hash
• CI/CD targets enable automated build, versioning, and deployment

This approach keeps the build process simple while supporting both desktop and web platforms.

Configuration Variables

Usage

Build (default)

make build

• Ensures the bin/ directory exists
• Performs a syntax check on all .lua files using luac
• Helps catch basic errors before packaging

Build .love Package

make love

• Packages the project files into a standard Love2D .love archive
• Automatically excludes development files like .git, Makefile, and the dist/ folder
• Output: dist/love2ddemo.love

Build Web Version

make web

• Requires the love target to be run.
• Downloads the love.js engine from a remote repository
• Assembles a web-ready bundle in dist/web/
• Patches the index.html and player.js to correctly load the game and reference the proper project paths

Export

make export VERSION=1.0.0

• Requires a VERSION variable.
• Builds both the .love package and the web version
• Packages everything into versioned ZIP archives:
  • love2ddemo-1.0.0.love.zip
  • love2ddemo-1.0.0.html.zip
• Cleans up temporary build files after packaging

Watch Mode

make watch

• Watches the project directory for changes to .lua files
• Automatically triggers the build target on any change
• Requires fswatch to be installed

Clean

make clean

• Removes generated build artifacts:
  • bin/ directory
  • dist/ directory

CI/CD Targets

make ci-version

• Extracts version from metadata.json (if exists) or uses git short commit hash
• Checks the current git branch
• If the branch is not main or master, prefixes version as dev-<version>-<branch>
• Writes the final version to .version file for use in subsequent CI steps

make ci-export

• Reads version from .version file
• Runs make export with the stored VERSION
• Generates versioned ZIP packages for distribution

make ci-upload

• Reads version from .version file
• Uploads the generated ZIP files and metadata.json via SCP to a remote server
• Requires environment variables:
  • DROPAREA_SSH_PASSWORD - SSH password
  • DROPAREA_PORT - SSH port
  • DROPAREA_USER - SSH username
  • DROPAREA_HOST - Server hostname
  • DROPAREA_TARGET_PATH - Target directory on server

make ci-update

• Reads version from .version file
• Sends HTTP requests to update server for both love and love-web platforms
• Requires environment variables:
  • UPDATE_SERVER - Update server URL
  • UPDATE_SECRET - Authentication secret

Generated Artifacts

Requirements

• make
• luac (for syntax checking)
• zip (for packaging archives)
• curl (for downloading love.js)
• unzip (for extracting love.js)
• sed (for patching web files)
• fswatch (only for watch mode)
• sshpass and scp (for ci-upload target)
• jq (for parsing metadata.json in ci-version)
• git (for version fallback and branch detection in ci-version)

Pipeline

This document describes the Woodpecker CI pipeline used to build, export, upload, and publish a Love2D game project.

Overview

The pipeline logic is almost entirely encapsulated within a Makefile, which is called by each pipeline step. This approach simplifies the CI configuration and keeps the build logic centralized.

The pipeline performs the following steps:

1. Version Extraction: Extracts the game version from metadata.json or git commit hash.
2. Build & Export: Packages the game into a .love file and creates a web-compatible bundle using love.js.
3. Upload Artifacts: Uploads the generated archives and metadata to a remote server.
4. Notify Update Server: Triggers a remote service to publish the new version for both native and web platforms.

Each step corresponds to a make ci-* target.

Step 1: Version Extraction

- name: version
  image: alpine
  commands:
    - apk add --no-cache git make jq
    - make ci-version

What it does:

• Uses a minimal Alpine Linux image.
• Installs git, make, and jq for processing metadata.
• Runs make ci-version, which:
  • Reads the version from metadata.json (if exists) or falls back to git short commit hash.
  • Checks the current branch.
  • If on a development branch (not main or master), prefixes the version as dev-<version>-<branch>.
  • Saves the final version to .version file for subsequent steps to use.

Step 2: Build & Export

- name: export
  image: alpine
  commands:
    - apk add --no-cache zip make curl unzip
    - make ci-export

What it does:

• Uses a minimal Alpine Linux image.
• Installs zip, make, curl, and unzip for fetching dependencies and packaging.
• Runs make ci-export, which:
  • Reads the version from the .version file.
  • Packages the project into a .love file.
  • Downloads and prepares love.js to create a web-compatible version of the game.
  • Patches the web player and HTML files with the project name and version.
  • Packages both the .love file and the web folder into ZIP archives: love2ddemo-<version>.love.zip and love2ddemo-<version>.html.zip.

Step 3: Artifact Upload

- name: upload
  image: alpine
  environment:
    DROPAREA_HOST: vps.teletype.hu
    DROPAREA_PORT: 2223
    DROPAREA_TARGET_PATH: /home/drop
    DROPAREA_USER: drop
    DROPAREA_SSH_PASSWORD:
      from_secret: droparea_ssh_password
  commands:
    - apk add --no-cache make openssh-client sshpass
    - make ci-upload

What it does:

• Installs make and SSH tooling (openssh-client, sshpass).
• Runs make ci-upload, which:
  • Reads the version from the .version file.
  • Copies metadata.json to love2ddemo-<version>.metadata.json.
  • Uploads the .love.zip, .html.zip, and .metadata.json files to a remote server using scp.
  • Uses environment variables for SSH credentials (stored as secrets).

Step 4: Update Notification

- name: update
  image: alpine
  environment:
    UPDATE_SERVER: https://games.vps.teletype.hu
    UPDATE_SECRET:
      from_secret: update_secret_key
  commands:
    - apk add --no-cache make curl
    - make ci-update

What it does:

• Installs make and curl.
• Runs make ci-update, which:
  • Reads the version from the .version file.
  • Sends two HTTP requests to the update server (one for love and one for love-web) with query parameters:
  • secret - Authorization token
  • name - Project name (love2ddemo)
  • platform - Platform identifier (love or love-web)
  • version - Version from .version file
  • This notifies the server that a new build is available for publishing.

Example request:

https://games.vps.teletype.hu/update?secret=<SECRET>&name=love2ddemo&platform=love&version=1.0.0

Result

After a successful run:

• The game is packaged into a native .love distribution and a web-ready bundle.
• All archives are versioned according to project metadata or source control.
• Artifacts are uploaded to the distribution server.
• The public game index is updated automatically for all supported platforms.

This pipeline enables fully automated Love2D releases where the entire build and release logic is managed by the project's Makefile.