User Interface
Relevant source files
The following files were used as context for generating this wiki page:
The User Interface (UI) system manages the presentation of game state, interactive menus, and diagnostic tools. It reconstructs the faithful visual experience of the original game using data-driven layouts while providing modern inspection capabilities for development.
The UI consists of three primary layers:
- In-game HUD and Overlays: Displays real-time status like the candle, compass, and item inventory.
- Data-Driven Menus: Recreates the "Book" menu system using the original game's configuration files.
- Diagnostic Viewer: Provides a modern, egui-based interface for inspecting 3D models, worlds, and textures.
Sources: crates/cyrus-assets/src/lib.rs, crates/cyrus-viewer/src/ui.rs
HUD and Overlay Architecture
The HUD system exports and renders installed artwork, fonts, and layouts for portable presentation. It uses SYSTEM.INI, ITEM.INI, and WORLD.INI to determine widget positions and behavior.
Component Export
The prepare function in the HUD export module reads binary assets and configuration to build a HudAsset structure. This structure includes:
- Static Widgets: Candle, compass, and logbook icon positions.
- Dynamic Slots: Power-up slots and item bitmaps.
- Interaction Bindings: Control codes derived from
KEYS.INI.
Sources: crates/cyrus-assets/src/hud_export.rs:56-120
HUD Data Structure
The following diagram illustrates the relationship between the exported HUD data and its source configuration.
The export process transforms raw game data into a structured HudAsset for the renderer.
Sources: crates/cyrus-assets/src/hud_export.rs:188-250
Menu System (The Book)
The menu system is data-driven, recreating the original "book" interface where pages contain selectable entries and 3D models.
Menu Pages and Entries
Pages are parsed from MENU.INI. Each MenuPage contains:
- Entries: Interactive items with text, action IDs, and selection flags.
- Surfaces: Texture indices mapped from TEXBSI banks.
- Selection: Tracks which entry is currently active or selectable.
Sources: crates/cyrus-assets/src/startup/menu_export.rs:165-210
Key Menu Components
| Component | Description | Source |
|---|---|---|
MenuModel | 3D geometry for pages, tables, and buttons within the menu. | MENU.ROB |
MenuPicture | 2D images for widgets like checkmarks and sliders. | MM_CHECK.GXA, MM_SLIDE.GXA |
Action ID | Integer code determining logic (e.g., -2 for Exit, 504 for Subtitles). | MENU.INI |
Sources: crates/cyrus-assets/src/startup/menu_export.rs:105-150
Logbook and Credits
The logbook system handles the presentation of the player's journal and the game credits. It uses a specific styling table to map digits (0-9) to font properties.
Credits Parsing
The system parses CREDITS.TXT into CreditLine records. Each line supports specific alignment and styling.
The CreditLine structure represents a single formatted entry in the credits roll.
Sources: crates/cyrus-assets/src/logbook.rs:25-50
Reader Styles
The reader style table defines how text appears on the logbook paper. It specifies:
- Font Index: Which of the 5 reader fonts to use.
- Color Factor (Scale): The strength of the color (0-255).
- Alpha: The transparency of the text (0-255).
Sources: crates/cyrus-assets/src/logbook.rs:90-110
Asset Viewer UI
The Asset Viewer provides a diagnostic interface built with egui. It allows developers to browse the asset catalog and inspect individual files.
Viewer State and Navigation
The Viewer resource maintains the UI state, including search queries, selected assets, and camera parameters. It organizes assets into categories like Models, Worlds, and Palettes.
Sources: crates/cyrus-viewer/src/ui.rs:50-90
Inspection Controls
The viewer supports multiple shading and camera modes for 3D assets:
- Shading Modes: Textured, Unlit, Solid, and Wireframe.
- Camera Modes: Orbit (default for objects) and Flycam (for world exploration).
- Data Modes: Content (visual), JSON (raw fields), and Fields (decoded tree).
Sources: crates/cyrus-viewer/src/ui.rs:10-40
Interaction Flow
Selecting an asset triggers a reset of the viewer state and initiates an asynchronous load of the preview data.
Sources: crates/cyrus-viewer/src/ui.rs:155-180
Summary
The UI system separates data extraction from presentation. The cyrus-assets crate provides the portable data structures (HudAsset, MenuAsset, LogbookArtwork), while specialized plugins in the game and viewer crates handle interactive rendering. This architecture ensures that the complex UI rules of the original engine are preserved while allowing for modern debugging tools.