Configuration & Preferences
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration & Preferences system manages user-specific state, environment settings, and gameplay choices while ensuring the original game installation remains read-only. This system handles persistent data such as remembered installation paths, audio levels, graphics fidelity, and log files across different operating systems and the browser.
The cyrus-config crate provides the foundational storage logic, employing atomic file operations to prevent data corruption. The cyrus-game crate builds upon this to manage gameplay-specific Preferences and fidelity policies, allowing users to toggle between "Faithful" and "Modern" behaviors.
Sources: [crates/cyrus-config/README.md:1-6](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/README.md#L1-L6), [AGENTS.md:rule-2](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/AGENTS.md%3Arule-2), [crates/cyrus-game/README.md:12-16](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-game/README.md#L12-L16)
Directory Architecture
Cyrus organizes local state into specific categories: config, cache, logs, and screenshots. The system resolves the root directory based on a strict priority order to support development, portable use, and standard platform installations.
Root Resolution Priority
- Environment Variable: If
CYRUS_CONFIG_DIRis set, the system uses this path for all state. - Local Directory: If a
game-config/directory exists in the current working directory, it takes precedence. This is the default for development checkouts. - Platform Standard: If neither of the above applies, the system uses platform-specific application data folders.
Sources: [crates/cyrus-config/src/lib.rs:9-25](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/lib.rs#L9-L25), [crates/cyrus-config/src/lib.rs:64-75](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/lib.rs#L64-L75)
Platform-Specific Paths
| Platform | Configuration (config) | Cache (cache) | Logs (logs) |
|---|---|---|---|
| Linux | ~/.config/cyrus | ~/.cache/cyrus | ~/.local/state/cyrus/logs |
| macOS | ~/Library/Application Support/cyrus | ~/Library/Caches/cyrus | config/logs |
| Windows | %APPDATA%\cyrus\config | %LOCALAPPDATA%\cyrus\cache | %LOCALAPPDATA%\cyrus\data\logs |
Sources: [crates/cyrus-config/README.md:25-33](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/README.md#L25-L33), [crates/cyrus-config/src/lib.rs:78-90](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/lib.rs#L78-L90)
Directory Resolution Flow
The following diagram illustrates the logic used by Dirs::choose to determine the active storage paths.
Diagram shows the selection hierarchy for persistent storage locations.
Sources: [crates/cyrus-config/src/lib.rs:56-62](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/lib.rs#L56-L62)
Atomic Storage Operations
Cyrus uses atomic file operations to ensure that configuration files are never left in a partially written or corrupted state.
Read Mechanism
The read function attempts to load bytes from a path. It treats a NotFound error as a successful return of None, allowing callers to handle missing configuration gracefully. Any other I/O error is returned with path context.
Sources: [crates/cyrus-config/src/file.rs:13-20](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/file.rs#L13-L20)
Write Mechanism
The write function performs a multi-step atomic replacement:
- It creates a hidden candidate file (e.g.,
.cyrus-123-0.tmp) in the target directory. - It writes the full byte buffer to the candidate file.
- It calls
sync_allto ensure data is physically persisted to the storage medium. - It renames the candidate file to the final destination path, which is an atomic operation on most filesystems.
- If any step before the rename fails, it removes the temporary candidate to clean up.
Sources: [crates/cyrus-config/src/file.rs:26-55](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/file.rs#L26-L55)
Atomic Write Sequence
Sequence shows the safety steps taken to prevent data loss during configuration updates.
Sources: [crates/cyrus-config/src/file.rs:32-49](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/src/file.rs#L32-L49)
Gameplay Preferences and Fidelity
Gameplay preferences are managed through the Preferences structure in cyrus-game. These settings bridge the gap between the original game's data-driven behavior and modern user requirements.
Fidelity Modes
Cyrus implements a "Faithful by default" policy. Behavioral deviations are categorized into fidelity Areas.
- Faithful: Reproduces original visuals, audio, and logic exactly as the player experienced them in 1998.
- Modern: Enables opt-in enhancements like modern water, fog, or sky rendering.
Sources: [AGENTS.md:rule-3](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/AGENTS.md%3Arule-3), [crates/cyrus/README.md:65-71](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus/README.md#L65-L71)
Configuration Files
Native builds store these settings in the config directory resolved by cyrus-config:
settings.toml: General game settings and fidelity modes.install.json: The remembered path to the Redguard GOG installation.REDGUARD.CHT: Local cheat overrides.REDGUARD.CPF: Console preferences.
Sources: [crates/cyrus/README.md:12-25](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus/README.md#L12-L25), [crates/cyrus/README.md:104-122](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus/README.md#L104-L122)
Preferences Summary Table
| Preference Category | Persistence File | Behavior Policy |
|---|---|---|
| Audio | settings.toml | Music and SFX volume levels. |
| Fidelity | settings.toml | Toggles for Modern vs Faithful (Water, Fog, Sky). |
| Installation | install.json | Path to RGFX.EXE and game data. |
| Cheats | REDGUARD.CHT | Overrides for task, animation, and node markers. |
| Console | REDGUARD.CPF | Editor settings and history. |
Sources: [crates/cyrus/README.md:65-75](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus/README.md#L65-L75), [crates/cyrus/README.md:104-110](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus/README.md#L104-L110), [crates/cyrus-game/README.md:12-16](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-game/README.md#L12-L16)
Browser Implementation
The browser build (WASM) does not have access to a standard filesystem. It utilizes localStorage for persistence. The cyrus-config crate provides stubs for the directory layout to ensure code compatibility, but actual reads and writes are redirected to web-native storage APIs. Users must manually select their game folder via a browser picker, and this selection is not permanently remembered in the same way as native paths due to browser security restrictions.
Sources: [crates/cyrus-config/README.md:35-37](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/crates/cyrus-config/README.md#L35-L37), [README.md:52-57](https://github.com/michidk/cyrus/blob/0105d8ea914aee3bfcd1254113406fd23c770422/README.md#L52-L57)
The Configuration & Preferences system provides a robust, platform-agnostic layer for managing the user's environment. By isolating user state from game data and employing atomic write patterns, Cyrus maintains a high level of technical fidelity and data integrity.