Engine flags & building from source

Reference for the runtime's command-line flags and for building the runtime and packages from this repo. Using guido through the packages does not require any of this.

Bridge flags

Flag	Effect
--bridge-stdio	serve the protocol on stdin/stdout; all engine logs move to stderr so stdout stays clean (SDKs add this for you)
--bridge-inproc	in-process transport (added automatically by guido_start)
--bridge-listen host:port	loopback TCP listener
--bridge-socket /path	Unix domain socket (0600, unlinked on shutdown)
--bridge-pipe name	Windows named pipe \\.\pipe\name
--spawn "cmd"	engine-as-parent: fork the client, speak over its stdio, quit when it exits
--bridge-token t	require t in the handshake before any other op (use with TCP/socket)
--bridge-window spec	creation-time window flags: comma list of borderless, transparent, on_top, no_resize, embed_subwindows, size=WxH
--bridge-pack file.pck	mount an asset pack at boot (absolute path)

Engine flags added by this fork

Flag	Effect
--no-project	boot with no project/PCK at all: built-in defaults, gl_compatibility renderer, empty scene tree. The client builds the UI over the wire (SDK default)

Combine with upstream Godot flags as usual: --headless (CI), --rendering-driver, --verbose, --quiet.

The dual-use runtime binary

Every package ships one file, libguido.so, which works both as an executable (./libguido.so --no-project --bridge-stdio; the tarball's bin/guido and the npm guido bin point at this file) and as a shared library (dlopen it and use the five guido_* functions). Executable shared objects are a Linux/glibc/x86-64 mechanism; other platforms will ship separate executable and library artifacts.

Building the runtime

misc/scripts/build_ui_library.sh     # → bin/libgodot.linuxbsd.template_release.x86_64.so

Needs scons and a C++ compiler; roughly 30 minutes the first time. This is the condensed build: 3D, physics, navigation, XR, GDScript and the editor compiled out; the Control stack, themes, FreeType, advanced text shaping (ICU/HarfBuzz), SVG/JPG/WebP and the bridge kept. Size levers and their measured costs: misc/scripts/BUILD_SIZE_REPORT.md.

For the static archive (single-file native apps):

scons platform=linuxbsd target=template_release production=yes \
  library_type=static_library optimize=size_extra lto=none debug_symbols=no \
  disable_3d=yes deprecated=no disable_physics_2d=yes disable_physics_3d=yes \
  disable_navigation_2d=yes disable_navigation_3d=yes disable_xr=yes \
  accesskit=no sdl=no vulkan=no d3d12=no metal=no opengl3=yes \
  openxr=no minizip=no brotli=no graphite=no modules_enabled_by_default=no \
  module_freetype_enabled=yes module_text_server_adv_enabled=yes \
  module_svg_enabled=yes module_jpg_enabled=yes module_webp_enabled=yes \
  module_godot_bridge_enabled=yes \
  ccflags="-fPIC -ffunction-sections -fdata-sections -fno-asynchronous-unwind-tables -fno-unwind-tables"
misc/scripts/merge_static_lib.sh     # → bin/libguido.a

Two constraints to be aware of:

• Shared library: exports are trimmed with a linker version script (misc/scripts/guido_exports.map). Do not add -Wl,--exclude-libs,ALL; it hides the archive-resident guido_* symbols.
• Static library: must be built with lto=none. A GCC-LTO archive links only with the same GCC release via its plugin; rustc, Go and zig cc fail on it.

Building the packages

misc/scripts/package_dist.sh [version]

Takes the built .so and produces everything under dist/:

Artifact	Contents
dist/npm/guido-runtime-linux-x64-<v>.tgz	runtime binary package (npm publish both this and the SDK)
dist/npm/godot-ui-sdk-<v>.tgz	TypeScript SDK (depends on the runtime package)
dist/python/godot_ui_sdk-<v>-py3-none-manylinux_2_38_x86_64.whl	Python SDK with the runtime bundled
dist/guido-<v>-linux-x86_64.tar.gz	native tarball: bin/guido, lib/libguido.so, include/guido.h, themes, guido_pack.py, install.sh

The wheel's manylinux tag tracks the highest glibc symbol version the .so references (currently 2.38) — re-check with objdump -T libguido.so | grep -o 'GLIBC_[0-9.]*' | sort -Vu | tail -1 if you build on a different distro.

Other build scripts

Script	Output	Purpose
misc/scripts/build_ui_runtime.sh	bin/godot...x86_64	standalone engine executable (not needed for packaging — the .so is dual-use)
misc/selfextract/build_stub.sh	bin/guido-sfx-stub (150 KB)	self-extracting launcher stub for single-file bundles
demo-apps/scripts/bundle-inproc.ts	one-file Bun app	--pack=sfx|upx|none
misc/scripts/guido_pack.py	<name>.pck	pack a directory of scenes/assets without the Godot editor
examples/embedding/run-all.sh	—	smoke-runs every language example