This Makefile provides a simple, reproducible workflow for building TIC-80 Lua projects from multiple source files. It is designed for small indie or experimental projects where the source code is split into logical parts and then merged into a single
.luacartridge.
The workflow is based on four core ideas:
inc/ directory.inc file defines the build order.lua fileThis approach keeps the codebase modular while remaining compatible with TIC-80’s single-file cartridge model.
project-root/
├── inc/
│ ├── core.lua
│ ├── player.lua
│ └── world.lua
├── impostor.inc
├── Makefile
└── README.md
inc/ contains all Lua source fragments<project>.inc defines the order in which files are merged<project>.lua is generated automatically.inc FileThe .inc file is a plain text file listing Lua source files in build order:
core.lua
player.lua
world.lua
The order matters. Files listed earlier are concatenated first and must define any globals used later.
make build
<project>.inc (e.g., impostor.inc)inc/<project>.lua (e.g., impostor.lua)make minify
minify.lua) and uses it to process the concatenated Lua file. The original code is backed up as <project>.original.lua.make export VERSION=1.0.0
VERSION variable.build and minify to ensure the code is ready..tic cartridge (e.g., impostor-1.0.0.tic).impostor-1.0.0.html.zip).impostor.tic, impostor.html.zip) for consistency.make export_assets
<project>.lua file.awk to directly parse the generated <project>.lua and saves the extracted data into inc/meta/meta.assets.lua. This allows visual assets to be tracked in version control as source code.make import_assets
.png files in assets/<type>/.tic80 --cli import command to load each asset into the cartridge.make watch
inc/ directory, the .inc file, and the assets/ directory for changes.fswatch to be installed.make lint
luacheck, and remaps line numbers back to the original source files for accurate error reporting.make docs
ldoc to process the compiled <project>.lua file and outputs HTML documentation into the docs/ directory.make install_precommit_hook
.git/hooks/pre-commit that runs make lint.make clean
<project>-*.tic)<project>-*.html.zip)<project>.lua)<project>.original.lua)These targets are designed for automated continuous integration (e.g., Woodpecker CI). Each target reads the version from the .version file created by ci-version.
make ci-versioninc/meta/meta.header.lua.main/master) for development builds (e.g., dev-1.0.0-feature-foo)..version file for subsequent steps.make ci-lintmake lint to statically analyze the Lua source files.make ci-minifymake minify to build the project and minify the output.<project>.lua (minified) and <project>.original.lua (pre-minification backup).make ci-docs<project>.original.lua) using ldoc.<project>-1.0.0-docs.zip).<project>-docs.zip) for convenience.make ci-export.version file..tic and .html.zip artifacts.make ci-artifact.lua, .tic, .html.zip, and -docs.zip artifacts to a remote server using scp.sshpass for SSH authentication.DROPAREA_HOST, DROPAREA_PORT, DROPAREA_USER, DROPAREA_TARGET_PATH).make ci-updatecurl to a predefined update server.UPDATE_SECRET) to authorize the request.| File | Description |
|---|---|
<project>.lua |
Merged and potentially minified Lua source |
<project>.original.lua |
Pre-minification source backup |
<project>.tic |
TIC-80 cartridge |
<project>.html.zip |
Packaged HTML build |
<project>-*-docs.zip |
Versioned documentation archive |
<project>-docs.zip |
Latest documentation archive |
maketic80 available in PATHlua (for minification)luacheck (for linting)ldoc (for documentation)fswatch (only for watch mode)sshpass and curl (for CI/CD targets)MIT License — free to use, modify, and redistribute.