Project Introduction
Relevant source files
The following files were used as context for generating this wiki page:
cyrus is a faithful rebuild of the 1998 game The Elder Scrolls Adventures: Redguard using Rust and the Bevy engine. The project aims to provide a modern, portable implementation that reads original game data from a user's local GOG installation without distributing any copyrighted assets. Sources: README.md:3-10, AGENTS.md:3-8
The project currenty supports world viewing, menu navigation, and movie playback. Full gameplay implementation is ongoing. Sources: README.md:16-25, dev/pages/index.html:132-136
Core Philosophy and Development Rules
Cyrus follows a "Faithful by Default" policy. This means the engine reproduces the original player experience regarding visuals, audio, and logic, while leveraging modern hardware for better performance and frame rates. Sources: README.md:86-90, AGENTS.md:27-35
Development Pillars
- Read-Only Data: The project never writes to the original game directory. Sources: AGENTS.md:23-24
- No Asset Distribution: The repository contains no original game data, code, or extracted assets. Sources: AGENTS.md:18-20, CONTRIBUTING.md:44-46
- Evidence-Based Logic: Developers derive constants and formulas from original game data or preservation research rather than guessing. Sources: AGENTS.md:36-41, CONTRIBUTING.md:33-35
- Agent-Driven Code: The project is written by LLM coding agents under human direction. Sources: README.md:118-120, dev/pages/index.html:148-150
Architecture Overview
The system is composed of several specialized crates and external integrations. It depends heavily on redguard-preservation (crate rgpre) for file format parsing and engine facts. Sources: AGENTS.md:3-7, crates/cyrus-game/README.md:3-6
System Relationships
The following diagram illustrates the high-level flow from original assets to the rendered application.
Sources: README.md:3-5, AGENTS.md:3-8, crates/cyrus/README.md:3-7
Component Breakdown
The project splits functionality across multiple crates to maintain architectural boundaries. Sources: AGENTS.md:117-120
Primary Crates
| Crate | Responsibility |
|---|---|
cyrus | The main binary; handles argument parsing, install discovery, and Bevy app assembly. |
cyrus-game | Manages portable gameplay state, player input, script hosting, and fidelity policies. |
cyrus-assets | Handles portable cache records and native install preparation. |
cyrus-startup | Manages splash screens, title menus, and world-entry loading. |
cyrus-web | Implements the browser-based version using WASM. |
Sources: crates/cyrus/README.md:3-7, crates/cyrus-game/README.md:3-6, crates/cyrus-assets/Cargo.toml:2-3, crates/cyrus-startup/Cargo.toml:2-3, crates/cyrus-web/Cargo.toml:2-3
Native vs. Browser Deployment
Cyrus provides two primary ways to run the project.
- Native Application: Compiled for Windows, Linux, or macOS. It uses local configuration directories (e.g.,
~/.config/cyrus) for persistent settings. Sources: README.md:43-52, dev/pages/index.html:92-108 - Browser Build: A WASM-based implementation that accesses local files through a browser-safe file picker or a local python-based viewer server. Sources: README.md:54-68, dev/pages/index.html:115-121
Execution and Interaction
The application supports various command-line flags and URL parameters to control startup behavior and scene loading. Sources: crates/cyrus/README.md:41-55
Shared Configuration Options
The following options apply to both the native CLI and the browser URL parameters.
| Option | Parameter | Effect |
|---|---|---|
--install | ?install= | Defines the path to the original Redguard directory. |
--scene | ?scene= | Loads a specific map stem or world ID directly. |
--skip-startup | ?skip-startup= | Bypasses the splash screen and goes directly to the title. |
--new-game | ?new-game= | Automatically starts a new game from the book menu. |
--movie | ?movie= | Plays a specific cinematic via its MENU.INI index. |
Sources: crates/cyrus/README.md:41-55
The Asset Viewer
A separate cyrus-viewer application is provided to inspect Redguard's file formats, including models, worlds, textures, fonts, animations, and scripts. Sources: README.md:70-76, dev/pages/index.html:101-108
Summary
Cyrus serves as a modern reimplementation of The Elder Scrolls Adventures: Redguard, focusing on technical fidelity and portability. By separating asset parsing into the redguard-preservation project and using a modular Rust architecture, it enables the original game to run on modern systems and web browsers while maintaining strict adherence to legal and technical standards. Sources: README.md:3-10, AGENTS.md:3-15, dev/pages/index.html:125-130