gogogd

README

gogogd

A Godot binding for Go plus an opinionated authoring layer, in one project. Write full Godot games in Go.

Working principle: Go fast. Stay Godot.

gogogd lets you write Godot games in Go with the type system, tooling, and ecosystem you already use, without the binding ceremony that makes raw gdextension bindings verbose. The Godot scene tree, nodes, signals, resources, packed scenes, and lifecycle hooks remain front and centre — gogogd just makes them pleasant to drive from Go code.

package main

import (
    "fmt"
    "os"

    "github.com/AveryLucas/gogogd/classdb/Node"
    "github.com/AveryLucas/gogogd/startup"
)

type Game struct {
    Node.Extension[Game] `gd:"Game"`
}

func (g *Game) Ready() {
    fmt.Fprintln(os.Stderr, "[hello] Game.Ready — gogogd works")
}

func main() {
    // Class registrations are emitted by `gogogd register` into
    // gogogd_register.go's init() — run automatically before main.
    startup.Scene()
}

Drop a Game node into main.tscn in the Godot editor (or use gogogd new — the scaffold writes the scene file too), then gogogd dev rebuilds and reloads on save.

Install

Requires Go 1.26+ and Godot 4.6.2+.

go install github.com/AveryLucas/gogogd/cmd/gogogd@latest
gogogd new my-game
cd my-game
gogogd dev

CLI

gogogd new <name>       Scaffold a new project.
gogogd doctor [--json]  Diagnose the local toolchain.
gogogd register         Generate gogogd_register.go for the current project.
gogogd build [target]   Build the project (target: windows, linux, macos, web).
gogogd run              Codegen + build + launch the project under Godot.
gogogd dev              File-watching dev loop (rebuild + relaunch on save).
gogogd inspect <type>   Print a registered type's static schema.
gogogd test [--duration d]  Run the project headless for d (default 8s).

Most users only need gogogd dev. The others are exposed for CI, scripting, and one-off operations.

What it provides

Component authoring. Register a Go struct as a Godot class by embedding the binding's <Class>.Extension[Self]:

type Player struct {
    CharacterBody2D.Extension[Player] `gd:"Player"`

    HP    int       // inspector property
    Speed gd.Delta  // inspector property
}

func (p *Player) Ready()             { /* ... */ }
func (p *Player) Process(dt gd.Delta){ /* ... */ }

Codegen promotes every ancestor's methods, properties, and signals onto the leaf class, so p.SetPosition(v), p.MoveAndSlide(), p.OnPressed(cb), p.QueueFree() all work directly with no .AsParent() chain.

Helpers — pick your import shape. Two equivalent ways to reach the authoring API:

// (1) Umbrella — one import for the high-frequency surface.
import "github.com/AveryLucas/gogogd"

gogogd.After(p.AsNode(), 0.5, p.QueueFree)
gogogd.Connect0(p.AsNode(), &p.Died, onDied)
gogogd.Quit(p.AsNode())

// (2) Bare packages — one import per verb. The import list reads as
//     the inventory of what the component does.
import (
    "github.com/AveryLucas/gogogd/timing"
    "github.com/AveryLucas/gogogd/signals"
    "github.com/AveryLucas/gogogd/scenetree"
)

timing.After(p.AsNode(), 0.5, p.QueueFree)
signals.Connect0(p.AsNode(), &p.Died, onDied)
scenetree.Quit(p.AsNode())

Both compile to the same code (the umbrella is wrapper functions and type aliases over the bare packages). Mix freely — import what reads well in each file.

Package	What it owns	Available on umbrella?
gd	Type aliases (Vec2, Vec3, Col, Delta, Radians), Must, MustOk	yes
signals	Signal0, Signal[T], owner-bound Connect / Connect0	yes
timing	After, Every, Cooldown, OnMainThread	yes
actions	Pressed, JustPressed, Vector and mouse helpers	yes
scenetree	Quit, ChangeScene, ReloadScene, SetPaused	yes
tree	Find, Children, Descendants, OnlyIf	yes
spawn	Add, AddChild, AddNew (polymorphic)	yes
strict	Assert for ggd:"strict" field validation	yes
visual	AttachCircle, AttachRect, ColorOf, X11 colours	bare only
stat	Reactive Stat[T]	bare only
pool	Typed object pool	bare only
sequence	Timeline DSL (Wait, Do, Parallel, Loop)	bare only
bus	Global pub/sub	bare only
i18n	Tr, SetLocale, Bind	bare only
audio	Bus volume, ducking	bare only
window	Fullscreen, VSync	bare only
settings	Typed reactive singleton	bare only
physics	Raycast2D, OverlapRect	bare only
ui	Modal screen stack, toast, focus	bare only
fsm	Flat finite state machine	bare only
fx	Flash, Hitstop	bare only
save	Typed save slots with versioned migration	bare only

