=============================
Nim bindings for Godot Engine
=============================

:Author: Ruslan Mustakov
:Version: |godotnimversion|
:GitHub: `$GODOTNIM_GITHUB_URL <$GODOTNIM_GITHUB_URL>`_

.. contents::

``godot-nim`` library allows to create games on
`Godot Engine <https://godotengine.org/>`_ with
`Nim programming language <https://nim-lang.org/>`_. Nim is a statically typed
language with an elegant Python-like syntax that compiles to native code.
It is garbage-collected, but its GC supports real-time mode which this library
makes use of. It means the GC will never run during game frames and will use
fixed amount of frame idle time to collect garbage. This leads to no stalls
and close to zero compromise on performance comparing to native languages with
manual memory management.

If you are not familiar with Nim yet, it is recommended to go through the
`official tutorial <https://nim-lang.org/docs/tut1.html>`_.

`VSCode <https://code.visualstudio.com/>`_ is the recommended editor for
working with Nim code. It is cross-platform and has the excellent
`nim plugin <https://marketplace.visualstudio.com/items?itemName=kosz78.nim>`_
that supports most of the features you would expect from an IDE.
It also has `godot-tools plugin <https://marketplace.visualstudio.com/items?itemName=geequlim.godot-tools>`_
which adds features for editing GDScript and Godot resource files.


Getting Started
===============

Building Godot
--------------

The library requires a not yet released Godot version 3.0, which you can
build yourself by running the commands below (requires
`Git <https://git-scm.com/downloads>`_,
`Python 2.7 <https://www.python.org/downloads/>`_,
`SCons <http://www.scons.org/>`_):

.. code-block:: bash
   git clone https://github.com/godotengine/godot.git
   cd godot
   scons platform=<your_platform>

where ``<your_platform>`` can be ``windows``, ``osx``, ``x11``. After build
is finished, Godot binaries will be under the ``bin`` folder. More details
about compiling Godot can be found in `Godot documentation
<https://godot.readthedocs.io/en/stable/development/compiling/index.html>`_.


Building Nim
-------------

The library requires a not yet released Nim version 0.17.1, which you can
build yourself by following instructions in the
`Nim repository <https://github.com/nim-lang/Nim>`_. Make sure to also run
``./koch tools -d:release`` after the steps described there to build ``nimble``
(package manager) and ``nimsuggest`` (IDE helper tool,
used by VSCode Nim plugin)


Creating Project
----------------

The fastest way to set up a Godot-Nim project is to use an existing stub:

.. code-block:: bash
   git clone --depth=1 https://github.com/pragmagic/godot-nim-stub.git myproject

(you can then delete the .git directory within to untie the project from the
stub repository)

The stub contains the necessary build configuration to compile your code for
desktop and mobile platforms, as well as a couple of very simple scenes to
help you get started. Consult the stub's `README
<https://github.com/pragmagic/godot-nim-stub>`_ for information about
compiling the project.


Adding Nim to Existing Project
------------------------------

If you would like to use Nim in an existing project:

1. Copy ``nakefile.nim`` file and ``src`` directory from the stub described
   in the previous section above your Godot project folder. Adjust paths in
   build scripts (``nakefile.nim``, ``src/stub.nimble``) according to your
   own project structure.

2. Copy ``project/nimlib.tres`` to your Godot project folder. It is a
   GDNative library resource that contains paths to dynamic libraries
   compiled by Nim.

Next Steps
----------

Once you are familiarized with the build process (it's as simple as running
``nake build`` after you are set up), it is recommended to go through
`godotmacros <godotmacros.html>`_ and `godotnim <godotnim.html>`_ module
documentations. They describe special macros and procedures needed to define
or instantiate Godot objects. After you learned that, the rest is similar to
using any Nim library. These bindings do not limit any of Nim's capabilities,
and you can use any Nim types as fields or parameters of Godot objects and
their procedures (but, obviously, you may not be able to export some of them
to Godot editor or GDScript, unless you define your own converters).


Modules
=======

The binding library consists of three major modules:

* `godot <#modules-godot-module>`_ - Contains core types and macro definitions.
  You need to import this in any module that defines or makes use of Godot
  types.

* `godotinternal <#modules-godotinternal-module>`_ - Contains raw wrappers over
  few core types, such as ``GodotVariant``, ``GodotString``, ``GodotNodePath``,
  ``GodotDictionary``, pool arrays. These are used by ``godotapigen`` and macro
  implementations, and you don't have to use them at all in your code, unless
  you want to go into low-level details for some reason. Each of those types
  needs to be destructed manually with ``deinit`` procedure.

* `godotapigen <godotapigen.html>`_ - Wrapper generator based on data from
  Godot's ``ClassDB``. You only need to use it as a part of the build process.


godot Module
------------

Contains core types and macro definitions. You need to import this in any
module that defines or makes use of Godot types. The sumbodules below are
exported and you don't have to import any of them directly.

* `godotnim <godotnim.html>`_ Defines ``NimGodotObject`` and Varaint converters
  for standard Nim types.
* `godotmacros <godotmacros.html>`_ Defines ``gdobj`` macro for defining
  Godot objects.
* `variants <variants.html>`_ ``Variant`` type represents a "dynamic object"
  that many Godot procedures make use of.
* `arrays <arrays.html>`_ Defines ``Array`` of Variants.
* `basis <basis.html>`_ Defines 3D ``Basis``.
* `colors <colors.html>`_ Defines ARGB ``Color``.
* `dictionaries <dictionaries.html>`_ Defines ``Variant`` -> ``Variant``
  ``Dictionary``.
* `nodepaths <nodepaths.html>`_ Defines ``NodePath`` - a path to a ``Node``.
* `planes <planes.html>`_ Defines 3D ``Plane``.
* `poolarrays <poolarrays.html>`_ Defines pooled arrays: ``PoolByteArray``,
  ``PoolIntArray``, ``PoolRealArray``, ``PoolVector2Array``,
  ``PoolVector3Array``, ``PoolColorArray``, ``PoolStringArray``.
* `quats <quats.html>`_ Defines ``Quat`` (quaternion) describing object
  rotation in 3D space.
* `rect2 <rect2.html>`_ Defines ``Rect2`` - a 2D rectangle.
* `rect3 <rect3.html>`_ Defines ``Rect3`` - a 3D box.
* `rids <rids.html>`_ Defines ``RID`` - a resource identifier.
* `transform2d <transform2d.html>`_ Defines ``Transform2D``.
* `transforms <transforms.html>`_ Defines ``Transform``.
* `vector2 <vector2.html>`_ Defines ``Vector2``.
* `vector3 <vector3.html>`_ Defines ``Vector3``.
* `godotbase <godotbase.html>`_ Defines ``Error`` type and few common math
  procedures missing in Nim's standard library.


Godot API
---------

This is an auto-generated list of Godot API modules. It's built from Godot
changeset `$GODOTAPI_CHANGESET_HASH
<https://github.com/godotengine/godot/commit/$GODOTAPI_CHANGESET_HASH>`_.

$AUTO_GENERATED_GODOTAPI_LIST


godotinternal Module
--------------------

Contains low-level wrappers over Godot types that require manual memory
management. This module is used within ``godot-nim`` implementation and you
don't need to import it unless you know what you are doing.

* `godotdictionaries <godotdictionaries.html>`_
* `godotnodepaths <godotnodepaths.html>`_
* `godotpoolarrays <godotpoolarrays.html>`_
* `godotstrings <godotstrings.html>`_
* `godotvariants <godotvariants.html>`_