Create your own Homebrew game system

Every game system in New Recruit comes from a public GitHub repository. To make your own homebrew version of a game, you copy ("fork") that repository to your own GitHub account, edit it with the New Recruit Data Editor, and share your copy with your players. No programming and no command line are needed.

1. Create a GitHub account
2. Find the repository of the game you want to modify
3. Create a GitHub token
4. Download the Data Editor and the Builder
5. Fork and import the game in the Data Editor
6. Modify the game
7. Publish your changes and test them
8. Share your game with your players

1. Create a GitHub account

GitHub is a free website that stores files and keeps the history of every change. Go to github.com/signup and create an account. Your username will be part of the address of your homebrew, so pick something your players will recognise.

2. Find the repository of the game

Pick the game you want to start from. Your homebrew will begin as an exact copy of it.

Keep this owner/repository name, you will paste it in the Data Editor at step 5.

3. Create a GitHub token

A token is a password that lets the Data Editor create your fork and publish your changes on your behalf. You only create it once.

1. Open GitHub › Settings › Developer settings › Fine-grained tokens (you must be signed in).
2. Give it a name (for example "New Recruit Editor") and an expiration date.
3. Under Repository access, choose All repositories. "Public repositories" is read-only and cannot publish anything.
4. Under Permissions › Repository permissions, set Contents to Read and write and Administration to Read and write (needed to create the fork).
5. Click Generate token and copy it right away: GitHub will never show it again.

Treat the token like a password: never post it on Discord or in a screenshot. If it leaks, delete it on the same GitHub page and create a new one.

4. Download the Data Editor and the Builder

On the Downloads page, under Data Development, download and install the Editor and the Builder for your computer (Windows, macOS or Linux).

On macOS, if you get "App Is Damaged and Can't Be Opened", run xattr -c /Applications/NewRecruit\ Editor.app in a terminal.

5. Fork and import the game in the Data Editor

1. Open the Data Editor, click Settings (top right), paste your token in the GitHub section and click Test.
2. Click Systems, then + Add system ▾ › Import from GitHub.
3. Paste the repository name from step 2, then click Fork to my account & import.

The editor creates the copy your-username/repository on your GitHub account and opens it. If you already forked it, the existing fork is reused.

6. Modify the game

Double-click a catalogue to open it, then change units, costs, options and rules. Use Save All often: saving keeps your work on your computer, nothing is sent to GitHub yet.

To learn the editor itself, see the Data Editor documentation.

7. Publish your changes and test them

1. In the editor, click Commit & push…, describe what you changed and confirm. Your changes are now on your GitHub fork.
2. Open the New Recruit Builder (or the web app), go to Add more games › Add from Github, enter your-username/repository, choose Latest Commit (Head) and click Add.
3. Build a list with your game to check your changes. After each new push, update the game in the Builder to get them.

If the original game is updated, click Pull in the editor to bring the changes into your fork. When a file was changed on both sides, you choose which version to keep.

8. Share your game with your players

Your players add your game the same way you did in step 7, with your fork's name. Or send them this link, which opens the install directly:

Pick a game at step 2 and type your username to get the link.