Visuals & Rendering Quirks
Relevant source files
The following files were used as context for generating this wiki page:
BandaStation utilizes a multi-layered rendering architecture that combines native BYOND DreamMaker (DM) sprite handling with modern web technologies via the tgui framework. Visual output includes traditional DMI-based icons, Greyscale Auto-Generated Sprites (GAGS), and CSS/SASS-driven user interfaces. Specific rendering quirks arise from the interaction between the BYOND engine, Chromium-based WebView2, and custom asset loading pipelines.
Sources: tgui/README.md:1-20, code/datums/greyscale/README.md:1-10
Greyscale Auto-Generated Sprites (GAGS)
The GAGS system generates dynamic recolors of sprites at runtime. It replaces static DMI icons with a configuration-driven approach that allows for multiple color layers and advanced blend modes.
GAGS Architecture
The system relies on three primary components:
- JSON Configuration: Controls icon combinations, layering order, and color mapping.
- DMI Source: Provides the base greyscale sprites.
- DM Configuration Type: Links the code to the DMI and JSON assets.
The GAGS generation engine processes inner lists in the JSON as independent chunks before applying them to the main sprite. This allows for complex nesting and "order of operations" during rendering.
Sources: code/datums/greyscale/README.md:27-35
Layer Types and Blend Modes
GAGS uses specific layer types to define how components are retrieved and merged.
| Layer Type | Description |
|---|---|
icon_state | Retrieves a specific state from the associated DMI file. |
reference | References another greyscale configuration to reuse its logic. |
Sources: code/datums/greyscale/README.md:37-70
Rendering Quirks in GAGS
- Mappability: Mappers require a pre-made object icon with the same name as the item's
icon_stateto see items in mapping software. - Color IDs: Layers do not require color IDs if they are pre-colored components.
- Inheritance: Subtypes can inherit JSON configurations while changing DMI files (e.g., sharing logic between object and worn sprites).
Sources: code/datums/greyscale/README.md:82-120
TGUI Framework Rendering
The tgui framework handles the rendering of high-fidelity user interfaces using React, SASS, and Chromium (WebView2).
UI Layout Pipeline
TGUI interfaces are rendered through a specific style hierarchy:
- Base/Reset: Standardizes the browser environment.
- Atomic CSS: Reusable, low-level utility classes.
- Themes: Global color schemes and branding (e.g., Nanotrasen background).
- Interface Styles: Specific SCSS files for unique UI components.
Rendering Tools and Debuggers
- Layout Debugger: Toggled with
F11, this tool outlines all elements to identify alignment issues and hidden layout bugs. - Kitchen Sink: Accessed via
F12or the bug icon, it provides a playground for testing component rendering. - Re-render Optimization: Developers should maintain re-render times below 16ms to ensure smooth visual performance.
Sources: tgui/README.md:120-135
Asset Loading and Quirks
Asset delivery between the BYOND server and the client browser involves several specialized mechanisms.
Stylesheet and Script Loading
The system uses a robust retry mechanism for loading CSS and JS assets to prevent broken interfaces.
- Retry Logic: Assets attempt to load up to 5 times with an increasing wait period (500ms initial increment).
- CSS Verification: The loader checks
node.sheet.rules.lengthto confirm a stylesheet is actually applied before proceeding. - Inapplicable Media Trick: CSS is temporarily set to
media="only x"during fetch to prevent blocking the initial render.
Sources: tgui/packages/tgui-setup/helpers.js:183-260
BYOND Engine Rendering Constraints
The underlying engine introduces several constraints identified by the project's linting tools:
- Internal Hrefs: Links must begin with
byond://to be processed correctly. - Easing Flags: Calling
animate()with easing arguments and a defaultLINEAR_EASINGcurve results in ineffective rendering and is flagged as an error. - Map Formats: Maps must be TGM-formatted; non-TGM maps or unexpected comments in DMM files can cause rendering or conversion failures.
Sources: tools/ci/check_grep.sh:80-95, tools/ci/check_grep.sh:135-140, tools/ci/check_grep.sh:255-265
Buildmode Visual Effects
Buildmode provides specialized graphics for administrative and development manipulation.
| Mode | Visual/Rendering Behavior |
|---|---|
| Area Edit | Highlights the active area in yellow for visual feedback. |
| Effects | Contains specialized graphics used only for UI indicators in buildmode. |
| Boom | Renders explosion overlays based on configured size. |
Sources: code/modules/buildmode/README.md:1-120
Summary
Visuals in BandaStation are a hybrid of GAGS-recolored sprites and tgui-rendered web interfaces. The GAGS system provides runtime flexibility for object colors, while tgui utilizes a sophisticated CSS pipeline and a Chromium-based setup helper to manage UI rendering. Developers must account for BYOND's specific URL formatting (byond://) and animation easing constraints to ensure consistent visual behavior across different client environments.
Sources: tgui/README.md:150-170, code/datums/greyscale/README.md:130-140