godot-nim/gdext

📚 Documentation | ⚛️ DeepWiki | 🧪 Examples | 💬 Discord | 🧵 Forum | 🛠️ Source

---

Nim for GDExtension — a pure library and CLI tool.

Quick start

nimble install gdext
mkdir testproject && cd $_
touch project.godot
gdextwiz new-extension MyExtension
gdextwiz run

Features

• Access all classes and methods provided by the engine directly from Nim.
• Define new extension classes that inherit from engine classes and expose them to the editor and GDScript.
• Add new methods, signals, properties, and enums to your extension classes and expose them as needed.
• Define and expose virtual functions, which can be overridden in both Nim and GDScript.
• Reload recompiled GDExtensions without restarting the editor (Hot Reloading).
• More expressive arithmetic operations (e.g., vectors) than Godot’s defaults — GLSLang-style swizzling is also supported.
• Includes a CLI tool for creating new extensions, compiling, running projects, and more — all from a single interface (see wiki - gdextwiz).
• Generate class references from comments and annotations in the code.
• Web platform support via Emscripten.

Limitations

• Editor plugins cannot be written using pure Nim alone.
  To create an editor plugin, your extension class must be properly wrapped in GDScript and integrated via a plugin.cfg file. This setup is currently not automated.

• Due to engine constraints, Nim code is executed only when called from the engine.
  It is not possible to run Nim as a standalone Godot application entry point.

vs. GDScript

Nim and GDScript have very similar syntax, making porting between them relatively straightforward.

# Nim import gdext import gdext/classes/[gdSprite2D, gdInput] type MySprite2D* {.gdsync.} = ptr object of Sprite2D speed: float = 400 angular_speed: float = PI method process(self: MySprite2D; delta: float64) {.gdsync.} = var direction = 0 if Input.is_action_pressed("ui_left"): direction = -1 if Input.is_action_pressed("ui_right"): direction = 1 self.rotation = self.rotation + self.angular_speed * direction * delta var velocity: Vector2 if Input.is_action_pressed("ui_up"): velocity = Vector2.Up.rotated(self.rotation) * self.speed self.position = self.position + velocity * delta

# GDScript extends Sprite2D var speed = 400 var angular_speed = PI func _process(delta): var direction = 0 if Input.is_action_pressed("ui_left"): direction = -1 if Input.is_action_pressed("ui_right"): direction = 1 rotation += angular_speed * direction * delta var velocity = Vector2.ZERO if Input.is_action_pressed("ui_up"): velocity = Vector2.UP.rotated(rotation) * speed position += velocity * delta

Guntur Sarwohadi (@guntur-ctech) reports that optimizing the build configuration for a simple port can yield performance gains of up to 6×.

https://github.com/guntur-ctech/simulation-performance-comparison

Commands

install

Installs the gdext library and its CLI tool gdextwiz.

nimble install gdext

The gdextwiz tool will be installed to ~/.nimble/bin, which is automatically added to your PATH if you've installed Nim via the official method.

uninstall

Removes the library and CLI tool:

nimble uninstall gdext

CLI Tool: gdextwiz

Use gdextwiz to create, build, and run your GDExtension projects from the command line.

📘 For detailed usage and subcommands, see the gdextwiz manual.

Supported environments

OS

• Linux
• Macos
• Windows

Engine

• godotengine/godot 4.5.0 or higher

Nim compiler

• nim-lang/nim 2.0.12 or higher

  Macos

  Use Nim installed via Homebrew, not choosenim. This is because Godot requires a native AArch64/ARM64 binary, while choosenim installs an x86_64 version that runs via Rosetta emulation.

Tested by author and maintainers

Note

Support for other environments depends on community feedback. Please consider contributing your findings!

• OS: Linux (Arch) — Author | Mac M2 — @ArikRahman
• Engine: Godot 4.5.stable.arch_linux | Homebrew Godot 4.4.1 arm64-apple-darwin24.5.0
• Nim: 2.2.0 | 2.2.2 | 2.2.4 | 2.2.6
• CC: gcc version 15.1.1 20250425 (GCC) | clang version 17.0.0

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors: