.. :hide-toc:

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 <https://nim-lang.org/>`_ 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.*


.. container:: align-center

   .. image:: media/goodboy.gif
      :target: https://goodboygalaxy.com
      :alt: Goodboy Galaxy

   .. image:: media/xniq.gif
      :target: https://exelotl.itch.io/xniq
      :alt: xniq

   .. image:: media/arushedhackjob.gif
      :target: https://pyro-pyro.itch.io/a-rushed-hack-job
      :alt: A Rushed Hack Job

Installation
============

Follow the steps below for your OS.

..
   .. note::
      If you happen to have devkitARM installed globally, then installing the Arm GNU Toolchain is optional (but still recommended).

.. tab:: Debian / Ubuntu

   1. Install GCC for bare-metal ARM targets
      
      .. code-block:: console
      
         $ sudo apt install gcc-arm-none-eabi
   
   2. Install Nim (1.4 or higher)
      
      Via `choosenim <https://nim-lang.org/install_unix.html>`_ (makes it easier to switch between Nim versions)
      
      .. code-block:: console
         
         $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh
      
      Or via apt:
      
      .. code-block:: console
      
         $ sudo apt install nim   # Requires Debian 11 (Buster), Ubuntu 21 (Hirsute), or higher.
   
   3. Install Natu
   
      .. code-block:: console
      
         $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

.. tab:: Arch / Manjaro

   1. Install GCC for bare-metal ARM targets
   
      .. code-block:: console
         
         $ sudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-gdb arm-none-eabi-newlib
   
   2. Install Nim
   
      Via `choosenim <https://nim-lang.org/install_unix.html>`_ (makes it easier to switch between Nim versions)
      
      .. code-block:: console
         
         $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh
      
      Or via pacman:
      
      .. code-block:: console
         
         $ sudo pacman -S nim nimble
   
   3. Install Natu
   
      .. code-block:: console
      
         $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0

.. tab:: Windows
   
   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:
      
      * `installer <https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-win32.exe>`_
      * `zip archive <https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-win32.zip>`_
        (add the `bin` directory to your `PATH` environment variable)
   
   .. 
      1. Install the Arm GNU Toolchain
      
         Via `scoop <https://scoop.sh/>`_:
         
         .. code-block:: console
            
            $ scoop bucket add extras
            $ scoop install gcc-arm-none-eabi
         
         Or `winget <https://docs.microsoft.com/en-us/windows/package-manager/winget/>`_:
         
         .. code-block:: console
         
            $ winget install Arm.GnuArmEmbeddedToolchain
   
   2. Install Nim
   
      Via `scoop <https://scoop.sh/>`_:
      
      .. code-block:: console
         
         $ scoop install nim
      
      Or manually:
      
         Download the latest release from the `Nim website <https://nim-lang.org/install_windows.html>`__.
         
         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*.
      
   3. Install Natu
   
      .. code-block:: console
      
         $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0


.. tab:: macOS
   
   1. Install the Arm GNU Toolchain
   
      Via `Homebrew <https://brew.sh/>`_:
      
      .. code-block:: console
         
         $ brew tap ArmMbed/homebrew-formulae
         $ brew install arm-none-eabi-gcc
      
      Or `MacPorts <https://ports.macports.org/>`_:
      
      .. code-block:: console
      
         $ sudo port install arm-none-eabi-gcc
   
   2. Install Nim
   
      Via `choosenim <https://nim-lang.org/install_unix.html>`_ (makes it easier to switch between Nim versions)
      
      .. code-block:: console
         
         $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh
      
      Or via Homebrew:
      
      .. code-block:: console 
         
         $ brew install nim
      
      Or MacPorts:
      
      .. code-block:: console 
         
         $ sudo port install nim
   
   3. Install Natu
   
      .. code-block:: console
      
         $ nimble install https://git.sr.ht/~exelotl/natu@0.2.0
   

.. tab:: Other
   
   These instructions should work for pretty much any OS:
   
   .. 1. Install the Arm GNU Toolchain
   
   ..    Grab the `latest release <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads>`__,
   ..    unzip and add it to your ``PATH``.
   
   1. Install the GNU ARM Embedded Toolchain
   
      Grab the `October 2021 release <https://developer.arm.com/downloads/-/gnu-rm>`__,
      unzip and add it to your ``PATH``.
   
   2. Install Nim
   
      Get the latest release from the `Nim website <https://nim-lang.org/install.html>`__, 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
   
      .. code-block:: console
      
         $ 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 <https://git.sr.ht/~exelotl/natu>`_ and `this website <https://git.sr.ht/~exelotl/natu-docs>`_ are both hosted on Sourcehut, where contribution is done with patches via mailing list. This workflow absolutely *sucks*, but there is a `tutorial <https://git-send-email.io>`__ 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 <https://www.coranac.com/tonc/text/>`_ + libtonc by **Jasper Vijn**
* Interrupt manager from `libugba <https://github.com/AntonioND/libugba>`_ by **Antonio Niño Díaz**
* Malloc/free from `ACSL <https://codeberg.org/pgimeno/ACSL>`_ by **Pedro Gimeno Fortea**.
* String formatting from `posprintf <http://danposluns.com/gbadev/posprintf/index.html>`_ by **Dan Posluns**.
* Audio playback from `Maxmod <https://maxmod.org/>`_ by **Mukunda Johnson**.
* Image converter depends on `NimPNG <https://github.com/jangko/nimPNG>`_ by **Andri Lim**.
* `Nim <https://nim-lang.org/>`_ programming language by **Andreas Rumpf** et al.
* `mGBA <https://mgba.io/>`_ emulator by **Vicki Pfau**
* Natu Logo by **Rik Nicol** based on pixel art by **Dania Rifki**.


.. toctree::
   :hidden:
   :maxdepth: 1
   
   Source Code <https://git.sr.ht/~exelotl/natu>
   Issue Tracker <https://todo.sr.ht/~exelotl/natu>
   Mailing List <https://lists.sr.ht/~exelotl/natu>
   Discord <https://discord.gg/P2PHwm8rK6>
   IRC <ircs://irc.libera.chat:6697/#natu>

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Tutorial
   
   Project setup <todo>
   The basics <basics>
   FAQ <faq>
.. Sprites <todo>
.. Backgrounds <todo>
.. Music & sound <todo>
.. Adding custom tools <todo>

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: API Docs

   video <video>
   input <input>
   memory <memory>
   irq <irq>
   timers <timers>
   bios <bios>
   math <math>
   utils <utils>
   bits <bits>
   surfaces <surfaces>
   tte <tte>
   posprintf <posprintf>
   mgba <mgba>
   graphics <graphics>
   backgrounds <backgrounds>
   maxmod <maxmod>
   
.. sound <todo>
.. fonts <todo>
.. oamlists <todo>
.. tileengine <todo>
.. textrenderer <todo>
.. labels <todo>