godot-go: Go bindings for Godot 4.7
Go bindings for the Godot Game Engine cross-platform game engine. godot-go integrates into Godot through the Godot GDExtension API through cgo.
The project is currently under heavy development. The API should be considered __EXPERIMENTAL__ and is subject to change. The API is expected to become more stable as we get closer to a 1.0 release.
Current State of the Project
Here are some high level bullet points:
- You must have a minimum of Godot 4.7.
- The tests confirm basic functionality.
- The bindings are more than likely leaking memory.
- Not all variant types have been tested.
- Go to godot-go-demo-projects to look at demo projects running a mix of godot-go and GDScript classes.
Getting Started
Requirements:
- clang-format
- gcc
- go 1.25.x
- goimport
Building Godot-Go
In order for godot-go to work correctly, you must make sure the godot_headers are in sync between your godot binary and godot-go. Development is built and tested off of Godot 4.7.
# Install go dependencies make installdeps
# exports the latest gdextension_interface.h and extension_api.json from the godot binary GODOT=/some_path/bin/godot make update_godot_headers_from_binary
# generates code for wrapping gdextension_interface.h and extension_api.json make generate
# build godot-go make build
Alpine / musl libc
On musl-based systems such as Alpine Linux, godot-go builds as-is with the optional
C-side backtrace printing compiled out (musl provides no execinfo interface). Alpine's
package repositories ship no installable execinfo implementation, so capture stays
compiled out there unless you supply one: build or obtain a library providing the
glibc-compatible execinfo interface (execinfo.h plus the backtrace /
backtrace_symbols symbols) and point the build at it:
make build EXTRA_CGO_CFLAGS='-DGODOT_GO_ENABLE_EXECINFO -I/path/to/execinfo/include' EXTRA_CGO_LDFLAGS='-L/path/to/execinfo/lib -lexecinfo'
On glibc and Apple systems nothing extra is needed; the backtrace path is selected
automatically. On Windows, capture is compiled in by default and uses the same
PE/COFF libbacktrace copy that Godot bundles for MinGW builds. It reads the DWARF
embedded in the extension DLL, so no PDB or CodeView link step is needed and the
DLL does not import dbghelp.dll. Frames in the DLL print
function (file:line) (ip 0x…); frames in other modules keep the
module.dll+0xoffset (ip 0x…) form. The test suite proves capture end-to-end on
every CI platform with a narrow probe window (stacktrace-probe capture=<0|1>);
on Windows capture=0 now means the build is broken. The vendored copy is
BSD-3-Clause; see pkg/log/libbacktrace/LICENSE and its README.md for
provenance.
Captured frames resolve offline to function plus file:line — feed any printed
module+0xoffset to Go's own resolver against the debug-built library:
echo 0x536e61 | go tool addr2line test/demo/lib/libgodotgo-test-linux-amd64.so
Use go tool addr2line, not GNU addr2line, which effectively hangs on the
Go DWARF in these debug builds. Inside the probe window the Go side also
prints its own stack (stacktrace-probe go-stack), giving live file:line for
Go frames on every platform, including ones where native capture is stubbed
out.
The same works for Windows frames against the DLL from the windows-test-lib
CI artifact — that platform wants addresses rebased onto the library's
preferred image base, which llvm-objdump -p reports:
BASE=$(llvm-objdump -p libgodotgo-test-windows-amd64.dll | awk '/ImageBase/{print "0x"$2}') echo $((BASE + 0x987ad)) | go tool addr2line libgodotgo-test-windows-amd64.dll
The DLL carries DWARF for both C and Go frames; no PDB is produced or shipped.
Test
Once the project successfully builds, run the following commands to generate cached files for the test demo project for the first time (don't be concerned if it fails):
GODOT=/some_path/bin/godot make ci_gen_test_project_files
From here on out, you will just need to run the following command to iteratively test:
GODOT=/some_path/bin/godot make test
This will run the demo project in the test directory.
The expected output can be found in the CI logs.
Documentation
A living doc of godot-go is maintained at docs/overview.md.
Contact
I'm happy to help out anyone interested in the project. Please leave a message in the Discussion boards or you can add me (surgical#3758) as a friend on the Godot Engine Discord servers. I primarily frequent the gdnative-dev room.
References
- Go 101 article on Type-Unsafe Pointers
- Cheatsheet for cgo data type conversion
- Cross compilation with cgo with xgo
- vscode-go patch to support cgo
- Check unsafe pointer conversion
- Loading nativescript libraries with a godot server build requires manual modification to the library .tres.
- Working with GDB Go extension