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 archive/pc/mod/. No VFS, no staging, no REDmod, no FUSE.

Features

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 .archive files directly to mod directory
Conflict Detection	Scans for duplicate file patterns across enabled mods
Profiles	Save/load mod configurations (e.g. "NSFW", "Vanilla+", "Minimal")
Nexus Mods Integration	Paste nxm:// URLs to download, or register as browser protocol handler
Drag & Drop	Drop .archive files onto the window to install
No Wine needed	Pure Python + Qt, runs natively on Linux

Installation

Prerequisites

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

# Ubuntu / Debian
sudo apt install python3-pyqt6

# Fedora
sudo dnf install python3-pyqt6

# Or via pip
pip install PyQt6

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 .archive files, OR
2. Drag & drop .archive 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 texture/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

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!)

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
4. Option B: Click 🔗 Register nxm:// Protocol Handler — then clicking "Download" on Nexus Mods will automatically send the mod to Neon Mod Manager

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's archive/pc/mod/ 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 to control this:

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

Enable/Disable

Instead of moving files in/out of a staging directory, mods are renamed:

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

The game ignores .disabled files completely.

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)
• Nexus Mods search (browse mods without leaving the app)
• Mod update detection (compare versions)
• REDmod script mod support (r6/tweaks)
• Auto-extract .7z / .zip downloads
• Mod categories and tags
• Dark/light theme switcher