Skip to content

Free games for graphing calculators: NumWorks, TI-Nspire CX, Casio fx-CG50 and soon TI-84 Plus CE. Balatro, Celeste, Hollow Knight, Minecraft and more.

6.8 KB
Raw Blame

Contributing to NumPlay

Thanks for wanting to help! Bug reports, game ideas, fixes, translations and whole games are all welcome. This page says how, from setting up your computer to opening a pull request.

Just want to make your own NumWorks game? Read Make your own NumWorks game: it starts from NumPlay's template and doesn't need any of the rules below.

Before you start

  • Found a bug? Open a bug report with your calculator's model and software (Settings, then About), the NumPlay version and what happened.
  • Want a game? Check the roadmap first, then ask for it, one game per issue.
  • Want to make a game for NumPlay? Open an issue first and say what you'd like to build and how. Space on the calculator is short, so we'll agree on where it goes (inside NumPlay or as its own app) before you spend time on it.
  • Want to work on an issue? Say so in a comment and it's yours: an issue with someone assigned is taken, any other is free. Issues are assigned only to whoever is working on them.
  • Want to talk it over first? Use Discussions: what you're working on, questions, ideas. Changes to main are listed under commits; pull before you start.
  • Small fixes (a typo, a crash, a clearer key hint) can go straight to a pull request.

Set up your computer

NumPlay builds on macOS, Linux and Windows.

git clone https://github.com/Mason363/NumPlay.git
python3 NumPlay/tools/setup.py

tools/setup.py gets the ARM compiler, nwlink and the Python packages into ~/.numplay and tells you the one line that puts them on your PATH (source ~/.numplay/env.sh on macOS and Linux). On macOS, run xcode-select --install first if make is missing. Rust is needed only for Tetris: rustup.rs, then rustup target add thumbv7em-none-eabihf. On Windows, python tools/build.py builds NumPlay natively (--doctor checks your setup), or use WSL.

Then:

Command What it does
make -j4 NWLINK=nwlink NumPlay, its versions and every game on its own, in build/
make check NWLINK=nwlink Checks that NumPlay fits the calculator's space and every game its RAM
make lang NWLINK=nwlink The French and Chinese versions
make -C games/<game> NWLINK=nwlink One game on its own
make -C games/<game> test That game's tests on your computer (most games have them)
python3 tests/test_games.py build/compiled/games Plays every app in the emulator and checks its saves
python3 tools/emu.py app.nwa --ms 5000 --shots 2000 --out shots Runs any .nwa in the emulator and takes pictures
python3 tools/emulator.py app.nwa The emulator in a window, to play with the mouse and keyboard; --live rebuilds as you save
python3 tools/build.py Builds everything and puts the finished apps in build/compiled/ (--game ID for one game, --watch to build again when you save)

How the code is laid out

Folder What's in it
launcher/ NumPlay itself: the home screen, settings, saves, the 2D drawing every small game shares
games/<game>/ One game: src/ (with icon.png), Makefile, README.md, docs/ pictures, lang/ translations, tests/
games/common/ What every game uses: Home safety, files, text, compression
games/games.json The games in NumPlay, in the launcher's order, with their colours and screenshots
sdk/template/ Star Catcher, the template new games start from
tools/ Builders, the emulator, icons, translations, sizes
tests/ Tests of NumPlay and every app
docs/ How to play, the guide to making games, the pictures

A small game inside NumPlay follows Block Blast's pattern (games/blockblast): built with -DNP_MODULE=1, it draws with the launcher's gfx_* functions and fonts and saves with np_file_read and np_file_write, so it costs only its rules and its screen. On its own it compiles those files in. tools/new_game.py "My Game" --numplay starts one this way.

A big game builds as its own .nwa (like games/finalearth2), with a build for your computer to test it. It's built with -DEPSILON_XL=1, so in a NumPlay that goes past the calculator's app area (Nwagra) it still finds its saves.

What every game needs

  • Faithful to what it's based on: its rules, numbers, levels and look. Nothing cheap, nothing important missing.
  • Keys anyone gets: arrows move, OK or EXE acts, Back pauses or goes back, Home quits from anywhere. The keys are written on the screen whenever there's something to learn.
  • A pause menu in the game's own look, with Quit game, which asks first.
  • An icon of 55 x 56 pixels with NumPlay's rounded corners: python3 tools/icon.py picture.png games/<game>/src/icon.png. For a port, start from the original's own icon.
  • Saves that always come back: packed bytes with a magic and a version number; old versions read or reset cleanly, never a crash. Save on Home, on quitting and every so often while playing.
  • Every calculator: it runs on the N0110, N0115 and N0120 (the first two are 2.5 times slower: keep the game's speed with a fixed tick rate and catch-up), fits the RAM (make check), and says so if it needs more than Upsilon gives (107 KB).
  • Speed: 30 frames a second on the N0120.
  • Honest credits: the original's makers, every borrowed picture, font and library, and "not affiliated with" them.

Translations

Texts players read are marked T("...") in the code. Each game has lang/fr.txt and lang/zh.txt: one line per text, the English, a tab, then the translation. make lang builds NumPlay in French and Chinese from them. To fix or add a translation, edit those files; new texts in the launcher go in launcher/lang/.

Testing

Before a pull request:

  1. make -C games/<game> test if your game has tests, and add some if it hasn't: its rules against the original, a scripted playthrough, and a few hundred random-key runs that must not crash.
  2. Run it in the emulator (tools/emu.py), also with --model n0110.
  3. make -j4 check NWLINK=nwlink if you touched NumPlay or a game inside it.
  4. Play the first minute as someone who has never seen the game.

If you can, try it on a real calculator too, and say which one in the pull request.

Pull requests

  • One subject per pull request: a fix, a game, a translation.
  • Say what it does, how you tested it (computer, emulator, which calculator) and include a screenshot or GIF for anything you can see.
  • Keep the README's plain style if you change it: short sentences a beginner understands.
  • By sending a pull request you agree that your code is shared under NumPlay's GPL-3.0 license.

Thank you!