<div align="center"> <img src="./src-tauri/icons/frontendlogo.ico" alt="RivalNxt Logo" width="128" height="128">

RivalNxt

Marvel Rivals Mod Manager

One desktop app to manage, activate, and validate Marvel Rivals mods with conflict detection, NexusMods integration, and blazing-fast local database.

Features • Installation • Development Guide • Contributing

</div>

---

✨ Features

🎯 Core Functionality

• Smart Mod Management - Activate, deactivate, and organize mods with per-mod and bulk actions
• Conflict Detection - Automatic detection and resolution of mod conflicts with tag rebuilding
• Auto-Detection - Automatically detects Marvel Rivals installation path via Steam/Epic Games registry and archive tools (WinRAR)
• One-Click Downloads - Click "Download with Mod Manager" on NexusMods to instantly download and install mods
• Background Processing - Automatic download processing via NXM protocol without manual intervention

🔧 Technical Highlights

• Local-First Database - Portable SQLite with health checks and inspection utilities
• Rust-Powered Core - Native Rust rust-ue-tools library with PyO3 bindings via Maturin
• Modern Tech Stack - Tauri 2 desktop shell + React/Vite frontend + FastAPI/Python backend
• CI/CD Automation - GitHub Actions workflow for automated builds and releases
• One-Click Build - Complete build script for easy local development setup

🌐 NexusMods Integration

• Browser Integration - "Download with Mod Manager" button on NexusMods automatically opens RivalNxt
• NXM Protocol - Bi-directional handoff system with Windows registry integration
• Background Processing - Automatic download processing via NxmBackgroundListener component
• API Integration - Metadata fetching and update notifications
• Test Functionality - Built-in protocol validation tools

⚡ Rust UE Tools Library

• PyO3 Integration - Python bindings built with Maturin for seamless interop
• Native Performance - Rust library replaces slow Python/external tool processing
• PAK/UTOC Support - Direct unpacking and listing without external CLI dependencies
• AES Encryption - Built-in support for encrypted mod files
• Batch Processing - Parallel processing for multiple mod files
• Archive Support - Handles ZIP and RAR archives containing mod files

🚀 Installation

1. Download the Installer

• Go to the Releases page.
• Download the latest setup file, for example: RivalNxt_0.5.0_x64-setup.exe (or any newer version).

2. Install & Launch

• Run the installer.
• Launch the application after installation completes.

3. Configure Paths

RivalNxt can automatically detect your Marvel Rivals installation if installed via Steam or Epic Games Store.

In Settings:

• Local downloads directory → Select the folder where your Marvel Rivals mods are downloaded/saved (create anywhere or use existing folder)
• Nexus Personal API Key → Get your API key (scroll all the way down) and paste it into RivalNxt

💡 Tip: The app also auto-detects archive tools (WinRAR) for extracting mod files.

⚠️ Mod Folder Naming Convention

Every mod inside your marvel_rivals_local_downloads_root directory must follow this format:

<name>-<modid>-<version>

Example: CoolSkin-12345-1.0.0

This helps the app detect and track mods accurately.

5. You're Ready to Use the App

No Node.js, Rust, or Python is needed for normal usage.

For Developers

See the Development Guide below.

🏗️ Architecture

%%{init: {
  "flowchart": {
    "nodeSpacing": 40,
    "rankSpacing": 40
  }
}}%%
flowchart LR
    FE["🎨 React + Vite"]
    Tauri["🖥️ Tauri 2.0"]
    API["⚙️ FastAPI"]
    DB[("💾 SQLite")]
    RustUE["📦 Rust UE Tools"]

    FE <-->|HTTP/IPC| Tauri
    Tauri <-->|HTTP| API
    API <-->|ORM| DB
    API <-->|PyO3| RustUE
    Tauri <-->|Rust API| RustUE

    classDef frontend fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    classDef desktop fill:#ffc131,stroke:#333,stroke-width:2px,color:#000
    classDef backend fill:#009688,stroke:#333,stroke-width:2px,color:#fff
    classDef shared fill:#dea584,stroke:#333,stroke-width:2px,color:#000
    classDef data fill:#4caf50,stroke:#333,stroke-width:2px,color:#fff

    class FE frontend
    class Tauri desktop
    class API backend
    class RustUE shared
    class DB data

Tech Stack

