Crate Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Cyrus implements a modular workspace architecture to rebuild The Elder Scrolls Adventures: Redguard using Rust and the Bevy engine. The project separates concerns between core engine logic, asset preparation, platform-specific hosts, and preservation-focused data parsing. It relies on a sibling project, redguard-preservation (crate rgpre), for file format specifications and engine facts.
Sources: AGENTS.md:5-9, Cargo.toml:1-5
Workspace Structure
The Cyrus workspace consists of multiple specialized crates that communicate through well-defined interfaces. Dependencies flow from high-level application crates down to specialized library crates.
Dependency Flow
The following diagram illustrates the primary relationship between the main workspace components.
The workspace uses a single-writer model for local state and maintains one-way dependencies to prevent circular references.
Sources: Cargo.toml:34-52, crates/cyrus-game/README.md:3-6, crates/cyrus-config/src/file.rs:20-22
Core Component Responsibilities
| Crate | Primary Responsibility |
|---|---|
cyrus | Native executable; handles argument parsing, windowing, and host-specific storage. |
cyrus-game | Portable gameplay state, fidelity policies, and deterministic player controllers. |
cyrus-assets | Asset preparation, portable cache records, and install discovery. |
cyrus-world | World loading and spatial data management. |
cyrus-script | SOUP program types, operand validation, and script execution. |
cyrus-config | Atomic local state document storage and platform directory resolution. |
Sources: crates/cyrus/README.md:3-6, crates/cyrus-game/README.md:3-5, crates/cyrus-assets/README.md:15-18, Cargo.toml:34-52
Asset and State Management
Portable Cache System
cyrus-assets generates portable cache records from the original game installation. This system enables the browser version to function without a server-side exporter by using pre-prepared data.
- Schema Versioning: Every record includes a schema version. Incompatible cache records are rejected to ensure data integrity.
- Asset Categorization: Records are grouped into categories such as animations, collision, environment, menu, and HUD.
- Identity Checks: Content identity checks prevent loading mismatched sidecars (e.g., animation sidecars from different world exports).
Sources: crates/cyrus-assets/README.md:6-12, crates/cyrus-assets/README.md:104-106
Atomic Local Storage
cyrus-config provides a robust mechanism for writing local state documents. It ensures that failed publications do not corrupt existing data.
- Create a unique temporary candidate file.
- Write the complete byte stream to the candidate.
- Sync the file to disk.
- Rename the candidate to the target destination.
Sources: crates/cyrus-config/src/file.rs:20-45
Gameplay and Fidelity
cyrus-game manages the simulation and enforces the project's fidelity rules.
Fidelity Areas
Behaviors that deviate from the original game are categorized into fidelity Areas (e.g., Water, Fog, Sky). These run in one of two modes:
- Faithful: Reproduces original visuals, logic, and timing exactly.
- Modern: Opt-in branches for higher frame rates, modern controls, or enhanced graphics.
Sources: AGENTS.md:21-28, crates/cyrus/README.md:60-70
Execution Flow
Platform Abstraction
Cyrus maintains strict boundaries between engine logic and platform-specific implementations.
- Native Host: Uses
cyrus-configfor filesystem access and handles TCP control servers. It supports direct world exporting and headless auditing. - Web Host: Uses a selected read-only install service. It relies on
wasm-bindgenandweb-sysfor browser integration. - Common Interface: Both hosts use the same CLI/URL parameter names (e.g.,
--scene/?scene=) to ensure behavior parity.
Sources: crates/cyrus/README.md:46-58, crates/cyrus-web/Cargo.toml:19-25, crates/cyrus-assets/README.md:15-20
The architecture of Cyrus prioritizes technical accuracy and portability, ensuring that the core engine remains independent of whether it is running as a native Windows/Linux application or within a web browser. Re-exporting assets is required when schema versions or rgpre metadata changes to maintain compatibility between the prepared data and the engine.
Sources: crates/cyrus-assets/README.md:23-28, AGENTS.md:95-100