Contribute a Mote game

Built a game on the Mote engine and want it in the gallery? Here's the whole path — fork, build, add your game to the listing, and open a pull request for review. It takes about ten minutes once your game is finished.

1 Fork the repository

A fork is your own personal copy of the project on GitHub, where you're free to make changes without affecting the original.

1. Go to github.com/austinio7116/mote.
2. Click the Fork button near the top-right of the page.
3. On the next screen, leave everything as-is and click Create fork.
4. After a moment you'll land on your copy — the URL now reads github.com/<your-username>/mote. Keep this tab open.

2 Clone your fork to your computer

Cloning downloads your fork so you can work on it locally.

1. On your fork's page, click the green <> Code button, make sure HTTPS is selected, and copy the URL it shows (https://github.com/<your-username>/mote.git).
2. Open a terminal (macOS/Linux: Terminal; Windows: Git Bash, installed with Git) and run — replacing <your-username> with yours:

git clone https://github.com/<your-username>/mote.git
cd mote

Now make a branch — a named workspace for your change, so your main stays clean:

git checkout -b add-mygame

The name after -b is up to you; something like add-yourgame is clear. git checkout -b creates it and switches to it in one go.

3 Add your game to games/

Each game is a self-contained folder under games/. Drop yours in as games/mygame/ with this shape:

Two macros in game.c are the source of truth for your listing — make sure they're set:

MOTE_GAME_META("My Game", "yourname");   // name + author
MOTE_GAME_VERSION("1.0.0");              // bump this every release

4 Build the .mote for the gallery

Build the device binary and copy it into docs/games/ (this is the file players download):

# from the repo root
./tools/mote build games/mygame --device
cp games/mygame/build/MyGame.mote docs/games/MyGame.mote

The .mote filename is your game's name from MOTE_GAME_META with spaces removed (e.g. My Game → MyGame.mote). Run ./tools/mote build games/mygame once first to see the exact name it prints.

5 Add your entry to the listing

The gallery is driven by a GAMES array in docs/games.html. Open it, scroll to the end of that array, and add your game as the last entry (keep the trailing comma tidy):

{id:"mygame", file:"MyGame.mote", name:"My Game", by:"yourname", kb:64,
 guide:"mygame-guide.html",          // optional — omit if you have no guide page
 mp:1,                               // optional — include ONLY if it's 2-player
 tag:"One-line hook for the hero card",
 desc:"A paragraph describing the game — what you do, what's special, the modes."},

• id — lowercase, no spaces (matches your folder name).
• file — must match the .mote you copied into docs/games/.
• kb — rough download size in KB (the build step prints the byte size; divide by 1024).
• tag — the short hook shown on the card. desc — the longer blurb on the hero panel.
• mp:1 — add this only for multiplayer games; it shows the 2P badge.
• guide — only if you also add a docs/<id>-guide.html page. Otherwise leave it out.

6 Regenerate games.json

Don't hand-edit docs/games.json — it's generated. Run the tool, which reads your games.html entry and your .mote (pulling out the embedded version, ABI, size and checksum):

python3 tools/gen_gallery.py

You should see your game printed in the summary, and docs/games.json will now include it. This is the manifest the in-Studio and on-device galleries read, so it has to be regenerated whenever a .mote or listing changes.

7 Commit your work

A commit is a saved snapshot of your changes. Save your game code, the built .mote, and the two listing files together:

git add games/mygame \
        docs/games/MyGame.mote \
        docs/games.html \
        docs/games.json
git commit -m "Add My Game to the gallery"

git add stages the files you want to include; git commit -m "…" saves them with a short message describing the change.

If you added a guide page or gallery images, include those in the git add too (docs/mygame-guide.html, docs/img/gallery/mygame-*.png).

8 Push & open a pull request

Pushing uploads your commit to your fork on GitHub. A pull request (PR) then asks the original project to pull in your change.

Push your branch

git push origin add-mygame

Use the same branch name you created in step 2. If Git asks you to sign in, use your GitHub username and a personal access token as the password (GitHub no longer accepts your account password here).

Open the pull request

1. Go to your fork on GitHub (github.com/<your-username>/mote). A yellow banner usually appears — "add-mygame had recent pushes" — with a Compare & pull request button. Click it. (No banner? Click the Contribute button, then Open pull request.)
2. Check the boxes at the top read: base repository austinio7116/mote base main ← head repository <your-username>/mote compare add-mygame. That means "merge my branch into the main project."
3. Give it a clear title (e.g. "Add My Game to the gallery") and, in the description, a few lines that help the review:
   • What the game is, in a sentence or two.
   • Confirm it builds and plays in the emulator (and on a device, if you tested one).
   • Credit any art, audio, or code you didn't make yourself.
4. Click Create pull request. Done!

Your PR will show up on the main project for review. If changes are requested, just commit and git push again on the same branch — the PR updates automatically. Thanks for building on Mote!