Godot-Nim v4.1

It enable us to work godot-4.x with Nim.

Based on godot-cpp 4.1 stable

How to use

See test/ to get an overview of the binding interface.

Known Issues

• Initial loading of the extension fails

  Initialization of the extension fails the first time. Reloading solves the problem.

Features

This project is in the early stages of development and some features are not yet operational.

🟢Available

Godot (Editor/GDScript) Side

See GodotSideTester and tester.gd

• Add defined Extension-Class Node into scene
• Instantiate Extension-Class
• Call Extension-Class method
• Use Extension-Class property
• Receive/Emit Extension-Class signal

Nim (GDExtension) Side

See NimSideTester

• Define Extension-Class
• Define Simple Extension-Class method
• Define Extension-Class property
• Define/Emit Extension-Class signal
• Instantiate Engine-Class
• Call Engine-Class method (E.g. Node.get_node)
• Override virtual hooks of Engine-Class (E.g. _ready, _process)
• Call Variants' method

🟡Never tested yet

• Async Dispatch

⚫In progress

• Define utility functions (E.g. print)
• Register user-defined methods
  • Register and call simple method
    • access to self instance
    • access to other arguments
    • return value
  • Support varargs
  • Support static
  • Support virtual
  • Support default-value
• Auto-react to typical notifications
• Define constants
  • Define Variant constants
  • Define Class constants

🟣Planned

• Using Parallelism
• Library hot reloading
• GDScript integration
  • Static conversion from GDScript to Nim (c2nim-like converter)
  • GDScript Embedding

🔴Still can't

• C++ backend
  • Module development

...And so on.

Note

Bridge between Nim's ref and Godot's Refcounted

RefCounted of Godot and Nim's ref are integrated. Every Godot's classes is defined as ref object in this library. RefCounted has =copy, =dup, and =destroy custom hooks defined, which automatically call RefCounted::reference(), RefCounted::unreference(), etc. inside the hooks.

Various ways to fetch Godot's object

Singleton

let obj1: Engine = Engine.singleton
let obj2: Engine = /Engine

Get Node

# getNode(Node, NodePath): Node
let obj1: Control = node.getNode("Control") as Control
# `/`(Node, NodePath): Node = getNode(Node, NodePath)
let obj2: Control = node/"Control" as Control
# `/`(Node, typedesc[SomeNode]): SomeNode = getNode(Node, $SomeNode) as SomeNode
let obj3: Control = node/Control

Vector Swizzling

Godot-nim supports GL-like swizzling operator .*.

To use swizzling, please switch -d:nimPreviewDotLikeOps

let v: Vector3 = [0f, 1, 2]
var v_sub = v.*zxz
assert v_sub == [2f, 0, 2]
v_sub.*xy = [3f, 4]
assert v_sub == [3f, 4, 2]
assert not compiles(v_sub.*xz = [5f, 6])

There are four types of accessors: x, y, z, and w.

Immutable values can be obtained in any combination.

let v2 = v.*zxy
let v3 = v.*xxxxxxxxx

Mutable values can only be retrieved by contiguous accessors (i.e., subsets).

v.*xy = [10f, 11]
v.*yz = [12f, 13]
v.*xyz = [14f, 15, 16]

Though if the original value is immutable, sub-vector will be too.

assert not compiles([1, 2, 3].*xy = [10, 11])

Single accessor represents mutable scalar.

let s: float32 = v.*x
v.*x = 20

Development

engine classes and engine variants are generated by generator/.

Environment

Tested

• Arch Linux
• Ubuntu 20.04.6 LTS on Windows 11 Subsystem