Factorio MOD Scaffold

This project is a scaffold for creating Factorio MODs.

Prerequisites

On Windows, use WSL2; the scripts and tasks assume a Unix shell and are not expected to work natively. Clone the repository inside the WSL filesystem.

• zsh
• mise
• A configured Git identity (git config user.name and user.email). It becomes the initial commit's author and, when MOD_LICENSE=default_mit, the LICENSE.txt copyright holder.
• GitHub CLI authentication (gh auth login; gh itself is installed by mise) with admin access to the new repository, which ./bin/initialize needs to change repository settings, create the release environment, and set its secret
• A Factorio Mod Portal API key, created at https://factorio.com/profile, with the ModPortal: Publish Mods, ModPortal: Upload Mods, and ModPortal: Edit Mods usages. ./bin/initialize prompts for it to set the FACTORIO_API_KEY secret.
• Optionally, a Claude Code OAuth token from claude setup-token, which authenticates against your Claude subscription. ./bin/initialize prompts for it to set the CLAUDE_CODE_OAUTH_TOKEN secret used by the weekly scaffold-drift workflow. Leave it blank to skip; the workflow no-ops until the secret is set.

Usage

1. Create a new repository from this template

   • On GitHub, click the Use this template button, then clone the new repository
   • Or, using the gh CLI: gh repo create <new-repo-name> --template sakuro/factorio-mod-scaffold --clone

2. cd into the new repository directory

3. Run mise trust

4. Run ./bin/initialize

   The script performs the following:

   1. Install tools via mise install

   2. Generate MOD files (info.json, locale/en/<MOD_NAME>.cfg, changelog.txt)

   3. Replace README.md with the MOD title and template repository link

   4. Download and set up LICENSE.txt based on the specified license

   5. Write release settings (MOD_LICENSE, MOD_CATEGORY, MOD_TAGS) into mise.toml

   6. Write the .scaffold-sync.json baseline for the scaffold-drift workflow

   7. Remove bin/initialize itself, amend the initial commit, and force-push it; the script stops here if either fails, before any GitHub setting is changed

   8. Configure GitHub repository settings

      • Auto-delete merged branches
      • Auto-merge for pull requests
      • GitHub Discussions
      • Repository topics (factorio-mod)
      • Repository website (MOD portal page)
      • Issue labels (project-specific additions; see Issue labels)
      • Workflow permissions
      • release environment
      • FACTORIO_API_KEY secret
      • CLAUDE_CODE_OAUTH_TOKEN secret for the scaffold-drift workflow

   9. Configure branch protection requiring pull requests

   • MOD_LICENSE can be set to customize the license (defaults to default_mit); see License identifier
   • Example: MOD_LICENSE=default_gnulgplv3 ./bin/initialize
   • MOD name, title, and author are derived from the current directory name and the GitHub repository owner; edit info.json and locale/en/<MOD_NAME>.cfg afterward if they need to be different. MOD category and tags are written to mise.toml with their default values (no-category and empty, respectively) and can be edited there.

5. Your MOD scaffold will be ready

Issue labels

GitHub provisions its standard label set (bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix, accessibility) on every new repository. ./bin/initialize adds four project-specific labels:

Label	Color	Description
chore	e4b429	Maintenance, tooling, and housekeeping
test	0e8a16	Tests and test infrastructure
refactor	d4c5f9	Code restructuring without changing external behavior
icebox	add8e6	Parked for the future; not scheduled for work

An initialized repository ends up with 14 labels: the 10 standard ones plus these four.

Scaffold drift

.github/workflows/scaffold-drift.yml runs weekly in each generated MOD and, via Claude Code Action, opens a chore/scaffold-drift PR when this scaffold's shared infrastructure has moved ahead of the MOD. It runs only when the CLAUDE_CODE_OAUTH_TOKEN secret is set, so it does nothing on a fork. Scheduled workflows are disabled by default in a fork (not in a repository generated from the template). See CONTRIBUTING.md for how to review those PRs.