TGUI Framework Architecture
Relevant source files
The following files were used as context for generating this wiki page:
TGUI is a user interface framework for Space Station 13 codebases, specifically BandaStation. It utilizes React, JavaScript, and modern web technologies to replace traditional DM-based UIs. The framework operates as a bridge between the BYOND game engine and a Chromium-based WebView2 environment, allowing for complex, responsive, and state-driven interfaces.
Sources: tgui/README.md:3-8, tgui/README.md:143-146
Core Communication Layer
TGUI relies on the Byond API object to communicate between the game server (DM) and the client-side UI. This communication uses an event-based system where DM messages trigger UI updates, and UI actions send topic or winset calls back to the server.
The Byond API Object
The Byond global object provides the interface for interacting with the BYOND executable and the DM backend.
| Method | Description |
|---|---|
call(path, params) | Makes a BYOND call, either via location.href or an XMLHttpRequest for large payloads. |
sendMessage(type, payload) | Sends a JSON-encoded message to the /datum/tgui_window hosting the instance. |
subscribe(listener) | Registers a function to handle incoming messages from the DM backend. |
winset(id, props) | Assigns properties to BYOND skin elements (e.g., window size, visibility). |
parseJson(text) | Parses incoming JSON from BYOND using a custom reviver to handle Infinity and NaN. |
Sources: tgui/packages/tgui-setup/helpers.js:33-145, tgui/global.d.ts:47-152
Messaging Flow
The following sequence diagram illustrates the lifecycle of a message from the DM backend to a TGUI interface component.
Event Dispatch System
TGUI implements a three-layer event dispatch system to separate server-side messages from client-side UI actions. This architecture reduces abstraction by providing direct state access for internal UI changes while using a formal event bus for external messages.
- Event Bus: Maintains a registry of handlers and dispatches messages to them.
- Handlers: Functions that process specific event types, update the application store, or trigger further backend calls.
- Store: The global application state.
Sources: tgui/packages/tgui/events/README.md:12-20
Event Processing Logic
When the Byond object receives a message, it is dispatched through the EventBus.
Project Structure and Styling
TGUI organizes code into self-contained modules within a /packages directory. The framework uses SASS for styling, divided into atomic classes, themes, and interface-specific stylesheets.
File Organization
- /packages/tgui/index.ts: The application entry point where themes are registered.
- /packages/tgui/interfaces: Contains the individual React components for in-game windows.
- /packages/tgui/layouts: Root-level components controlling the title bar, window handlers, and themes.
- /packages/tgui/styles: Structured into
/atomic(reusable classes),/themes, and/interfaces(specific UI styles).
Sources: tgui/README.md:148-166
Styling Hierarchy
TGUI uses a layered SASS approach, importing a core component library (tgui-core) and then applying project-specific overrides.
Initialization and Error Handling
The initialization process begins in tgui.html, which sets up metadata tags and the React root element.
Bootstrapping
- The browser loads
tgui.htmland parses metadata forwindowIdandstrictMode. helpers.jsinitializes theByondAPI and hooks intowindow.onerror.- The script sends a
readysignal to BYOND viaByond.sendMessage('ready').
Sources: tgui/public/tgui.html:10-15, tgui/public/tgui.html:61-64, tgui/packages/tgui-setup/helpers.js:36-60
Fatal Error Handling
If strictMode is enabled, any unhandled exception triggers a "Fatal Error" screen (Blue Screen of Death). This stops the application from handling further messages and logs the stack trace back to the game server.
Sources: tgui/packages/tgui-setup/helpers.js:304-332, tgui/public/tgui.html:24-49
Summary
TGUI Framework Architecture provides a modern, React-based environment for SS13 interfaces. It bridges the gap between DM and web technologies through a robust Byond API object, a structured event dispatch system, and a modular project layout. This allows developers to build responsive UIs that are decoupled from the legacy BYOND rendering engine while maintaining tight synchronization with the game state.