graphics.gd

The Web (js/wasm) test harness is a tool designed to run the internal test suite inside a real browser against a Godot web export. It operates headlessly and reports pass/fail results to CI.

Workflow

1. Build & Serve: Running gd test (with GOOS=js) builds the go test binary to library.wasm, downloads the Godot web export template, and executes the Godot Web export preset. This produces a standard Godot web build (index.html, index.wasm, index.pck) alongside the Go library.wasm and wasm_exec.js. The result is served on :$PORT with the required cross-origin-isolation headers.
2. Browser Execution: run_browser_test.mjs launches headless Chromium via the DevTools protocol. Go's stdout is routed to console.log via wasm_exec.js, allowing standard go test output to appear in the browser console.

Exit Codes

• 0: PASS/ok line detected.
• 1: FAIL/--- FAIL/exit code: N/panic/uncaught exception detected.
• 2: Timeout occurred.

graphics.gd maps Godot engine classes to Go packages under the classdb directory.

Importing Classes

To use a class like Node, import it via its package path: import "graphics.gd/classdb/Node"

Inheritance and Casting

There is no formal inheritance in the Go API. To access a superclass or cast an object, use the AsClassName() method or specific casting methods provided by the class:

• AsObject()
• AsNode2D()
• AsControl()

Method Naming

Methods have been renamed from Godot's snake_case to Go's PascalCase convention. For example, get_tree() in GDScript becomes Get() in Go (note: some utility functions may have moved packages, e.g., Node.get_tree() is now SceneTree.Get()).

Handling Optional Arguments

By default, optional arguments are omitted. To specify them, convert an Instance into either the MoreArgs or Advanced types:

node.MoreArgs().AddChild(...)

To prevent deadlocks and race conditions in Godot's non-thread-safe API, calls made from non-main goroutines are routed through a Multi-Producer Single-Consumer (MPSC) ring buffer.

The Workflow:

1. Routing: Using threadcheck.Main(), calls from non-main goroutines are detected.
2. Dispatch:
   • Void calls: Pushed to the MPSC ring as fire-and-forget tasks.
   • Calls needing results: Pushed to the ring, and the calling goroutine blocks until the entry status is marked DONE.
3. Execution: The main thread drains this ring every frame (via startup/garbage_collector.go), executing the calls in a single batch.
4. Result Delivery: Results are written directly into the ring entry. The blocked goroutine reads the return value from the entry itself, avoiding per-call allocations.

Key Safety Features:

• Panic Handling: Panics inside a Run thunk are captured by the drain and re-raised on the original calling goroutine. Panics in deferred thunks propagate on the main thread after the cursor advances.
• Memory Safety: Result slots are zeroed before dispatch to prevent stale bytes from triggering incorrect unrefs of Godot objects (like StringName or Array).
• Shutdown: Calling ring.Threads.Close() at engine exit ensures remaining buffered calls are drained while the engine is still alive, and prevents goroutines from parking indefinitely.

// Conceptual flow of a cross-thread call
// 1. Goroutine calls a method
// 2. threadcheck.Main() detects it's not the main thread
// 3. Call is pushed to MPSC ring
// 4. Main thread drains ring and executes call
// 5. Result is placed in ring; goroutine wakes and reads it

Sticky-P is an optimization mechanism designed to eliminate the high overhead of runtime.cgocallback transitions during inbound virtual calls (such as _process or _physics_process) from the engine to Go.

In a standard flow, every call incurs syscall-state transitions (reentersyscall and exitsyscall) which can account for a significant portion of the call overhead. Sticky-P optimizes this by acquiring a Processor (P) once per frame's virtual batch and keeping it live across the engine-C gaps between calls.

The Three Execution Paths:

1. Cold path: Used for the first call of a batch or after a Stop-The-World (STW) event. It establishes the Go-to-P connection via the direct runtime.cgocallback path but skips the release on return, making the P "sticky."
2. Fast path: Used when the P is still held and no STW is pending. It switches to the sticky goroutine stack, runs the Dispatch function, and switches back without triggering exitsyscall or entersyscall.
3. Teardown: Triggered by EndFrame (via an on_every_frame handler), which releases the P to ensure inter-frame engine work can run with STW unblocked.

When working with Godot reference types (e.g., String, StringName, NodePath, Array, Dictionary, Variant, Callable, Signal) in goroutines, you must use anchored state rather than frame-temporaries.

The Problem: On the main thread, wrappers are 'frame-temporaries' that expire after two cycles. Goroutines operate on their own timeline and might outlive these cycles, leading to use-after-free errors.

The Solution (Anchoring):

• All wrap sites use gd.Wrap* helpers.
• For goroutines, these helpers construct pinned values using runtime.AddCleanup via an anchor.
• The Go garbage collector governs the lifetime of these anchors.
• Cleanup is handled via ring.Threads.Defer, ensuring the engine value is freed via noescape.Free only after all buffered uses in the MPSC ring have been executed (FIFO order).

Important Invariant: Values created on the main thread remain frame-temporaries even if a goroutine later uses them. Cross-thread sharing of main-created wrappers follows standard main-thread lifetime rules.