📚 Documentation | 🔌 API | 🧑💻 Coding Guide | 🎓 Tutorial | 🧪 Examples | 🧩 Templates | 💬 Discord | 🧵 Forum | 🛠️ Source
Nim for GDExtension — a pure library and CLI tool.
nimble install gdext@0.12.1
mkdir testproject && cd $_
touch project.godot
gdextwiz new-extension MyExtension
gdextwiz run- 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.
-
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 aplugin.cfgfile. 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.
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
Installs the gdext library and its CLI tool gdextwiz.
nimble install gdext@0.12.1
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.
Removes the library and CLI tool:
nimble uninstall gdext
Use gdextwiz to create, build, and run your GDExtension projects from the command line.
📘 For detailed usage and subcommands, see the gdextwiz manual.
- Linux
- Macos
- Windows
- godotengine/godot 4.4.0 or higher
- nim-lang/nim 2.0.12 or higher
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.
Note
Support for other environments depends on community feedback. Please consider contributing your findings!
- OS: Linux (Arch) — Author | Mac M2 — @ArikRahman
- Engine: Godot 4.4.stable.arch_linux | Homebrew Godot 4.4.1 arm64-apple-darwin24.5.0
- Nim: 2.0.12 | 2.0.14 | 2.2.0 | 2.2.4
- CC: gcc version 15.1.1 20250425 (GCC) | clang version 17.0.0
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!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
