neon-mod-manager/README.md

🎮 Neon Mod Manager

A Cyberpunk 2077 mod manager for Linux. Built with PyQt6.

Why?

Because existing mod managers (Mod Organizer 2 / Fluorine) have problems on Linux:

• REDmod deployment fails with permission errors on FUSE mounts
• FUSE VFS blocks file access and causes crashes
• Wine prefix management is fragile and complex

Neon Mod Manager takes a simpler approach: directly manage files in the game directory. No VFS, no staging, no REDmod, no FUSE.

Features

v0.2 — Current

Feature	How it works
Enable/Disable Mods	Renames .archive ↔ .archive.disabled — no staging, no VFS
Load Order	Numeric filename prefixes (000_, 010_, 020_...) — higher number = loaded later = overrides earlier
Add Mods	Copy files directly, or drag & drop onto the window
Archive Parsing	Reads internal file paths from .archive files (RDAR format)
Deep Conflict Scan	Compares internal file paths across all enabled mods — finds real conflicts, not just name matches
Quick Conflict Scan	Fast name-based conflict detection
Script Mod Support	Manages redscript, TweakXL, CET, red4ext, ArchiveXL mods
Auto-Extract Downloads	.7z / .zip / .rar files are extracted and contents installed to correct paths automatically
Drag & Drop	Drop mod files (.archive, .zip, .7z) onto the window to install
Internal File Viewer	Right-click a mod → "Show Internal Files" to see what's inside the .archive
Profiles	Save/load mod configurations (e.g. "NSFW", "Vanilla+", "Minimal")
Nexus Mods Integration	Paste nxm:// URLs to download + auto-install, or register as browser protocol handler
No Wine needed	Pure Python + Qt, runs natively on Linux

Auto-Extract Install Paths

When you add a .zip or .7z mod, files are automatically routed to the correct location:

File Type	Destination	Mod Framework
.archive	archive/pc/mod/	Base game textures/meshes
.xl	archive/pc/mod/	ArchiveXL
.yaml / .yml	r6/tweaks/	TweakXL
.reds	r6/scripts/	redscript
.dll	red4ext/plugins/<modname>/	red4ext
.lua	bin/x64/plugins/cyber_engine_tweaks/mods/<modname>/	Cyber Engine Tweaks
.ini	engine/config/	Engine configuration

Script Mods Tab

The 📜 Script Mods tab automatically scans your game directory and shows all installed script-based mods, grouped by type:

• 🔴 REDSCRIPT — .reds files in r6/scripts/
• ⚙️ TWEAKXL — .yaml files in r6/tweaks/
• 🔧 CET — Lua mods in bin/x64/plugins/cyber_engine_tweaks/mods/
• 📦 RED4EXT — .dll plugins in red4ext/plugins/
• 🗂️ ARCHIVEXL — .xl files in archive/pc/mod/

Installation

Prerequisites

# Arch Linux / EndeavourOS
sudo pacman -S python-pyqt6 p7zip unrar

# Ubuntu / Debian
sudo apt install python3-pyqt6 p7zip unrar

# Fedora
sudo dnf install python3-pyqt6 p7zip unrar

# Or via pip (PyQt6 only)
pip install PyQt6

Note: p7zip and unrar are needed for auto-extracting .7z and .rar downloads. The Settings tab shows which tools are installed.

Download

git clone https://gitea.die-heimatlosen.eu/arch_agent/neon-mod-manager.git
cd neon-mod-manager

Run

# Wayland (most common on modern Linux)
QT_QPA_PLATFORM=wayland python3 mod_manager.py

# X11
python3 mod_manager.py

Usage

Adding Mods

1. Click ➕ Add Mod and select files (.archive, .zip, .7z, .rar, .yaml, .reds, .xl), OR
2. Drag & drop mod files onto the window, OR
3. Download from Nexus Mods (see below)

Load Order

