Decision #6 — agenKic-orKistrator

Desktop Rendering

Why Godot 4 + godot-xterm over Tauri, egui, raylib, or SDL2

The Question

The pixel office needs a game-like rendering engine that supports sprite animation, tilemap layouts, and embedded terminal panels. The renderer must feel like a real-time game environment — not a web page dressed up with CSS tricks — while retaining the ability to host live PTY sessions inside individual office tiles. These two requirements together are what make this the most researched decision in the project.

Options Considered

Godot 4 + godot-xterm

Visual editor, Pixelorama integration, embedded PTY terminals

Chosen

Pros

First-class pixel-art workflow: TileMaps, AnimatedSprite2D, CanvasLayer
godot-xterm embeds a full VTE-backed terminal as a scene node
Pixelorama integrates directly as an in-engine sprite editor
GDScript hot-reload keeps iteration cycles under 1 second
Integer scaling built in via Window.content_scale_mode
MIT-licensed; no royalty or build-fee at any revenue threshold

Cons

godot-xterm PTY support is Linux/macOS only; Windows is display-only
godot-xterm has no stable v1.0 release; must pin to a specific commit
gRPC client requires a GDExtension (C++) wrapper — no pure GDScript option

Tauri + CSS Pixel Art

WebView shell under 1 MB; web dev skills transfer directly

Rejected

Pros

Binary under 1 MB; familiar HTML/CSS/JS development model
xterm.js provides a polished terminal component out of the box
Rust backend with typed IPC commands via Tauri invoke

Cons

No native sprite engine — pixel art via CSS image-rendering: pixelated is brittle
Tilemap system requires a full canvas game library (Phaser, etc.) adding complexity
WebView GPU compositing is inconsistent across Linux desktop environments

egui (Rust)

Immediate-mode Rust GUI; compiles to native or WebAssembly

Rejected

Pros

Single Rust binary; trivial to cross-compile
Immediate-mode API keeps layout logic close to render logic
egui_extras provides image and texture support

Cons

No pixel font rendering — sub-pixel antialiasing blurs pixel art at low resolutions
No tilemap primitives; every game-like element must be hand-built
Not game-like: the retained/immediate model is fundamentally different from a scene graph

raylib + Go

Proven by MasterPlan; 120+ examples, C-compatible bindings

Rejected

Pros

Proven for pixel-art productivity apps (MasterPlan uses raylib + Go)
120+ official examples; pixel-perfect rendering with integer scaling
Minimal dependency surface; single statically-linked binary

Cons

No visual editor; every sprite and tile must be positioned in code
Custom UI widgets required from scratch (buttons, panels, scroll areas)
Terminal embedding requires a full PTY + VTE implementation in Go/C

SDL2

26-year AAA pedigree; used in hundreds of shipped titles

Rejected

Pros

Battle-hardened: 26-year production history across AAA and indie titles
Fine-grained control over every pixel, input event, and audio frame
Go bindings (veandco/go-sdl2) are mature and stable

Cons

Everything is manual: scene graph, sprite batching, input routing, UI layout
Terminal embedding is completely unsupported; requires vendoring libvte or similar
Heavy boilerplate before a single sprite appears on screen

Capability Matrix

Required capabilities vs. evaluated options

Capability	Godot 4	Tauri	egui	raylib	SDL2
Sprite animation	Yes	Partial	No	Yes	Yes
Tilemap system	Yes	No	No	Partial	No
Embedded PTY terminal	Yes	Yes	No	No	No
Visual scene editor	Yes	No	No	No	No
Integer pixel scaling	Yes	Partial	No	Yes	Yes
Hot-reload scripting	Yes	Yes	No	No	No
MIT / open license	Yes	Yes	Yes	Yes	Yes

The Decision

Godot 4 is the only option that satisfies both the pixel-art workflow requirement and the terminal embedding requirement simultaneously. Every alternative either has the game engine capabilities without a terminal (raylib, SDL2) or has a terminal without a game engine (Tauri). egui satisfies neither. This is not a close call.

