Author:	Ruslan Mustakov
Version:	0.5.1
GitHub:	https://github.com/pragmagic/godot-nim

godot-nim library allows to create games on Godot Engine with Nim programming language. 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.

VSCode is the recommended editor for working with Nim code. It is cross-platform and has the excellent nim plugin that supports most of the features you would expect from an IDE. It also has godot-tools plugin 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, Python 2.7, SCons):

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.

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. 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:

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 for information about compiling the project.

Adding Nim to Existing Project

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

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.
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 and godotnim 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 - Contains core types and macro definitions. You need to import this in any module that defines or makes use of Godot types.
godotinternal - 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 - 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 Defines NimGodotObject and Varaint converters for standard Nim types.
godotmacros Defines gdobj macro for defining Godot objects.
variants Variant type represents a "dynamic object" that many Godot procedures make use of.
arrays Defines Array of Variants.
basis Defines 3D Basis.
colors Defines ARGB Color.
dictionaries Defines Variant -> Variant Dictionary.
nodepaths Defines NodePath - a path to a Node.
planes Defines 3D Plane.
poolarrays Defines pooled arrays: PoolByteArray, PoolIntArray, PoolRealArray, PoolVector2Array, PoolVector3Array, PoolColorArray, PoolStringArray.
quats Defines Quat (quaternion) describing object rotation in 3D space.
rect2 Defines Rect2 - a 2D rectangle.
rect3 Defines Rect3 - a 3D box.
rids Defines RID - a resource identifier.
transform2d Defines Transform2D.
transforms Defines Transform.
vector2 Defines Vector2.
vector3 Defines Vector3.
godotbase 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 81dde2687f2f80f5f365a02d68913322d35e9be1.

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.

Nim bindings for Godot Engine