• Mods are sorted by numeric prefix: 000_ loads first, 999_ loads last
• Later mods override earlier ones (same internal file = last one wins)
• Click 🔢 Auto-Sort to auto-assign prefixes based on current list order
• Right-click a mod → Move Up/Down to reorder manually

Enabling / Disabling

• Checkbox in the mod list to toggle on/off
• Enable All / Disable All buttons for bulk actions
• Disabled mods get .archive.disabled extension (not deleted!)

Conflict Detection

• ⚡ Quick Scan — fast name-based check for duplicate mod names
• 🔍 Deep Scan — parses all .archive files and compares internal file paths
  • Shows which internal files (textures, meshes, etc.) are overridden by multiple mods
  • Files in 3+ mods are highlighted red, 2 mods in orange
  • Progress bar shows scan status

Viewing Internal Files

• Right-click any mod → 📋 Show Internal Files
• Shows version, file count, and up to 50 internal file paths from the .archive

Profiles

1. Set up your mods the way you want them
2. Go to 💾 Profile tab
3. Enter a name (e.g. "NSFW Full", "Vanilla+") and click Save Profile
4. Switch between profiles anytime from the dropdown at the top

Nexus Mods Integration

1. Get your API key from Nexus Mods
2. Go to 🌐 Nexus Mods tab and paste your key
3. Option A: Paste nxm:// URLs manually and click Download & Install
   • Downloads the mod, auto-extracts if needed, and installs to correct paths
4. Option B: Click 🔗 Register nxm:// Protocol Handler
   • Then clicking "Download" on Nexus Mods website automatically sends the mod to Neon Mod Manager
   • Downloads and installs silently in the background

How It Works (Technical)

No VFS / No Staging

Unlike MO2/Fluorine which use a virtual filesystem (FUSE on Linux), Neon Mod Manager copies files directly to the game directory. This avoids:

• FUSE mount permission issues
• REDmod deployment failures
• Wine prefix corruption

Load Order via Filename

Cyberpunk 2077 loads .archive files in alphabetical order. Neon Mod Manager uses numeric prefixes:

000_MyBodyMod.archive     → loads first
010_MyTextureMod.archive  → loads second
020_MyAdMod.archive       → loads third (overrides earlier)

Enable/Disable

Mods are renamed in-place:

• Enable: MyMod.archive.disabled → MyMod.archive
• Disable: MyMod.archive → MyMod.archive.disabled

The game ignores .disabled files completely.

Archive Parsing

.archive files use the RDAR format:

• Magic: RDAR (4 bytes)
• Version (uint32)
• File table offset (uint64)
• File count (uint32)

The file table contains entries with hash, offset, size, and null-terminated UTF-8 path strings. Neon Mod Manager reads these to detect which internal files (textures, meshes) are overridden by multiple mods.

Auto-Extract

When a .zip or .7z is added:

1. File is extracted to /tmp/neon-mod-extract/
2. Files are scanned and routed to correct game paths based on extension
3. Directory structure from the archive is preserved (e.g. r6/scripts/MyMod/ stays intact)
4. Temporary extraction directory is cleaned up

Configuration

Config is stored at ~/.config/neon-mod-manager/config.json:

{
    "game_path": "/mnt/Spiele/Heroic/Cyberpunk 2077",
    "mod_dir": "archive/pc/mod",
    "last_profile": "Default",
    "nexus_api_key": "",
    "auto_prefix": true
}

Profiles are stored at ~/.config/neon-mod-manager/profiles/*.json.

License

MIT — do whatever you want.

Roadmap

• Archive file parsing (read internal file list for real conflict detection) ✅ v0.2
• REDmod script mod support (r6/tweaks) ✅ v0.2
• Auto-extract .7z / .zip downloads ✅ v0.2
• Nexus Mods search (browse mods without leaving the app)
• Mod update detection (compare versions)
• Mod categories and tags
• Dark/light theme switcher
• Backup/restore vanilla files
• Mod dependency checker