GG-UI — Design

Module Boundary

The core meets the rest through three interfaces: platform events in, UI primitives out, and scheduling. The GGUI target can't include engine headers; CMake enforces it. That keeps the core headless-testable and usable by standalone tools without a World.

Contexts and Lifetimes

A UIContext is an independent tree, storage, and snapshot chain, owned by the engine and not by a World: UI outlives World resets, spans PIE Worlds, and renders loading screens when no World exists.

UI documents declare a ConstructLifetime tier (Level / World / Session / Persistent). FlowManager destroys Level- and World-scoped UI with their domain; documents that survive a World reset get the same OnWorldTeardown / OnWorldInitialized callbacks to rebind. There is no separate UI lifetime vocabulary.

Editor Integration

The editor UI sits on the edit-mode contracts (Edit Timeline) and adds no second path into world state.

Deterministic UI

GG-UI is also the basis for 2D and UI-driven games (card, puzzle, strategy), where layout and hit-testing feed gameplay and must resimulate bit-identically.

Commitments that can't be retrofitted, and so hold now:

• Layout is written against a numeric type chosen per document. No hidden float in shared paths.
• The core never reads a clock; time arrives through AdvanceTime.
• Evaluation order is by node, never by hash-container iteration.
• Text metrics enter sim-bound layout at one boundary, with fonts pinned per build.

Sim-bound documents on Brain are not built yet. The layout determinism test is.

Code ↔ Node Graph

The node graph and C++ are two views of one program. The C++ source is the source of truth; the graph is a live projection of it.

• Code changes re-parse incrementally and update the graph, keeping each node's identity through its source anchor.
• Graph changes become minimal text edits applied as one transaction, so undo covers both views and comments and formatting survive.
• Today's paths are one-way and lossy. The round-trip model gets its own design document.

Linux Verification

Built and checked on Windows. Everything goes through SDL and is expected to work, but X11 and Wayland runs are incomplete. Use the platform test window (--platform-test); its controls are listed in PlatformProbe.h. The routing logic (PlatformRouter) has no OS dependency and is covered by headless tests on every platform.

Docking Under Wayland

Capabilities are detected at run time.

Between windows, a tab drag finds the window under the pointer from window positions (UIHost::DockDocumentAt). Wayland gives neither window positions nor a global pointer, and during the press the source window keeps every pointer event. Only the compositor knows which surface is under the pointer, and it says so only during a wl_data_device drag. SDL 3.5 receives those drags but can't start one.

The plan, from reading SDL's Wayland backend; to be built and checked on Linux:

• Source. The platform layer binds its own wl_data_device_manager and wl_seat on SDL's wl_display (SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER). They share SDL's default queue, so SDL's event pump dispatches them. A wl_pointer of its own on that seat receives the same button events, which carry the serial start_drag needs. SDL keeps that serial private.
• Start. When a tab leaves its window, start a drag from that window's wl_surface with a source offering a private text MIME type and a token naming the drag. Optionally show a drag icon of the tab.
• Target. SDL accepts text drops, so its own data device turns the drag into SDL_EVENT_DROP_BEGIN, DROP_POSITION (window-local), DROP_TEXT and DROP_COMPLETE on whichever of our windows is under the pointer. These already reach the platform router; a drop carrying our token is routed to CarryOver / CarryEnd instead of a text drop.
• Outside. The source's cancelled event means nothing took it: float the panel. The compositor places it.
• Problems. Starting the drag sends wl_pointer.leave to the source window, and SDL answers that with a synthetic button release. The platform layer must swallow it, or the drag ends where it started. Another application may accept the text type; send writes nothing, so it receives an empty drop. Links wayland-client directly; SDL loads the same library at run time.

M7: Docking and Windows

Untested by hand: the real file dialog, tab dragging with a real mouse, and layout restore across a restart. Nothing after the first Linux pass has been built on Linux.

M8: The Editor on GG-UI

The shell moved first, so there was one dock from the start (EditorShell); panels not yet moved over were drawn by ImGui into areas of it until M10. The editor waits for every document each frame (an update budget of 0) and its frame on Encoder reads what was just published; the shell's handlers post their work to that frame.

Shortcuts are rebindable actions under Editor.*, with defaults most editors share:

While playing, the game has the keyboard, except chords of actions kept from the game (UIHost::KeepFromGame): Stop and Release Pointer. Their commands exist only while playing, so Escape keeps its usual meaning otherwise. Keys that also fly the camera (W, E, Q) don't switch tools while it flies.

Open: hiding entities and Constructs in the scene, so a designer can place things that a trigger reveals. It needs its own design: whether a hidden entity collides, ticks, replicates, and can be picked in the editor.

String files are hand-editable, one per language, so anyone can add a language:

# content/strings/en.strings
Editor.Outliner.Title = Outliner
Editor.Scene.Open.Tip = Open a .tnxscene file

Not Placed

• A first frame in proportion: build, layout, and publish of a large document from scratch cost about 0.7 microseconds a node, and need the three phases to walk chunks rather than nodes.
• Charts.
• A full engine input action (TnxInputAction); see Interaction.

How It Got There

Design choices that produced those numbers, and the problems that forced them:

• Snapshots share unchanged row chunks. Publishing one changed label used to write every node (9.7 ms at 100,000 nodes).
• Rows hold unscrolled positions; scroll offsets are stored separately. Scrolling a box used to rewrite the row of everything inside it (20 ms for a 100,000-node list).
• Nodes keep their primitive slots; draw order is a separate list. A label that grew by one glyph used to move every primitive drawn after it.
• Each document caches its own resolved styles (GGLooks), so a style table is only read during updates and documents sharing one update in parallel.
• The host never touches a document that is updating, and never changes what one reads. A slow document holds one frame, the one that discovers it, and none after.
• The text engine is three things, not one lock: a run table read by many, shaping with per-thread FreeType and HarfBuzz objects, and an atlas locked only to place a new glyph.

Problems found along the way, outside the UI:

• Job system: a quarter of the workers take physics jobs only, and a submitted job's wake went to any sleeping worker, so a job could wake one that couldn't take it and sit until something else was submitted. A coordinator that helps with its own jobs hid this. Physics-only workers now wait on their own signal.
• SheenBidi: its lock-free scratch-buffer stack handed one buffer to two threads under contention and crashed four runs in ten once shaping was parallel. It is built without that cache.
• Store forwarding: primitives written a field at a time and copied straight after stalled the copy; see Rendering.