Fidelity Mode Toggles
Relevant source files
The following files were used as context for generating this wiki page:
Fidelity Mode Toggles manage behavioral deviations from the original The Elder Scrolls Adventures: Redguard (1998) game. These toggles allow the engine to switch between "Faithful" behavior, which reproduces the original player experience, and "Modern" behavior, which introduces opt-in enhancements.
The system ensures that cyrus remains faithful by default. Every behavior that differs from the original game registers under a specific Area and executes only if the configured Mode matches.
Fidelity Policy
The project enforces a "Faithful by default" rule for every gameplay area. Faithful behavior encompasses visuals, audio, controls, camera logic, script timing, and game outcomes. Deviations exist only in Modern branches and never in shared execution paths.
Technical improvements, such as increased frame rates, faster loading, and optimized memory use, do not require fidelity toggles. These are considered inherent benefits of modern hardware rather than behavioral deviations.
Sources: AGENTS.md:29-37, README.md:107-111, crates/cyrus-game/src/fidelity.rs:1-4
Core Data Structures
The fidelity system relies on two primary enums and a centralized resource to manage state across the engine.
Mode and Area Definitions
Mode: Defines the target behavior level. TheDefaultisFaithful.Area: Categorizes different gameplay systems that support multiple behaviors.
| Enum | Variants | Description |
|---|---|---|
Mode | Faithful, Modern | The two selectable behavior states. |
Area | PlayerController, Camera, Water, Fog, Sky, Lighting, Music | Specific subsystems supporting fidelity toggles. |
Sources: crates/cyrus-game/src/fidelity.rs:9-37
Fidelity Resource
The Fidelity struct acts as a Bevy Resource, storing the current Mode for every defined Area. It provides helper methods to get and set modes for specific areas.
This diagram illustrates the relationship between the central Fidelity resource and the enums defining modes and areas.
Sources: crates/cyrus-game/src/fidelity.rs:39-64
System Integration
Developers use run conditions to branch logic based on the current fidelity state. The in_mode function returns a Bevy run condition that checks if a specific Area is set to a specific Mode.
Run Condition Usage
Systems execute only when the fidelity state matches the requirement. For example, a modern camera system uses .run_if(in_mode(Area::Camera, Mode::Modern)).
This flowchart shows how systems use the in_mode condition to select the appropriate execution path.
Sources: crates/cyrus-game/src/fidelity.rs:66-69
Configuration and External Control
Fidelity settings persist in settings.toml within the user's config directory. Users can override individual areas in the configuration file.
MCP Interface
The Model Context Protocol (MCP) server provides a set_fidelity tool. This tool allows developers or external agents to switch fidelity modes at runtime by providing an area and a mode string.
| Tool Name | Parameters | Description |
|---|---|---|
set_fidelity | area (string), mode (string) | Changes the mode of a specific area during execution. |
Sequence of Fidelity Change
The sequence diagram details how an external command propagates through the MCP server to update the game's internal fidelity state.
Sources: crates/cyrus-render/tests/fidelity.rs:13-17, crates/cyrus-mcp/src/main.rs:72-76, crates/cyrus-mcp/src/main.rs:222-231, CONTRIBUTING.md:14
Summary of Areas
| Area | Purpose | Modern Behavior Details |
|---|---|---|
PlayerController | Movement logic | Enhanced or modern controls. |
Camera | View behavior | Modern perspective or tracking. |
Water | Water rendering | Enhanced shader effects. |
Fog | Distance obscuration | Modern volumetric or distance fog. |
Sky | Background rendering | Enhanced skyboxes or scrolling. |
Lighting | Scene illumination | Currently reuses faithful terrain implementation. |
Music | Audio playback | Mutes CD-ROM data sector noise in audio tracks. |
Sources: crates/cyrus-game/src/fidelity.rs:27-37, crates/cyrus-game/src/fidelity.rs:40-49