C API (guido.h)

The complete in-process embedding surface — five functions, C99, no types beyond int and char *. Canonical header: modules/godot_bridge/guido.h. Exported by the shared library (exactly these plus upstream's two libgodot_* entry points) and by libguido.a.

int         guido_start(int argc, const char **argv);
int         guido_iteration(void);
int         guido_send(const char *utf8_line);
const char *guido_recv(void);
void        guido_stop(void);

guido_start(argc, argv) → int

Boots the engine in this process. argv holds engine arguments without a program name — e.g. {"--no-project", "--bridge-window", "size=800x600"} or {"--no-project", "--headless"}. --bridge-inproc is appended automatically; arguments are copied before returning.

Returns 0 on success, -1 if an engine already ran in this process, -2 if setup failed (bad arguments, or no usable display — try --headless), -3 if the engine failed to start after setup.

guido_iteration() → int

Pumps one frame: input events, process, render. Blocks for the frame's duration; the engine self-paces (vsync with a window, frame delay otherwise). Call continuously from the thread that called guido_start.

Returns 0 to continue, 1 when the engine wants to quit (last window closed, quit op), -1 if not running.

guido_send(line) → int

Queues one JSON-RPC message (a complete JSON object, UTF-8, no newline needed) for dispatch on the next frame. Thread-safe. Returns 0, or -1 if the bridge is not up.

guido_recv() → const char *

Pops the next engine→host message. Returns a NUL-terminated UTF-8 JSON object valid only until the next guido_recv() call — copy it before receiving again — or NULL when drained. Call after each iteration. Still usable after quit/stop to drain the final quit notification.

guido_stop()

Tears the engine down. One engine per process, and it cannot be restarted afterwards (upstream libgodot limitation).

Threading contract

guido_start, guido_iteration and guido_stop must all be called from one thread, which becomes the engine main thread. guido_send may be called from any thread; guido_recv from the main thread.

Teardown order

/* stop pumping … then: */
for (int i = 0; i < 2; i++) {           /* grace frames: dispatch queued ops */
    if (guido_iteration() != 0) break;
    while (guido_recv()) { /* drain */ }
}
guido_stop();
while (guido_recv()) { /* final "quit" notification */ }