Getting started

Install

Bun / TypeScript

bun add godot-ui-sdk
# or: npm install godot-ui-sdk

Python

pip install godot-ui-sdk

Other languages

# One tarball: runtime, C header, themes, packing tool.
tar xzf guido-0.1.0-linux-x86_64.tar.gz
./guido-0.1.0-linux-x86_64/install.sh     # installs to ~/.local, no root

Each package includes the runtime, a single ~21 MB binary that renders the UI. The SDKs locate it automatically; the tarball installs a guido command on your PATH.

Packages are currently Linux x86-64. For other platforms see Platform support; to build the runtime yourself see Building from source.

First program

Bun / TypeScript

import { GodotClient } from "godot-ui-sdk";

const client = new GodotClient();
await client.connect();                    // starts the runtime, opens a window

const root = await client.getRoot();
root.set("title", "Hello guido");

const button = await client.instantiate("Button");
button.set("text", "Click me");
root.addChild(button);

let clicks = 0;
await button.on("pressed", () => button.set("text", `Clicked ${++clicks}`));

client.onWindowCloseRequested = () => client.disconnect();

Python

import threading
from godot_ui import GodotClient

client = GodotClient()
client.connect()                           # starts the runtime, opens a window

root = client.get_root()
root.set("title", "Hello guido")

button = client.instantiate("Button")
button.set("text", "Click me")
root.add_child(button)

clicks = 0
def pressed():
    global clicks
    clicks += 1
    button.set("text", f"Clicked {clicks}")
button.on("pressed", pressed)

done = threading.Event()
client.on_window_close_requested = lambda oid: done.set()
done.wait()
client.disconnect()

Shell (no SDK)

# The runtime reads and writes newline-delimited JSON on stdio, so any
# language that can spawn a process can use it. --headless runs without
# a display:
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"handshake","params":{"clientInfo":{"name":"sh","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"instantiate","params":{"className":"Button"}}' \
  | guido --no-project --headless --bridge-stdio

Run it with bun run app.ts or python app.py. A window opens with a working button. All UI code follows this pattern: create widgets, set properties, subscribe to signals.

Next steps

• Language guides, each with a complete example and the patterns that language needs: Bun, Python, C, Rust, Go, Zig, Nim.
• Custom scenes & assets: design screens in the Godot editor instead of positioning widgets in code.
• Core patterns: batching, signals, ownership, read-after-write.
• Shipping your app: wheels, single-file executables, tarballs.

Reference notes

• Window options that must exist before the window is created are passed as engine arguments: connect({ stdio: { args: ["--no-project", "--bridge-window", "size=1000x700,borderless"] } }).
• --headless in the args runs the same API without a display (for CI and servers).
• To list available widget classes at runtime: client.request("classes", { contains: "Button" }). Names match the Godot Control documentation.
• Runtime resolution order: the GUIDO_BIN environment variable, then the installed package's runtime, then guido on PATH.