• Frontend: React 18, TypeScript, Vite 6, Radix UI, Tailwind CSS
• Backend: Python 3.10+, FastAPI, Uvicorn, SQLAlchemy
• Desktop: Tauri 2.0 (Rust), Windows native
• Rust UE Tools: Native Rust library with dual interfaces (Rust API + PyO3 bindings via Maturin)
• Database: SQLite with optimized materialized views

🦀 Rust UE Tools Library

RivalNxt includes a high-performance native Rust library (rust-ue-tools) that provides programmatic access to Unreal Engine PAK and UTOC file operations, replacing external command-line tools like repak and retoc_cli.

Key Features

• ✅ PAK File Support: Unpack .pak files without external tools
• ✅ UTOC File Support: List contents of .utoc files (UE5 IoStore format)
• ✅ AES Encryption: Handle encrypted mod files with proper key management
• ✅ Compression Support: Full support for Oodle, Zstd, Zlib, LZ4 compression
• ✅ Archive Processing: Extract ZIP and RAR archives containing mod files
• ✅ Parallel Processing: Leverage Rayon for concurrent file operations
• ✅ Python Bindings: PyO3 integration for seamless Python usage

Usage Examples

Basic Asset Path Extraction

use rust_ue_tools::Unpacker;

let unpacker = Unpacker::new();
let zip_path = "mod_file.zip";
let aes_key = Some("0C263D8C22DCB085894899C3A3796383E9BF9DE0CBFB08C9BF2DEF2E84F29D74");

match unpacker.extract_asset_paths_from_zip(zip_path, aes_key, false) {
    Ok(asset_paths) => {
        for asset in asset_paths {
            println!("Asset: {}", asset);
        }
    }
    Err(e) => {
        println!("Error: {}", e);
    }
}

PAK File Unpacking

use rust_ue_tools::{Unpacker, PakUnpackOptions};

let unpacker = Unpacker::new();
let options = PakUnpackOptions::new()
    .with_aes_key(aes_key.unwrap_or_default())
    .with_strip_prefix("../../../")
    .with_force(true)
    .with_quiet(false);

match unpacker.unpack_pak("mod.pak", "output_dir", &options) {
    Ok(asset_paths) => {
        println!("Unpacked {} files", asset_paths.len());
    }
    Err(e) => {
        println!("Error unpacking: {}", e);
    }
}

UTOC File Listing

use rust_ue_tools::{Unpacker, UtocListOptions};

let unpacker = Unpacker::new();
let options = UtocListOptions::new()
    .with_aes_key(aes_key.unwrap_or_default())
    .with_json_format(false);

match unpacker.list_utoc("mod.utoc", &options) {
    Ok(asset_paths) => {
        for asset in asset_paths {
            println!("Asset: {}", asset);
        }
    }
    Err(e) => {
        println!("Error listing: {}", e);
    }
}

Migration from Python

The Rust library replaces the original Python zip_to_asset_paths.py script:

Before (Python)

from core.assets.zip_to_asset_paths import extract_uasset_paths_from_zip

asset_paths = extract_uasset_paths_from_zip(
    "mod.zip",
    repak_bin="path/to/repak",
    aes_key="your-key"
)

After (Rust)

use rust_ue_tools::Unpacker;

let unpacker = Unpacker::new();
let asset_paths = unpacker.extract_asset_paths_from_zip(
    "mod.zip",
    Some("your-key"),
    false
)?;

Building from Source

# Build with Maturin (recommended for PyO3 bindings)
cd src-tauri/src/rust-ue-tools
maturin build --release --features pyo3

# Install the built wheel
pip install target/wheels/*.whl

# Manual Rust build (library only)
cargo build --release --features pyo3

# Run tests
cargo test

# Build documentation
cargo doc --open

Performance Benefits

• 🚀 10-50x Faster: Native Rust vs Python subprocess calls
• 📦 No External Dependencies: Eliminates repak.exe/retoc_cli.exe requirements
• 💾 Memory Efficient: Streams data instead of loading entire files
• 🔄 Parallel Processing: Rayon-powered concurrent operations
• 📊 Progress Tracking: Built-in progress reporting for long operations
• 🐍 Python Integration: Maturin-based PyO3 bindings for seamless Python usage

💻 Development Guide

Prerequisites

• Windows 10/11 (for desktop builds)
• Node.js 18+ and npm
• Rust toolchain via rustup
• Python 3.10+
• Maturin for PyO3 builds: pip install maturin
• Git

Quick Start (One-Click Build)

For new users, use the automated build script that handles everything:

# Clone repository with submodules
git clone --recurse-submodules https://github.com/Rounak77382/Project_ModManager_Rivals.git
cd