gd

package module

v0.0.0-...-e10d1cd Latest Latest Go to latest Published: Sep 17, 2025 License: MIT Imports: 2 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/quaadgras/graphics.gd

Links

Open Source Insights

README ¶

graphics.gd

A cross platform 2D/3D graphics runtime for Go suitable for building native mobile apps, gdextensions, multimedia applications, games and more!

// This file is all you need to start a project.
// Save it somewhere, install the `gd` command and use `gd run` to get started.
package main

import (
	"graphics.gd/startup"

	"graphics.gd/classdb/Control"
	"graphics.gd/classdb/GUI"
	"graphics.gd/classdb/Label"
	"graphics.gd/classdb/SceneTree"
)

func main() {
	startup.LoadingScene() // setup the SceneTree and wait until we have access to engine functionality
	hello := Label.New()
	hello.AsControl().SetAnchorsPreset(Control.PresetFullRect) // expand the label to take up the whole screen.
	hello.SetHorizontalAlignment(GUI.HorizontalAlignmentCenter)
	hello.SetVerticalAlignment(GUI.VerticalAlignmentCenter)
	hello.SetText("Hello, World!")
	SceneTree.Add(hello)
	startup.Scene() // starts up the scene and blocks until the engine shuts down.
}

Why use graphics.gd?

Write shaders in Go!
Unlike C++/C#/GDScript/Rust/Swift, all RIDs, Callables and Dictionary arguments are strongly typed.
A good balance of performance and convenience.
General purpose pure-Go 'variant' math packages, reuse them in any Go project.
After the first build, recompile quickly, with an experience similar to a scripting language.
Easily cross-compile for windows/macos/android/linux/ios/web on any host platform.
Neither Java, nor an Android SDK/NDK is needed to build Android apps.
Neither Xcode nor MacOS is needed to build iOS apps.
Drop in gd command, a cross-platform build tool compatible with GDScript-based Godot projects.

This project is not just a wrapper! graphics.gd has been designed from the ground up to provide a cohesive and curated experience for using Go on top of Godot + GDExtension.

Join us in our active discussions forum with any questions, comments or feedback you may have. Show us what you're building!

You can also help support the project, motivate development and prioritise issues by sponsoring.

Getting Started

The module includes a drop-in replacement for the go command called gd that makes it easy to work with projects that run within the runtime. It enables you to start developing a new project from a single main.go file, to install it, make sure that your $GOPATH/bin is in your $PATH and run:

$ go install graphics.gd/cmd/gd@release

Now when you can run gd run, gd test on the main package in your project's directory, things will work as expected. The tool will create a "graphics" subdirectory where you can manage your assets via the Engine's Editor.

Running the command without any arguments will startup the editor.

If you don't want to use the gd command, you can build a shared library with the go command directly:

$ go build -o example.so -buildmode=c-shared

The gd command is also compatible with standard GDScript-based Godot projects and can be used to initialise export configurations and launch projects on Web, Android and iOS (on any platform). To use it this way, run it from the directory where project.godot is located.

Next Steps

Check out the the.graphics.gd/guide which covers much, much more!

TLDR

Each engine class is available as a package under classdb. To import the Node class you can import "graphics.gd/classdb/Node" There's no inheritance, so to access a 'super' class, you need to call Super() on an extension 'class'. All engine classes have methods to cast to any sub-classes they extend for example AsObject() or AsNode2D().

Methods have been renamed to follow Go conventions, so instead of underscores, methods are named as PascalCase. Keep this in mind when referring to Godot documentation.

https://docs.godotengine.org/en/latest/index.html

Optional arguments are omitted by default, convert an Instance into either the Expanded or Advanced type to use them. ie. for a Node.Instance called node, it can be converted:

Node.Expanded(node).AddChild(...)

Where Do I Find?

Ctrl+F in the project for a specific //gd:symbol to find the matching Go symbol.

* Engine Class           -> `//gd:ClassName`
* Engine Class Method    -> `//gd:ClassName.method_name`
* Utility Functions      -> `//gd:utility_function_name`
* Enum                   -> `//gd:ClassName.EnumName`

