User Manual

User Manual

The complete reference in one page. Each section links to its dedicated wiki page for more detail — this page is for when you want everything without clicking around.

Contents

1. Status and scope
2. Getting started
3. Game detection and modes
4. Installing mods
5. Managing installed mods
6. Backups and recovery
7. Profiles
8. The AI assistant
9. The SP→FiveM converter
10. FiveM server tools
11. Safety model
12. Data locations

---

Status and scope

gtavmm-core (the engine) and gtavmm-cli are functional and tested against real mod files. gtavmm-app (the Tauri + React desktop app) is under active development: it has a working navigation shell with English/Traditional Chinese support, and a handful of pages wired to real commands (Legacy SP mod listing, FiveM server load ordering, the SP→FiveM converter). The install wizard, profile switching UI, and most workspace pages aren't ported yet. Use the CLI for anything the app doesn't cover yet.

Covers: Legacy and Enhanced single-player mods, LSPDFR, and FiveM (client asset mods and server resource ordering). Does not cover: downloading mods for you (manual-link-only, by design), editing .rar/.oiv archive internals, or mixed-mode/obfuscated .dll translation (a spike found a viable approach for plain managed .dll string translation, but it isn't wired into the CLI/app yet).

Getting started

gtavmm detect-game            # find your Legacy/Enhanced install
gtavmm check-components       # confirm ScriptHookV/SHVDN/OpenIV/OpenRPF are present
gtavmm inspect path/to/mod    # preview, no files written
gtavmm install path/to/mod    # install for real

Full walkthrough: Getting Started.

Game detection and modes

Detection order: Windows Registry → Steam → Epic → Rockstar launcher (Windows); Proton compatdata scan (Linux). Override anytime with --game-path.

--mode picks which directory conventions apply to install/inspect, independent of the detected edition:

• sp (default) — plain SP mods (ScriptHookV/SHVDN/Menyoo/OpenIV conventions)
• lspdfr — RAGE Plugin Hook conventions (Plugins\)
• fivem-client — FiveM client assets; requires --game-path explicitly, no auto-detection

Details: Game Setup and Launch.

Installing mods

Supported: plain folders, .asi, .dll (routed by --mode), Menyoo .xml, .zip, .7z. Refused outright: .rar (no pure-Rust decoder), .oiv (redirects you to OpenIV — every real sample seen modifies RPF internals). Anything else is reported as unrecognized, never silently skipped.

gtavmm inspect path/to/mod          # read-only preview
gtavmm scan path/to/mod             # OS-native antivirus check
gtavmm install path/to/mod          # install
gtavmm --mode lspdfr install path   # LSPDFR conventions

Details: Installing Mods.

Managing installed mods

gtavmm list-mods
gtavmm search <keyword>             # local keyword match, not natural-language search
gtavmm enable <id>
gtavmm disable <id>
gtavmm uninstall <id>
gtavmm reinstall <id> <source_path> <version>
gtavmm history
gtavmm export output.xlsx

Known limitation: the database doesn't yet tag which mode/edition a mod belongs to, so list-mods always shows everything installed, not filtered by mode.

Details: Managing Installed Mods.

Backups and recovery

Automatic per-mod backups on install; uninstalled mods go to a recycle bin (with expiry) rather than being deleted outright; manual whole-folder full backups for bigger changes.

gtavmm recycle-bin list
gtavmm recycle-bin restore <id>
gtavmm full-backup create
gtavmm full-backup list
gtavmm full-backup restore <path>

Details: Backup and Restore.

Profiles

Named, opt-in sets of mods that should be active together.

gtavmm profile create <name>
gtavmm profile add-mod <profile_id> <mod_id>
gtavmm profile switch <id>
gtavmm profile export <id> <output.json>
gtavmm profile import <path.json>

Export/import shares names only, never mod files — this project never auto-downloads mods.

Details: Advanced Tools § Profiles.

The AI assistant

Off by default. Choose Ollama (local, nothing leaves your machine) or your own cloud API key (stored in your OS credential manager).

gtavmm ai enable ollama --model llama3.1
gtavmm ai diagnose --file crash.log        # read-only advice
gtavmm ai list-known-fixes
gtavmm ai plan-known-fix <rule_id>          # preview
gtavmm ai apply-known-fix <rule_id> --yes   # execute
gtavmm ai set-auto-approve disable_mod enable_mod   # the only whitelistable kinds
gtavmm translate-config mod.ini zh-TW       # config-file translation drafts

Every action expands to a Plan you see before it runs. .NET DLL embedded-string translation was investigated (2026-08-29 spike, viable but involved binary patching) but isn't wired into the CLI/app yet.

Details: Advanced Tools § AI Assistant.

The SP→FiveM converter

Converts an SP add-on vehicle pack's dlc.rpf directly into a FiveM resource — no manual OpenIV/CodeWalker extraction needed. Vehicle/add-on packs only; script mod conversion isn't built.

gtavmm convert-vehicle path/to/dlc.rpf path/to/output-folder

Verified against 4 real mods including a 390MB tuning pack with nested localization archives and a non-ASCII source path. Details: SP to FiveM Converter.

FiveM server tools

gtavmm fivem-resource-order path/to/resources
gtavmm fivem-apply-load-order path/to/resources path/to/server.cfg

Computes load order from each resource's fxmanifest.lua dependencies (topological sort) — writes a clearly-marked, idempotent block into server.cfg, leaving everything else untouched.

Details: Advanced Tools § FiveM resource load order.

Safety model

• Protected files: any .exe, plus named launcher/anti-cheat files — never overridable.
• Conflict tiers: protected hit (fatal) → self-update (flagged, one-click continue) → foreign conflict (requires explicit override).
• Malware scanning: shells out to Windows Defender/clamscan, no bundled engine; Defender results are deliberately conservative (Clean/Unavailable only) after real testing showed its exit codes are ambiguous.
• No auto-downloads: manual-link-only sourcing, always.

Details: Safety Model.

Data locations

SQLite database + OS credential store for secrets, no plaintext config, versioned schema that migrates automatically. Details: Data Locations and Logs.