gdzig

Idiomatic Zig bindings for Godot 4.

DISCLAIMER

This library is currently undergoing rapid development and refactoring as we figure out the best API to expose. Bugs and missing features are expected until a stable version is released. Issue reports, feature requests, and pull requests are all very welcome.

Prerequisites

Zig 0.17.0
Godot 4.7.2

Note: gdzig currently targets these exact Zig and Godot releases.

WebAssembly

WebAssembly is supported on the above Zig release via the wasm32-emscripten target:

zig build -Dtarget=wasm32-emscripten

See the example for a browser export preset and instructions.

Usage:

See the example folder for reference.

Compile-time Godot compatibility minimum

Default builds discover the running engine version. To fold version gates, interface lookups, and method-bind selection at compile time, select a measured minimum:

zig build -Dgodot_compatibility_minimum=4.6

This is a floor, not an exact engine lock. Matching and newer engines are accepted, and older engines are rejected during initialization. Bindings still come from the current vendored API. With the option, gdzig.api_version points to the constant effective floor rather than the actual runtime version. Cached minima use the vendored metadata directly. An uncached minimum downloads that exact stable Godot release to measure compatibility, without changing the API snapshot. See the compatibility minimum guide for catalog requirements, downstream build usage and limitations.

Code Sample:

gdzig/example/src/GuiNode.zig

Lines 1 to 56 in 1cdfec6

    
           const GuiNode = @This(); 
        
           pub fn register(r: *Registry) void { 
        
               const class = r.createClass(GuiNode, r.allocator, .auto); 
        
               class.addMethod("on_pressed", .auto); 
        
               class.addMethod("on_toggled", .auto); 
        
           } 
        
           allocator: Allocator, 
        
           base: *Control, 
        
           sprite: *Sprite2D = undefined, 
        
           pub fn create(allocator: *Allocator) !*GuiNode { 
        
               const self = try allocator.create(GuiNode); 
        
               self.* = .{ 
        
                   .allocator = allocator.*, 
        
                   .base = Control.init(), 
        
               }; 
        
               self.base.setInstance(GuiNode, self); 
        
               return self; 
        
           } 
        
           pub fn destroy(self: *GuiNode, allocator: *Allocator) void { 
        
               self.base.destroy(); 
        
               allocator.destroy(self); 
        
           } 
        
           pub fn _enterTree(self: *GuiNode) void { 
        
               if (Engine.isEditorHint()) return; 
        
               var normal_btn = Button.init(); 
        
               self.base.addChild(.upcast(normal_btn), .{}); 
        
               normal_btn.setPosition(Vector2.initXY(100, 20), .{}); 
        
               normal_btn.setSize(Vector2.initXY(100, 50), .{}); 
        
               normal_btn.setText(.fromLatin1("Press Me")); 
        
               var toggle_btn = CheckBox.init(); 
        
               self.base.addChild(.upcast(toggle_btn), .{}); 
        
               toggle_btn.setPosition(.initXY(320, 20), .{}); 
        
               toggle_btn.setSize(.initXY(100, 50), .{}); 
        
               toggle_btn.setText(.fromLatin1("Toggle Me")); 
        
               toggle_btn.connect(Button.Toggled, .fromClosure(self, &onToggled)) catch {}; 
        
               normal_btn.connect(Button.Pressed, .fromClosure(self, &onPressed)) catch {}; 
        
               var res_name: String = .fromLatin1("res://textures/logo.png"); 
        
               defer res_name.deinit(); 
        
               const texture = ResourceLoader.load(res_name, .{}).?; 
        
               defer if (texture.unreference()) texture.destroy(); 
        
               self.sprite = Sprite2D.init(); 
        
               self.sprite.setTexture(Texture2D.downcast(texture).?); 
        
               self.sprite.setPosition(.initXY(400, 300)); 
        
               self.sprite.setScale(.initXY(0.6, 0.6)); 
        
               self.base.addChild(.upcast(self.sprite), .{}); 
        
           }

Community

Find us in the gdzig Discord server.

Name		Name	Last commit message	Last commit date
.github		.github
.mise-tasks/example		.mise-tasks/example
.zed		.zed
build		build
doc		doc
docs		docs
example		example
pkg		pkg
src		src
test		test
vendor		vendor
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_STYLE.md		CODE_STYLE.md
LICENSE		LICENSE
MIXINS.md		MIXINS.md
README.md		README.md
build.zig		build.zig
build.zig.zon		build.zig.zon
flake.lock		flake.lock
flake.nix		flake.nix
mise.lock		mise.lock
mise.toml		mise.toml
zlint.json		zlint.json

Navigation Menu

Repository navigation

About

Repository files navigation

gdzig

DISCLAIMER

Prerequisites

WebAssembly

Usage:

Compile-time Godot compatibility minimum

Code Sample:

Community

About

Releases

Packages

Contributors

Languages

	const GuiNode = @This();

	pub fn register(r: *Registry) void {
	const class = r.createClass(GuiNode, r.allocator, .auto);
	class.addMethod("on_pressed", .auto);
	class.addMethod("on_toggled", .auto);
	}

	allocator: Allocator,
	base: *Control,
	sprite: *Sprite2D = undefined,

	pub fn create(allocator: Allocator) !GuiNode {
	const self = try allocator.create(GuiNode);
	self.* = .{
	.allocator = allocator.*,
	.base = Control.init(),
	};
	self.base.setInstance(GuiNode, self);
	return self;
	}

	pub fn destroy(self: GuiNode, allocator: Allocator) void {
	self.base.destroy();
	allocator.destroy(self);
	}

	pub fn _enterTree(self: *GuiNode) void {
	if (Engine.isEditorHint()) return;

	var normal_btn = Button.init();
	self.base.addChild(.upcast(normal_btn), .{});
	normal_btn.setPosition(Vector2.initXY(100, 20), .{});
	normal_btn.setSize(Vector2.initXY(100, 50), .{});
	normal_btn.setText(.fromLatin1("Press Me"));

	var toggle_btn = CheckBox.init();
	self.base.addChild(.upcast(toggle_btn), .{});
	toggle_btn.setPosition(.initXY(320, 20), .{});
	toggle_btn.setSize(.initXY(100, 50), .{});
	toggle_btn.setText(.fromLatin1("Toggle Me"));

	toggle_btn.connect(Button.Toggled, .fromClosure(self, &onToggled)) catch {};
	normal_btn.connect(Button.Pressed, .fromClosure(self, &onPressed)) catch {};

	var res_name: String = .fromLatin1("res://textures/logo.png");
	defer res_name.deinit();

	const texture = ResourceLoader.load(res_name, .{}).?;
	defer if (texture.unreference()) texture.destroy();
	self.sprite = Sprite2D.init();
	self.sprite.setTexture(Texture2D.downcast(texture).?);
	self.sprite.setPosition(.initXY(400, 300));
	self.sprite.setScale(.initXY(0.6, 0.6));
	self.base.addChild(.upcast(self.sprite), .{});
	}

Latest commit

History

Folders and files

Repository files navigation

gdzig

DISCLAIMER

Prerequisites

WebAssembly

Usage:

Compile-time Godot compatibility minimum

Code Sample:

Community

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages