Native Application Launch Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Native Application Launch Flow governs how the cyrus executable initializes, locates game assets, and prepares the runtime environment. It handles command-line arguments, verifies the original Redguard installation, and transitions the Bevy application from a loading state to active gameplay or asset viewing.
Sources: crates/cyrus/README.md, crates/cyrus-app/README.md
Launch Sequence Overview
The launch process begins with argument parsing and environment resolution. If no valid installation directory is provided or discovered, the application displays a native installation picker. Once the path is resolved, the system starts background asset preparation.
The diagram shows the transition from binary execution to the interactive menu or game state.
Sources: crates/cyrus/src/main.rs, crates/cyrus-app/README.md, crates/cyrus-startup/src/preparation.rs:18-30
Installation Discovery and Validation
The application uses launch::InstallArgs to find the required game data. It follows a specific order of precedence to resolve the REDGUARD_DIR:
- Explicit
--install PATHcommand-line argument. REDGUARD_DIRenvironment variable.- The remembered location in
install.jsonwithin the config directory. - Default local or GOG installation folders.
If discovery fails, the application inserts the install picker into the existing egui context. The picker provides "Browse" and "Continue" options. "Continue" validates the selected root, saves it to install.json, and inserts the GameInstall resource.
Sources: crates/cyrus-app/README.md, crates/cyrus/README.md, README.md
Startup Preparation and Preloading
Once the installation is resolved, the LoadingPlugin manages asset preparation. This occurs in a background worker thread to prevent blocking the main application loop.
Preload Worker
The worker thread performs different tasks based on the launch context:
- Presentation Launch: Exports required menu and HUD assets to the local cache.
- Direct/Headless Launch: Scans the installation and parses every known file to verify format coverage.
Progress Tracking
The LoadingProgress resource tracks the state of the background worker. The poll system monitors a communication channel to update the UI with the number of files parsed and the current progress fraction.
| Message Type | Resulting Action |
|---|---|
Progress::MenuReady | Inserts MenuPrepared resource; enables menu rendering. |
Progress::File | Updates LoadingProgress with file name, done count, and total count. |
Progress::Done | Inserts Preloaded resource and transitions to AppState::InGame. |
Progress::Failed | Logs the error and displays it in the startup presentation. |
Sources: crates/cyrus-startup/src/preparation.rs:43-118, crates/cyrus-startup/README.md
Execution Modes and Commands
The cyrus binary supports multiple execution modes defined by CLI flags. These flags determine which plugins are assembled and whether a window is created.
Headless vs. Windowed
Windowed launches include the full suite of presentation, audio, and rendering plugins. Headless launches omit the camera and audio backend, focusing on control servers or world audits.
CLI Parameters Summary
| Flag | Description |
|---|---|
--scene <ID> | Loads a specific map directly, bypassing the menu. |
--headless | Runs without a window for servers or automated tasks. |
--skip-startup | Bypasses the splash animation and title screen. |
--new-game | Starts a new game immediately (implies --skip-startup). |
--export-all-worlds | Exports every world from WORLD.INI to the cache. |
--control <ADDR> | Starts the TCP control server (default 127.0.0.1:7117). |
Sources: crates/cyrus/README.md, crates/cyrus/src/main.rs
Startup Presentation Flow
When not skipped, the startup presentation follows a timed sequence of frames.
The sequence diagram illustrates the timing between visual presentation and background asset export.
Sources: crates/cyrus-startup/README.md, crates/cyrus-startup/src/preparation.rs:56-66
Conclusion
The Native Application Launch Flow ensures that cyrus finds a valid Redguard installation before initiating gameplay. By decoupling asset preparation into a background worker and providing a robust discovery mechanism, the system maintains a responsive UI while handling complex file parsing and cache generation.
Sources: crates/cyrus-app/README.md, crates/cyrus-startup/README.md