Natu#

Warning

These docs are extremely work in progress!

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.

_images/goodboy.gif _images/xniq.gif

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
    
  1. Install GCC for bare-metal ARM targets

    $ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-gdb
    
  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
    
  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
    
  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
    

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
    

Current status#

In good shape:

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

  • Video hardware

  • Keypad input

  • BIOS routines

  • Timers

  • Interrupt manager

  • Waitstate configuration

  • 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)

  • DMA (currently you need to use the legacy module)

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

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.