Text Rendering & Subtitles
Relevant source files
The following files were used as context for generating this wiki page:
The Text Rendering & Subtitles system manages the display of FNT-based bitmap text across various game interfaces, including the book menu, title screen, movie overlays, dialogue subtitles, and the in-game HUD. It uses original Redguard font files to ensure visual fidelity while providing modern rendering paths for both native and browser environments.
Sources: crates/cyrus-text/README.md:1-6, crates/cyrus-render/src/subtitles.rs:1-8
Font Architecture and Metrics
The system centers around the Font structure, which represents a Redguard .FNT file. Each font contains glyph metrics, palette-indexed pixels, and a 6-bit palette. The system converts original rgpre FNT data into a portable format used for exported caches.
Key Components of Font Rendering
- Glyph Mapping: Maps character codes to specific glyphs in the font atlas.
- Metric Calculation: Calculates widths where the advance for most characters is
width + 1, and a space character uses the width of the!character. - Shadowing: Implements the NPC subtitle style by drawing a black copy of the text at a (+1, +1) offset beneath the primary glyphs.
- Wrapping: Breaks dialogue lines according to rules defined in
[dialog] dialog_max_text_width.
Sources: crates/cyrus-text/README.md:8-18, crates/cyrus-render/src/subtitles.rs:5-10
The diagram shows the transformation of original font files into various game display systems. Sources: crates/cyrus-text/README.md:3-18
Dialogue Subtitles
Subtitles are rendered as RGBA overlays in a fixed band at the bottom of a 640x480 virtual screen. The system uses fonts/REDSEL.FNT for most NPC dialogue and draws text centered at x = 320.
Subtitle Setttings and Logic
Subtitles are managed through a slot-based system where only the lowest active slot is displayed. The duration of a subtitle depends on whether audio is enabled:
- Speech On: The line persists for the duration of the audio clip.
- Speech Off: Duration is calculated as
clip_seconds * 256 / (21 * TICKS_PER_SECOND).
Sources: crates/cyrus-render/src/subtitles.rs:1-12, crates/cyrus-render/src/subtitles.rs:104-122
Subtitle Data Structures
| Component | Type | Description |
|---|---|---|
SubtitleRequest | Enum | Message used to request speech display or stop all lines. |
SubtitleFont | Resource | Stores the loaded Font, max width settings, and active slots. |
Line | Struct | Tracks individual subtitle text and remaining time. |
TICKS_PER_SECOND | Constant | Derived as 12.0 * 18.2065 / 18.0. |
Sources: crates/cyrus-render/src/subtitles.rs:25-30, crates/cyrus-render/src/subtitles.rs:50-58, crates/cyrus-render/src/subtitles.rs:60-64
This sequence illustrates the lifecycle of a subtitle request from initiation to expiration. Sources: crates/cyrus-render/src/subtitles.rs:43-48, crates/cyrus-render/src/subtitles.rs:100-140
Logbook and Menu Text
Text rendering in menus and the logbook involves specialized styles. The logbook uses a style table indexed by a prefix digit (0-9) found in the text data.
Reader Styles
Each style defines:
- Font Index: Which of the 5 reader fonts to use (e.g.,
FONTNORS.FNT,REDSEL.FNT). - Scale: A constant color factor (A-value) where 255 is full strength.
- Alpha: The main transparency value (B-value).
- Page Palette: If true, glyphs use the page-palette colors instead of the font's own palette.
Sources: crates/cyrus-assets/src/logbook.rs:90-100, crates/cyrus-startup/src/logbook.rs:103-112
HUD Labels and RTX Mapping
In the HUD, labels are derived from RTX files. The system maps tags (e.g., #wof, #won) to specific localized strings.
| Setting | Source File | Section | Key |
|---|---|---|---|
| Selection Font Alpha | SYSTEM.INI | [3dfx] | font_sel |
| Normal Font Alpha | SYSTEM.INI | [3dfx] | font_norm |
| Used Font Alpha | SYSTEM.INI | [3dfx] | font_used |
| Max Subtitle Width | SYSTEM.INI | [dialog] | dialog_max_text_width |
Sources: crates/cyrus-assets/src/hud_export.rs:100-112, crates/cyrus-render/src/subtitles.rs:88-95
Asset Viewer Inspection
The Asset Viewer provides a specialized UI for inspecting font assets. It allows developers to view the entire character set, adjust zoom levels, and test font rendering with custom sample text.
Font Specimen View
The viewer renders individual glyphs into a specimen sheet. It calculates the layout based on the font's character_start and line_height metrics.
- Specimen Sheet: Displays a grid of every available glyph in the font.
- Sample Input: Permits real-time testing of the font's appearance with arbitrary strings.
- Scale Adjustment: Scales the bitmap glyphs using nearest-neighbor filtering to maintain pixel clarity.
Sources: crates/cyrus-viewer/src/ui.rs:613-662
Summary
Text rendering in Cyrus is a high-fidelity implementation of the original Redguard bitmap font system. By separating font metrics and glyph data from the specific rendering targets (UI, Subtitles, HUD), the project ensures that identical font logic is applied consistently across the engine while supporting both native RGBA overlays and palette-indexed menu surfaces.
Sources: crates/cyrus-text/README.md:1-20, crates/cyrus-render/src/subtitles.rs:1-15