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

```bash
# 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

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

### Run

```bash
# 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](https://www.nexusmods.com/users/myaccount?tab=api%20keys)
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`:
```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

- [x] ~~Archive file parsing (read internal file list for real conflict detection)~~ ✅ v0.2
- [x] ~~REDmod script mod support (r6/tweaks)~~ ✅ v0.2
- [x] ~~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