NOTE in order to avoid circular dependencies, a handful of functions have moved packages, for example Node.get_tree() (GDScript) has moved to SceneTree.Get() (Go).

Performance

It's feasible to write high performance code with graphics.gd, keep to variant types where possible and avoid allocating memory on the heap in frequently called functions. Advanced instances are available for each class which allow more fine-grained control over memory allocations.

Benchmarks show that Advanced method calls from Go -> Engine do not allocate.

Examples

There are a number of examples in the samples branch. All the samples are designed to be run with gd run without any additional setup.

Supported Platforms

Windows GOOS=windows gd build
Linux GOOS=linux gd build
MacOS GOOS=macos gd build
Android GOOS=android GOARCH=arm64 gd run
IOS GOOS=ios gd run (requires SideStore on the IOS device)
Web GOOS=web gd run

Platform Restrictions

64bit only (arm64 && amd64).
No support for Playstation/Xbox/Switch (achievable in the future with WASI, wasm2c or hitsumabushi).

Contributing

The best way you can contribute to graphics.gd is to try it, this project needs you to find out what's working and what doesn't, so do please let us know of any trouble that you run into! Any examples you can contribute are more than welcome.

The next best thing you can do to help is improve the Variant packages, these are general-purpose packages inspired by the Godot engine's Variant types. Specifically any changes you can make to optimize functionality and/or improve test coverage of these packages is more than welcome.

If you enjoy hunting down memory-safety issues, we would appreciate this.

Thirdly, the project needs more tests to ensure that everything is working, the best way you can guarantee that graphics.gd won't break on you is to contribute tests that cover the functionality you need!

To run the go tests for graphics.gd, cd into the repo and run cd internal && gd test.

Note we are looking for somebody to create benchmarks for the project.

Lastly, spread the word and let people know about graphics.gd!

Licensing

This project is licensed under an MIT license (the same license as Godot), you can use it in any manner you can use the Godot engine. If you use this project for any commercially successful products, please consider financially supporting the project to show your appreciation!

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

