arch_agent
96f24a8b25
Features: - Enable/disable mods (.archive <-> .archive.disabled) - Load order via filename prefixes (000_, 010_, 020_) - Conflict detection - Profile save/load - Nexus Mods nxm:// protocol handler - PyQt6 GUI, Wayland compatible - No REDmod, no FUSE, no Wine prefix
150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
# 🎮 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```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 `.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](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
|
||
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`:
|
||
```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 |