arch_agent/neon-mod-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README for v0.2 — archive parsing, script mods, auto-extract

Browse Source
This commit is contained in:
arch_agent
2026-07-13 13:11:30 +02:00
parent 0e33ca5ec1
commit bfcab791c9
1 changed files with 92 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+91 -22
View File
@@ -9,39 +9,72 @@ Because existing mod managers (Mod Organizer 2 / Fluorine) have problems on Linu
- **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.
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 `.archive` files directly to mod directory |
| **Conflict Detection** | Scans for duplicate file patterns across enabled mods |
| **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, or register as browser protocol handler |
| **Drag & Drop** | Drop `.archive` files onto the window to install |
| **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
sudo pacman -S python-pyqt6 p7zip unrar
# Ubuntu / Debian
sudo apt install python3-pyqt6
sudo apt install python3-pyqt6 p7zip unrar
# Fedora
sudo dnf install python3-pyqt6
sudo dnf install python3-pyqt6 p7zip unrar
# Or via pip
# 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
@@ -63,16 +96,16 @@ python3 mod_manager.py
### 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)
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 texture/file = last one wins)
- 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
- Right-click a mod → **Move Up/Down** to reorder manually
### Enabling / Disabling
@@ -80,6 +113,19 @@ python3 mod_manager.py
- **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
@@ -91,21 +137,24 @@ python3 mod_manager.py
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
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's `archive/pc/mod/` directory. This avoids:
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 to control this:
Cyberpunk 2077 loads `.archive` files in alphabetical order. Neon Mod Manager uses numeric prefixes:
```
000_MyBodyMod.archive → loads first
010_MyTextureMod.archive → loads second
@@ -114,12 +163,30 @@ Cyberpunk 2077 loads `.archive` files in alphabetical order. Neon Mod Manager us
### Enable/Disable
Instead of moving files in/out of a staging directory, mods are renamed:
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`:
@@ -141,10 +208,12 @@ MIT — do whatever you want.
## Roadmap
- [ ] Archive file parsing (read internal file list for real conflict detection)
- [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)
- [ ] REDmod script mod support (r6/tweaks)
- [ ] Auto-extract `.7z` / `.zip` downloads
- [ ] Mod categories and tags
- [ ] Dark/light theme switcher
- [ ] Backup/restore vanilla files
- [ ] Mod dependency checker