gd.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
classdb
AESContext This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard).	This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard).
AStar2D An implementation of the A* algorithm, used to find the shortest path between two vertices on a connected graph in 2D space.	An implementation of the A* algorithm, used to find the shortest path between two vertices on a connected graph in 2D space.
AStar3D A* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments).	A* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments).
AStarGrid2D [AStarGrid2D] is a variant of [AStar2D] that is specialized for partial 2D grids.	[AStarGrid2D] is a variant of [AStar2D] that is specialized for partial 2D grids.
AcceptDialog The default use of [AcceptDialog] is to allow it to only be accepted or closed, with the same result.	The default use of [AcceptDialog] is to allow it to only be accepted or closed, with the same result.
AimModifier3D This is a simple version of [LookAtModifier3D] that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation.	This is a simple version of [LookAtModifier3D] that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation.
AnimatableBody2D An animatable 2D physics body.	An animatable 2D physics body.
AnimatableBody3D An animatable 3D physics body.	An animatable 3D physics body.
AnimatedSprite2D [AnimatedSprite2D] is similar to the [Sprite2D] node, except it carries multiple textures as animation frames.	[AnimatedSprite2D] is similar to the [Sprite2D] node, except it carries multiple textures as animation frames.
AnimatedSprite3D [AnimatedSprite3D] is similar to the [Sprite3D] node, except it carries multiple textures as animation [SpriteFrames].	[AnimatedSprite3D] is similar to the [Sprite3D] node, except it carries multiple textures as animation [SpriteFrames].
AnimatedTexture [AnimatedTexture] is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame.	[AnimatedTexture] is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame.
Animation This resource holds data that can be used to animate anything in the engine.	This resource holds data that can be used to animate anything in the engine.
AnimationLibrary An animation library stores a set of animations accessible through string keys, for use with [AnimationPlayer] nodes.	An animation library stores a set of animations accessible through string keys, for use with [AnimationPlayer] nodes.
AnimationMixer Base class for [AnimationPlayer] and [AnimationTree] to manage animation lists.	Base class for [AnimationPlayer] and [AnimationTree] to manage animation lists.
AnimationNode Base resource for [AnimationTree] nodes.	Base resource for [AnimationTree] nodes.
AnimationNodeAdd2 A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeAdd3 A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeAnimation A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeBlend2 A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeBlend3 A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeBlendSpace1D A resource used by [AnimationNodeBlendTree].	A resource used by [AnimationNodeBlendTree].
AnimationNodeBlendSpace2D A resource used by [AnimationNodeBlendTree].	A resource used by [AnimationNodeBlendTree].
AnimationNodeBlendTree This animation node may contain a sub-tree of any other type animation nodes, such as [AnimationNodeTransition], [AnimationNodeBlend2], [AnimationNodeBlend3], [AnimationNodeOneShot], etc.	This animation node may contain a sub-tree of any other type animation nodes, such as [AnimationNodeTransition], [AnimationNodeBlend2], [AnimationNodeBlend3], [AnimationNodeOneShot], etc.
AnimationNodeExtension [AnimationNodeExtension] exposes the APIs of [AnimationRootNode] to allow users to extend it from GDScript, C#, or C++.	[AnimationNodeExtension] exposes the APIs of [AnimationRootNode] to allow users to extend it from GDScript, C#, or C++.
AnimationNodeOneShot A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeOutput A node created automatically in an [AnimationNodeBlendTree] that outputs the final animation.	A node created automatically in an [AnimationNodeBlendTree] that outputs the final animation.
AnimationNodeStateMachine Contains multiple [AnimationRootNode]s representing animation states, connected in a graph.	Contains multiple [AnimationRootNode]s representing animation states, connected in a graph.
AnimationNodeStateMachinePlayback Allows control of [AnimationTree] state machines created with [AnimationNodeStateMachine].	Allows control of [AnimationTree] state machines created with [AnimationNodeStateMachine].
AnimationNodeStateMachineTransition The path generated when using [AnimationNodeStateMachinePlayback.Travel] is limited to the nodes connected by [AnimationNodeStateMachineTransition].	The path generated when using [AnimationNodeStateMachinePlayback.Travel] is limited to the nodes connected by [AnimationNodeStateMachineTransition].
AnimationNodeSub2 A resource to add to an [AnimationNodeBlendTree].	A resource to add to an [AnimationNodeBlendTree].
AnimationNodeSync An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an [AnimationTree].	An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an [AnimationTree].
AnimationNodeTimeScale Allows to scale the speed of the animation (or reverse it) in any child [AnimationNode]s.	Allows to scale the speed of the animation (or reverse it) in any child [AnimationNode]s.
AnimationNodeTimeSeek This animation node can be used to cause a seek command to happen to any sub-children of the animation graph.	This animation node can be used to cause a seek command to happen to any sub-children of the animation graph.
AnimationNodeTransition Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine].	Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine].
AnimationPlayer An animation player is used for general-purpose playback of animations.	An animation player is used for general-purpose playback of animations.
AnimationRootNode [AnimationRootNode] is a base class for [AnimationNode]s that hold a complete animation.	[AnimationRootNode] is a base class for [AnimationNode]s that hold a complete animation.
AnimationTree A node used for advanced animation transitions in an [AnimationPlayer].	A node used for advanced animation transitions in an [AnimationPlayer].
Area2D [Area2D] is a region of 2D space defined by one or multiple [CollisionShape2D] or [CollisionPolygon2D] child nodes.	[Area2D] is a region of 2D space defined by one or multiple [CollisionShape2D] or [CollisionPolygon2D] child nodes.
Area3D [Area3D] is a region of 3D space defined by one or multiple [CollisionShape3D] or [CollisionPolygon3D] child nodes.	[Area3D] is a region of 3D space defined by one or multiple [CollisionShape3D] or [CollisionPolygon3D] child nodes.