The umbrella covers the core authoring surface — the helpers a typical component file reaches for. Domain-specific packages (save, i18n, ui, fsm, …) stay as bare imports because a file that touches them is about that domain and the explicit import is informative.

main() still imports startup directly. startup.Scene() is the engine entry point. We can't re-export it through the umbrella without an import cycle (the cgo glue at the umbrella root is blank-imported by startup). One-line cost per project.

The full Godot class surface. Every Godot class (Node, Sprite2D, CharacterBody2D, Control, Button, ~500 in total) is a Go package under classdb/. Codegen emits the full bound surface plus virtual hook helpers and OnX signal connectors.

Examples

• examples/01-coin-collector — smallest real game shape. Player auto-paths toward coins, picks them up via Area2D overlap, score on a Label HUD.
• examples/02-shooter — bullets with self-cleanup, enemy spawner, body-overlap hit detection.
• examples/03-menus-and-save — typed save slots with migration, reactive settings, modal screen stack, audio/window control, global event bus, FSM, i18n.

Each runs headless under gogogd test --duration 5s.

Documentation

• docs/ARCHITECTURE.md — full rationale: layer model, component model, lifetime/keepalive walker, lifecycle dispatch, child-node wiring (with the four footguns), helper API principles, complexity ramp.
• docs/DESIGN_PRINCIPLES.md — one-page rules cheat sheet.
• docs/MERGE_PLAN.md — how gogogd absorbed the Graphics.GD fork into one project.
• pkg.go.dev/github.com/AveryLucas/gogogd — full API reference (mirrors Godot's docs into Go).

Supported platforms

• Windows (GOOS=windows gogogd build windows)
• Linux (GOOS=linux gogogd build linux)
• macOS (GOOS=darwin gogogd build macos)
• Web (GOOS=js gogogd build web)

64-bit only (arm64, amd64, wasm).

Status

gogogd is pre-1.0. The authoring surface is stable; the binding layer tracks Godot 4.6.x. Breaking changes happen — pin a commit until 1.0.

History

gogogd started as an opinionated authoring layer on top of grow-graphics/gd (also known as Graphics.GD), a Godot binding for Go by @Splizard and contributors. In May 2026 the two were merged into one project: every API decision that was previously "wrapper sugar over the binding" is now codegen on the binding itself. The original upstream README is preserved at Readme_upstream.md.

Graphics.GD's design — the keepalive walker, the variant system, the classdb registration machinery, the cgo bridge, the cross-platform build pipeline — is the foundation gogogd stands on. Thanks.

The gogogd-specific work covers the authoring helpers, the gogogd CLI, the codegen passes that promote parent methods/properties/signals onto leaf classes, the scaffold templates, and the documentation rewrite.

Licensing

MIT, the same as Godot. You can use gogogd in any manner you can use the Godot engine. The gd command-line tool reuses some code under the Apache 2.0 license. The Readme_upstream.md is preserved under the original Graphics.GD license terms.

If gogogd is useful for a commercial product, consider sponsoring @Splizard — the binding layer they maintain is most of the code, and the upstream project depends on sponsor support.

Documentation

Overview

Package gogogd is the umbrella for the gogogd authoring API.

Most user-facing helpers and type aliases live here as re-exports of the bare packages underneath (`timing`, `signals`, `actions`, `scenetree`, `tree`, `spawn`, `strict`, …). Users who prefer the bare-package shape can import those directly; users who want one import can get most of what they need from this package.

Two things are NOT in the umbrella:

• The per-class packages under `classdb/` (Node, CharacterBody2D, Control, …). There are ~500 of them and users only need the handful their components actually subclass — importing those directly keeps the import list informative.
• The engine entry point. `main()` calls `startup.Scene()` from "github.com/AveryLucas/gogogd/startup". We can't re-export it through the umbrella without an import cycle (startup blank-imports this package for cgo linking).

A typical component file is two imports:

import (
    "github.com/AveryLucas/gogogd"
    "github.com/AveryLucas/gogogd/classdb/CharacterBody2D"
)

Index

• func Add(parent Node.Instance, thing any, pos Vec2) Node.Instance
• func Add3(parent Node.Instance, thing any, pos Vec3) Node.Instance
• func AddChild(parent Node.Instance, thing any) Node.Instance
• func AddNew[T interface{ ... }](parent Node.Instance, newFn func() T) T
• func After(owner Node.Instance, dt Delta, fn func())
• func AncestorOf[T Object.Any](start Node.Instance) (T, bool)
• func As[T Object.Any](value Object.Any) (T, bool)
• func Assert(target any)
• func ChangeScene(any Node.Instance, path string) error
• func Children[T Object.Any](parent Node.Instance) []T
• func Connect[T any](owner Node.Instance, sig *Signal[T], fn func(T))
• func Connect0(owner Node.Instance, sig *Signal0, fn func())
• func Connect2[A, B any](owner Node.Instance, sig *Signal2[A, B], fn func(A, B))
• func Connect3[A, B, C any](owner Node.Instance, sig *Signal3[A, B, C], fn func(A, B, C))
• func Descendants[T Object.Any](parent Node.Instance) []T
• func Every(owner Node.Instance, dt Delta, fn func())
• func Find[T Object.Any](any Node.Instance) (T, bool)
• func IsPaused(any Node.Instance) bool
• func JustPressed(action string) bool
• func JustReleased(action string) bool
• func Must[T any](v T, err error) T
• func MustOk[T any](v T, ok bool) T
• func OnExit(owner Node.Instance, fn func())
• func OnMainThread(fn func())
• func OnlyIf[T, In Object.Any](fn func(T)) func(In)
• func OnlyIfBody2D[T Object.Any](fn func(T)) func(Node2D.Instance)
• func Pressed(action string) bool
• func Quit(any Node.Instance)
• func ReloadScene(any Node.Instance) error
• func SetPaused(any Node.Instance, paused bool)
• type Class
• type Col
• type Cooldown
• type Delta
  • func Strength(action string) Delta
• type EulerRadians
• type Radians
• type Signal
• type Signal0
• type Signal2
• type Signal3
• type Vec2
  • func MouseDirectionFrom(from Vec2, any Object.Any) Vec2
  • func MousePos(any Object.Any) Vec2
  • func Vector(negativeX, positiveX, negativeY, positiveY string) Vec2
• type Vec3
• type Vec4

Functions

func Add

func Add(parent Node.Instance, thing any, pos Vec2) Node.Instance

Add adds `thing` as a child of `parent` and positions it at `pos`. Polymorphic over: a Go value implementing AsNode, a PackedScene instance, or a string scene path ("res://x.tscn").

func Add3

func Add3(parent Node.Instance, thing any, pos Vec3) Node.Instance

Add3 is the 3D variant of Add.

func AddChild

func AddChild(parent Node.Instance, thing any) Node.Instance

AddChild adds `thing` as a child of `parent` without setting a position. Useful for non-spatial children.

func AddNew

func AddNew[T interface{ AsNode() Node.Instance }](parent Node.Instance, newFn func() T) T

AddNew constructs a fresh T via `newFn` and adds it as a child of `parent`. Used for stock Godot node types (Timer, etc.) that have their own constructor.

func After

func After(owner Node.Instance, dt Delta, fn func())

After schedules `fn` to run once after `dt` seconds. The schedule is owner-bound: if `owner` exits the tree before the timer fires, `fn` is dropped.

func AncestorOf

func AncestorOf[T Object.Any](start Node.Instance) (T, bool)

AncestorOf walks up from `start` and returns the nearest ancestor matching type T.

func As

func As[T Object.Any](value Object.Any) (T, bool)

As converts `value` to the requested type T (typically a leaf Instance type). Returns (T, false) if the conversion isn't valid.

func Assert

func Assert(target any)

Assert validates every `ggd:"strict"` tagged child field on `target` is populated by a scene-authored node (not an auto-created runtime stub). Call from Ready.

func (m *MainMenu) Ready() {
    gogogd.Assert(m)
    // ... fields are now guaranteed scene-authored
}

Panics on any unset strict field.

func ChangeScene

func ChangeScene(any Node.Instance, path string) error

ChangeScene switches to the scene at `path` (typically "res://x.tscn").

func Children

func Children[T Object.Any](parent Node.Instance) []T

Children returns all direct children of `parent` whose type matches T.

func Connect

func Connect[T any](owner Node.Instance, sig *Signal[T], fn func(T))

Connect owner-binds a single-payload signal handler.

func Connect0

func Connect0(owner Node.Instance, sig *Signal0, fn func())

Connect0 owner-binds a void-signal handler. When `owner` exits the scene tree, the connection auto-detaches.

func Connect2

func Connect2[A, B any](owner Node.Instance, sig *Signal2[A, B], fn func(A, B))

Connect2 owner-binds a two-payload signal handler.

func Connect3

func Connect3[A, B, C any](owner Node.Instance, sig *Signal3[A, B, C], fn func(A, B, C))

Connect3 owner-binds a three-payload signal handler.

func Descendants

func Descendants[T Object.Any](parent Node.Instance) []T

Descendants returns every descendant of `parent` whose type matches T.

func Every

func Every(owner Node.Instance, dt Delta, fn func())

Every schedules `fn` to run on a repeating `dt`-second interval. Owner-bound — auto-cancels on owner exit.

func Find

func Find[T Object.Any](any Node.Instance) (T, bool)

Find searches the scene tree from `any` for a node of type T.

func IsPaused

func IsPaused(any Node.Instance) bool

IsPaused reports whether the engine is currently paused.

func JustPressed

func JustPressed(action string) bool

JustPressed reports whether the named input action transitioned to pressed this frame.

func JustReleased

func JustReleased(action string) bool

JustReleased reports whether the named input action transitioned to released this frame.

func Must

func Must[T any](v T, err error) T

Must adapts an (T, error) return into a T, panicking on non-nil error. Use for component code that *expects* the value to be there.

func MustOk

func MustOk[T any](v T, ok bool) T

MustOk adapts a (T, bool) return into a T, panicking on false.

func OnExit

func OnExit(owner Node.Instance, fn func())

OnExit fires `fn` once when `owner` exits the scene tree.

func OnMainThread

func OnMainThread(fn func())

OnMainThread runs `fn` on Godot's main thread. Use from a goroutine when you need to touch any Godot node, since cross-thread node access is unsafe.

func OnlyIf

func OnlyIf[T, In Object.Any](fn func(T)) func(In)

OnlyIf wraps a typed handler so it only fires when the incoming argument is of type T. Common with signals whose payload type is looser than what you want to react to.

area.OnBodyEntered(gogogd.OnlyIf(func(p *Player) { p.Hit() }))

func OnlyIfBody2D

func OnlyIfBody2D[T Object.Any](fn func(T)) func(Node2D.Instance)

OnlyIfBody2D is the Node2D-specialised version of OnlyIf for physics-body overlap signals.

func Pressed

func Pressed(action string) bool

Pressed reports whether the named input action is currently held.

func Quit

func Quit(any Node.Instance)

Quit shuts the engine down cleanly. `any` is any node in the tree (used to reach SceneTree).

func ReloadScene

func ReloadScene(any Node.Instance) error

ReloadScene reloads the current scene from disk.

func SetPaused

func SetPaused(any Node.Instance, paused bool)

SetPaused toggles the engine's pause state.

Types

type Class

type Class = classdb.Class

Class is the interface every registered gogogd class implements (via embedding `<Class>.Extension[Self]`). Alias for classdb.Class.

type Col

type Col = gd.Col

Col is an RGBA color. Alias for Color.RGBA.

type Cooldown

type Cooldown = timing.Cooldown

Cooldown is a zero-value-ready countdown timer. Tick each frame; Ready() reports whether the cooldown has elapsed; Reset starts it over.

type Delta

type Delta = gd.Delta

Delta is the frame-delta-time type passed to Process / PhysicsProcess. Alias for Float.X (float32).

func Strength

func Strength(action string) Delta

Strength returns the analogue strength (0..1) of the named action.

type EulerRadians

type EulerRadians = gd.EulerRadians

EulerRadians is a 3-axis Euler-angle triplet in radians.

type Radians

type Radians = gd.Radians

Radians is an angle in radians. Alias for Angle.Radians.

type Signal

type Signal[T any] = signals.Signal[T]

Signal is a single-payload signal. Declare as a struct field:

type Player struct {
    Node.Extension[Player] `gd:"Player"`
    HPChanged gogogd.Signal[int]
}

type Signal0

type Signal0 = signals.Signal0

Signal0 is a void signal (no payload). Declare as a struct field:

type Coin struct {
    Area2D.Extension[Coin] `gd:"Coin"`
    Collected gogogd.Signal0
}

type Signal2

type Signal2[A, B any] = signals.Signal2[A, B]

Signal2 is a two-payload signal.

type Signal3

type Signal3[A, B, C any] = signals.Signal3[A, B, C]

Signal3 is a three-payload signal.

type Vec2

type Vec2 = gd.Vec2

Vec2 is a 2D vector (X, Y). Alias for Vector2.XY.

func MouseDirectionFrom

func MouseDirectionFrom(from Vec2, any Object.Any) Vec2

MouseDirectionFrom returns the unit vector pointing from `from` to the current mouse position in `any`'s coordinate space.

func MousePos

func MousePos(any Object.Any) Vec2

MousePos returns the current mouse position in the coordinate space of `any` (a node or anything with AsObject()).

func Vector

func Vector(negativeX, positiveX, negativeY, positiveY string) Vec2

Vector returns a normalised 2D movement vector built from four named input actions (negativeX, positiveX, negativeY, positiveY). Useful for "use arrow keys to walk" patterns.

type Vec3

type Vec3 = gd.Vec3

Vec3 is a 3D vector (X, Y, Z). Alias for Vector3.XYZ.

type Vec4

type Vec4 = gd.Vec4

Vec4 is a 4D vector (X, Y, Z, W). Alias for Vector4.XYZW.