initial commit

README.md

@@ -0,0 +1,142 @@
+# SymlinkModels
+
+Replace unwanted Sven Co-op player models with a neutral placeholder by symlinking them to `helmet.mdl`. This keeps your client from rendering anime, NSFW, or other models you don't want to see, while still letting you connect to any server that uses them.
+
+## How it works
+
+For each model ID, the scripts create a relative symlink:
+
+```
+svencoop_addon/models/player/<id>/<id>.mdl
+    -> ../../../../svencoop/models/player/helmet/helmet.mdl
+```
+
+Every suppressed model renders as the default helmet instead.
+
+## Prerequisites
+
+- Sven Co-op installed (scripts must run from the game's root folder, alongside `tags.json`)
+- Python 3.8+ **or** PowerShell 5.1+
+- **Windows only:** Developer Mode enabled *(Settings → For developers)* **or** run as Administrator — both Windows symlink scripts check for this and warn if neither condition is met
+
+## Files
+
+| File | Description |
+|---|---|
+| `tags.json` | Model ID lists grouped by category (`anime`, `nsfw`, `vehicle`) |
+| `symlink_models.py` | Python — symlink models from `tags.json`, a server path, or a text file |
+| `symlink_models.ps1` | PowerShell equivalent of `symlink_models.py` |
+| `symlink_downloads.py` | Python — symlink downloaded models that match `tags.json`, then optionally clean up `svencoop_downloads` |
+| `symlink_downloads.ps1` | PowerShell equivalent of `symlink_downloads.py` |
+| `server_models.txt` | Example model ID dump from a server, usable with `--from-file` |
+
+## Usage
+
+Place the scripts and `tags.json` in your **Sven Co-op root folder** (the directory that contains `svencoop/` and `svencoop_addon/`).
+
+### symlink_models — bulk symlink by source
+
+Symlinks every model ID from the selected source.
+
+**Python:**
+```bash
+# Default: all IDs in tags.json
+python symlink_models.py
+
+# Scan a server's player/ directory
+python symlink_models.py --server /path/to/svencoop_addon/models/player
+
+# Read IDs from a text file (one ID per line)
+python symlink_models.py --from-file server_models.txt
+
+# Preview changes without writing anything
+python symlink_models.py --dry-run
+```
+
+**PowerShell:**
+```powershell
+# Default: all IDs in tags.json
+.\symlink_models.ps1
+
+# Scan a server's player/ directory
+.\symlink_models.ps1 -Server "C:\path\to\svencoop_addon\models\player"
+
+# Read IDs from a text file
+.\symlink_models.ps1 -FromFile server_models.txt
+
+# Preview changes without writing anything
+.\symlink_models.ps1 -DryRun
+```
+
+### symlink_downloads — process already-downloaded models
+
+Scans `svencoop_downloads/models/player/` for `.mdl` files whose names match IDs in `tags.json`. For each match it creates the symlink in `svencoop_addon`, then lists the source folders and prompts whether to delete them.
+
+**Python:**
+```bash
+python symlink_downloads.py
+
+# Preview without writing or deleting
+python symlink_downloads.py --dry-run
+```
+
+**PowerShell:**
+```powershell
+.\symlink_downloads.py
+
+# Preview without writing or deleting
+.\symlink_downloads.ps1 -DryRun
+```
+
+The `svencoop_downloads/models/player/` root itself is never deleted — only matched sub-folders.
+
+### Dumping model IDs from a server
+
+If you have access to a server's files (directly or via a network mount), you can dump its player model IDs to a text file and feed it to `symlink_models`:
+
+**Linux/macOS:**
+```bash
+find /path/to/svencoop_addon/models/player \
+     -mindepth 2 -maxdepth 2 -name "*.mdl" -printf "%f\n" \
+     | sed 's/\.mdl$//' > server_models.txt
+```
+
+**PowerShell:**
+```powershell
+Get-ChildItem -Path "C:\path\to\svencoop_addon\models\player" -Recurse -Filter "*.mdl" |
+    Where-Object { $_.DirectoryName -ne "...\player" } |
+    ForEach-Object { $_.BaseName } | Sort-Object -Unique | Set-Content server_models.txt
+```
+
+## tags.json
+
+The tag file is a flat JSON object with three category arrays:
+
+```json
+{
+  "anime":   ["2d_ab_kanna_coco", "sagas_trunks_ssj", ...],
+  "nsfw":    [...],
+  "vehicle": [...]
+}
+```
+
+- **anime** (~2,129 entries) — anime character models
+- **nsfw** (~579 entries) — adult content models
+- **vehicle** (~73 entries) — vehicle models
+
+Model IDs are lowercase with underscores or hyphens. Version suffixes like `_v2` and `_hd` are treated as separate entries. To add or remove a model, edit the relevant array directly. Existing entries are not fully sorted, but try to insert near alphabetical neighbours.
+
+## Output
+
+Each script prints one line per model processed and a summary on exit:
+
+```
+[anime] — 2129 models
+  create  : 2d_ab_kanna_coco
+  skipped : 2d_ab_kratos
+  replace : sagas_trunks_ssj
+
+147 symlinks written (147 new, 0 replaced), 1982 already correct
+```
+
+Exit codes are 0 on success, non-zero on a fatal error (missing `helmet.mdl`, bad path, etc.).