Natu

Warning

These docs are extremely work in progress! (They’re getting better though!)

Natu is a toolkit for creating Game Boy Advance games in the Nim programming language.

It has the following goals:

  • Expose the entirety of the GBA hardware in Nim.

  • Make low-level operations short and readable.

  • Simplify asset conversion (sprite gfx, backgrounds, music and sound).

  • Provide useful building blocks for a variety of games.

Goodboy Galaxy xniq A Rushed Hack Job

Installation

Follow the steps below for your OS.

  1. Install GCC for bare-metal ARM targets

    $ sudo apt install gcc-arm-none-eabi

  2. Install Nim (1.4 or higher)

    Via choosenim (makes it easier to switch between Nim versions)

    $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh

    Or via apt:

    $ sudo apt install nim   # Requires Debian 11 (Buster), Ubuntu 21 (Hirsute), or higher.

  3. Install Natu

    $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

  1. Install GCC for bare-metal ARM targets

    $ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-gdb arm-none-eabi-newlib

  2. Install Nim

    Via choosenim (makes it easier to switch between Nim versions)

    $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh

    Or via pacman:

    $ sudo pacman -S nim nimble

  3. Install Natu

    $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

  1. Install the GNU Arm Embedded Toolchain

    Due to problems with the latest version, it’s best to use the October 2021 release for now:

  1. Install Nim

    Via scoop:

    $ scoop install nim

    Or manually:

    Download the latest release from the Nim website.

    Unzip to a location of your choice and run finish.exe.

    Warning

    Windows Defender and other antivirus software may detect the Nim binaries as a false positive.

    If you notice nimble.exe, nim.exe or finish.exe disappearing from the installation, you should add an exception in your antivirus settings. To do this in Windows Defender, go to:

    Start -> Windows Security -> Virus & Threat Protection -> Manage Settings -> Add or Remove Exclusions.

  2. Install Natu

    $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

  1. Install the Arm GNU Toolchain

    Via Homebrew:

    $ brew tap ArmMbed/homebrew-formulae
$ brew install arm-none-eabi-gcc

    Or MacPorts:

    $ sudo port install arm-none-eabi-gcc

  2. Install Nim

    Via choosenim (makes it easier to switch between Nim versions)

    $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh

    Or via Homebrew:

    $ brew install nim

    Or MacPorts:

    $ sudo port install nim

  3. Install Natu

    $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

These instructions should work for pretty much any OS:

  1. Install the GNU ARM Embedded Toolchain

    Grab the October 2021 release, unzip and add it to your PATH.

  2. Install Nim

    Get the latest release from the Nim website, unzip the folder.

    On Windows, you can run finish.exe to take care of the rest, otherwise:

    • Unzip and add the bin folder to your PATH.

    • Ensure you have a standard C compiler for your platform, which Nim will use to compile the tools that come with Natu.

  3. Install Natu

    $ nimble install https://git.sr.ht/~exelotl/natu

Examples

Some simple examples can be found at https://git.sr.ht/~exelotl/natu-examples

Current status

In good shape:

  • Asset conversion for sprites, backgrounds, music and sounds.

  • Video hardware

  • Keypad input

  • BIOS routines

  • Timers

  • Interrupt manager

  • Waitstate configuration

  • DMA

  • Tonc Surface wrapper (draw to tiles like a canvas)

  • Tonc Text Engine wrapper

  • Maxmod Sound System wrapper

  • Posprintf wrapper for efficient string formatting

  • Sin/Cos/Div LUTs + other math functions

  • Fixed-point numbers, 2D vector types

Needs improvement:

  • Logging interface (only mGBA supported currently)

Needs major work:

  • Low-level sound module (not yet published)

  • Serial IO (only the registers are exposed in the legacy module)

Contributing

The source code for Natu and this website are both hosted on Sourcehut, where contribution is done with patches via mailing list. This workflow absolutely sucks, but there is a tutorial if you want to try it.

Alternatively, here’s a much easier way to contribute (basic git knowledge required):

  1. Create a bundle with all changes up to your latest commit. For example, if you branched off devel and worked on branch foo, you can simply run git bundle create MyBundle devel..foo

  2. Send the bundle file to me (by email, Discord, or however you like).

  3. I’ll review it and merge the changes, or give feedback.

Thanks

  • Text engine and many foundations from Tonc + libtonc by Jasper Vijn

  • Interrupt manager from libugba by Antonio Niño Díaz

  • Malloc/free from ACSL by Pedro Gimeno Fortea.

  • String formatting from posprintf by Dan Posluns.

  • Audio playback from Maxmod by Mukunda Johnson.

  • Image converter depends on NimPNG by Andri Lim.

  • Nim programming language by Andreas Rumpf et al.

  • mGBA emulator by Vicki Pfau

  • Natu Logo by Rik Nicol based on pixel art by Dania Rifki.