PIX

Pixel-Art Rendering — Godot TileMap + AnimatedSprite2D

The office world is built as a TileMap scene with a 16×16 tile atlas. Individual agent tiles use AnimatedSprite2D nodes so state changes (idle, working, waiting, error) map directly to named animation tracks — no bespoke animation state machine needed. Window.content_scale_mode = integer enforces pixel-perfect upscaling at every viewport size without blurring.

Pixelorama, a Godot-native pixel editor, opens directly within the engine so asset iteration never leaves the development environment. Changes to the sprite atlas hot-reload into the running scene in under a second.

PTY

Terminal Embedding — godot-xterm as a Scene Node

godot-xterm exposes a Terminal node backed by libvterm. Any scene can instantiate a Terminal child, set its PTY to an agent subprocess, and receive live output as a standard Godot signal. The terminal panel that appears when clicking on an agent tile is literally a Godot node — subject to the same z-ordering, shader, and animation system as every other scene element.

Because the terminal is a first-class scene node, interactions like "slide the panel in from the right" or "shake the frame on error" are Tween animations, not custom compositor hacks. This integration depth is not achievable in any other evaluated option.

RPC

Orchestrator Bridge — GDExtension gRPC Client

The Godot client communicates with the Go orchestrator over gRPC. Because there is no pure GDScript gRPC library, a thin GDExtension module in C++ wraps the official gRPC C core and exposes typed calls as Godot signals. The extension is compiled once and distributed as a shared library alongside the project binary.

The extension surface is deliberately minimal: connect(address), send_command(type, payload), and a message_received signal. All protocol buffer parsing happens in the C++ layer; GDScript only sees native Godot Dictionary objects, keeping the scripting layer decoupled from the wire format.

Caveats and Constraints

godot-xterm PTY support is Linux/macOS only. On Windows, the Terminal node renders output but the PTY layer is not implemented; the subprocess pipe is display-only. This is acceptable for the initial target platform (Linux developer workstations) but blocks a future Windows port unless an upstream maintainer or a project contributor adds ConPTY support to godot-xterm.

Pin godot-xterm to a specific commit hash. The library has no stable v1.0 release and the API surface changes between commits. The project addons/godot-xterm directory tracks a pinned commit via a git submodule lock. Any upstream update requires an explicit review and re-pin rather than a passive git submodule update.

Integer scaling must be enforced at the project level. Set display/window/stretch/mode = viewport and display/window/stretch/scale_mode = integer in project.godot. If either setting is absent, the engine uses fractional scaling and pixel art becomes blurry at non-integer zoom levels. This must be guarded in CI via a project settings lint step.

gRPC client via GDExtension requires a C++ toolchain in CI. The extension links against the gRPC C core (grpc, grpc++) and the Godot headers for the target Godot version. The build is pinned to a specific Godot minor version; upgrading Godot requires recompiling the extension. A pre-built .so / .dylib is committed to the repository to avoid requiring every contributor to have a C++ toolchain installed.

Trade-offs Accepted

Full game engine may be overkill for a developer tool. Godot ships with a physics engine, 3D renderer, audio bus, and networking stack that the pixel office will never use. The binary is larger than a minimal Tauri shell and the engine has a longer startup time. This overhead is accepted because the engine-level capabilities (TileMap, AnimatedSprite2D, scene hot-reload) are not available in lighter alternatives.

GDScript is a niche language with a shallow talent pool. New contributors must learn GDScript before they can modify the office rendering layer. There is no type inference in older GDScript; type annotations are opt-in. The risk is mitigated by keeping the GDScript surface area small: scene logic only, with all business logic delegated to the Go orchestrator over gRPC.

godot-xterm is a single-maintainer dependency with no LTS commitment. If the maintainer abandons the project or breaks the API on a Godot 4.x minor update, the project must either fork and maintain godot-xterm internally or migrate to an alternative terminal embedding strategy. A fork plan is documented in the architecture runbook as a contingency.