{"id":50400471,"url":"https://github.com/enki013/nms-mod-installer-macos","last_synced_at":"2026-05-30T23:03:27.257Z","repository":{"id":349581170,"uuid":"1202928284","full_name":"Enki013/nms-mod-installer-macos","owner":"Enki013","description":"CLI mod installer for No Man’s Sky on macOS: safe HGPAK patching, automatic backups, indexed uninstall, and EXML/MBIN support.","archived":false,"fork":false,"pushed_at":"2026-04-15T21:29:18.000Z","size":8675,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T23:26:07.152Z","etag":null,"topics":["cli","game-modding","hgpak","macos","modding","no-mans-sky","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Enki013.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T14:46:23.000Z","updated_at":"2026-04-15T21:29:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Enki013/nms-mod-installer-macos","commit_stats":null,"previous_names":["enki013/nms-mod-installer-macos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Enki013/nms-mod-installer-macos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enki013%2Fnms-mod-installer-macos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enki013%2Fnms-mod-installer-macos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enki013%2Fnms-mod-installer-macos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enki013%2Fnms-mod-installer-macos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Enki013","download_url":"https://codeload.github.com/Enki013/nms-mod-installer-macos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enki013%2Fnms-mod-installer-macos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33712582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","game-modding","hgpak","macos","modding","no-mans-sky","python"],"created_at":"2026-05-30T23:03:18.781Z","updated_at":"2026-05-30T23:03:27.244Z","avatar_url":"https://github.com/Enki013.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NMS Mod Installer for macOS\n\nA command-line tool for installing mods into **No Man's Sky** on macOS by patching HGPAK `.pak` archives.\n\nOn macOS, the game's built-in `MODS` folder does not work. This tool bridges that gap by extracting `.pak` archives, replacing files with mod contents, and repacking them with LZ4 compression — all automatically.\n\n## How It Works\n\n```\n┌──────────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐\n│  Mod Folder  │────\u003e│  Scan \u0026  │────\u003e│  Extract  │────\u003e│ Replace  │────\u003e│  Repack  │\n│              │     │  Match   │     │   .pak    │     │  Files   │     │  \u0026 Install│\n└──────────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘\n                          │                                                   │\n                     Maps mod files                                    LZ4 compressed\n                     to game .paks                                     HGPAK v2 format\n                                                                            │\n                                                                            ▼\n                                                                    ┌──────────────┐\n                                                                    │  MACOSBANKS/ │\n                                                                    │  (game dir)  │\n                                                                    └──────────────┘\n```\n\n1. **Scan** — Indexes all `.pak` archives in the game and maps each mod file to its target `.pak`\n2. **Backup** — Copies original `.pak` files to `_MOD_BACKUPS/` before any changes\n3. **Extract** — Unpacks affected `.pak` archives using `hgpaktool -U -M`\n4. **Replace** — Overwrites extracted files with mod versions (case-insensitive matching)\n5. **Repack** — Rebuilds `.pak` archives with LZ4 compression using `hgpaktool -R -Z`\n6. **Register** — Records installed mod metadata for clean uninstall later\n\n## Requirements\n\n- **macOS** (tested on macOS 15+)\n- **Python 3.9+** (pre-installed on macOS)\n- **[hgpaktool](https://github.com/monkeyman192/HGPAKtool)** — HGPAK archive tool by monkeyman192\n- **.NET 8 Runtime** (`Microsoft.NETCore.App 8.x`) — required for EXML-based mods (MBINCompiler)\n\n## Installation\n\n```bash\n# 1. Install hgpaktool\npip3 install --user hgpaktool\n\n# 2. Clone this repo\ngit clone https://github.com/Enki013/nms-mod-installer-macos.git\ncd nms-mod-installer-macos\n\n# 3. Make executable (required for ./ shortcuts below)\nchmod +x nms_mod_installer.py\n```\n\nCommands below assume your shell’s current directory is the repo folder (`nms-mod-installer-macos` or wherever you cloned it). From anywhere else you can still run `python3 /path/to/nms_mod_installer.py …`.\n\n## Usage\n\n### Set game path (first time only)\n\nThe tool auto-detects the game in common locations (`/Applications`, `~/Applications`, Steam library). If auto-detection fails, set it manually:\n\n```bash\n./nms_mod_installer.py set-game \"/Applications/No Man's Sky.app\"\n```\n\nThe path is saved and remembered for future runs. You can also use `--game \u003cpath\u003e` with any command to override.\n\n### Scan a mod (preview, no changes)\n\n```bash\n./nms_mod_installer.py scan ~/Downloads/MyMod\n```\n\nShows which `.pak` files the mod will affect without modifying anything.\n\n### Interactive wizard (beginner mode)\n\n```bash\n./nms_mod_installer.py wizard\n```\n\nStep-by-step guided CLI flow for scan/install/list/uninstall without remembering commands.\n\n### Install a mod\n\n```bash\n./nms_mod_installer.py install ~/Downloads/MyMod\n```\n\nFull pipeline: scan, backup originals, extract, replace, repack, install.\n\n\u003cimg src=\"docs/images/install.gif\" alt=\"Install command in terminal\"\u003e\n\nTo preview which paks a mod touches without installing, use `scan` (see above).\n\n### List installed mods\n\n```bash\n./nms_mod_installer.py list\n```\n\n\u003cimg src=\"docs/images/list.png\" alt=\"Installed mods list with index numbers\" width=\"900\"\u003e\n\n### Uninstall a mod\n\n```bash\n./nms_mod_installer.py uninstall 2\n# or by name:\n./nms_mod_installer.py uninstall \"MyMod\"\n```\n\nRestores original `.pak` files from backup.\n\n\u003cimg src=\"docs/images/uninstall.png\" alt=\"Uninstalling a mod by index\" width=\"900\"\u003e\n\n### Options\n\n| Flag | Description |\n|---|---|\n| `--game \u003cpath\u003e` | Path to `No Man's Sky.app` (auto-detected or saved via `set-game`) |\n| `--force-reindex` | Rebuild the pak index cache (use after game updates) |\n\n## Mod Folder Structure\n\nMods must mirror the game's internal directory structure. File and folder names are **case-insensitive**.\n\n```\nMyMod/\n├── LANGUAGE/\n│   └── NMS_LOC1_ENGLISH.MBIN\n├── FONTS/\n│   └── GAME/\n│       └── CONSOLEFONT2.TTF\n├── TEXTURES/\n│   └── PLANETS/\n│       └── ...\n└── METADATA/\n    └── REALITY/\n        └── TABLES/\n            └── SOME_TABLE.MBIN\n```\n\nThe tool automatically determines which `.pak` archive each file belongs to.\n\n## Example: Turkish Language Patch\n\n```bash\n# Preview\n./nms_mod_installer.py scan ~/Downloads/Turkish\\ Localisation\n\n# Output:\n# Mod would affect 3 pak(s):\n#   NMSARC.Language.pak    (8 files)\n#   NMSARC.Precache.pak    (1 file)\n#   NMSARC.fonts.pak       (1 file)\n\n# Install\n./nms_mod_installer.py install ~/Downloads/Turkish\\ Localisation\n\n# Verify\n./nms_mod_installer.py list\n\n# Uninstall if needed\n./nms_mod_installer.py uninstall 1\n```\n\n## Game File Structure (macOS)\n\nOn macOS, No Man's Sky stores assets differently from Windows:\n\n| | Windows | macOS |\n|---|---|---|\n| Archive directory | `GAMEDATA/PCBANKS/` | `GAMEDATA/MACOSBANKS/` |\n| MODS folder | Supported | **Not supported** |\n| Compression | ZSTD | LZ4 |\n| Archive format | HGPAK v2 | HGPAK v2 |\n\n```\nNo Man's Sky.app/\n└── Contents/Resources/GAMEDATA/MACOSBANKS/\n    ├── NMSARC.Language.pak      # Localization strings\n    ├── NMSARC.fonts.pak         # Game fonts\n    ├── NMSARC.Precache.pak      # Metadata, dialog tables, UI\n    ├── NMSARC.globals.pak       # Global game settings\n    ├── NMSARC.Materials.pak     # Material definitions\n    ├── NMSARC.UI.pak            # UI definitions\n    ├── NMSARC.TexPlanet*.pak    # Planet textures (per-biome)\n    ├── NMSARC.MeshPlanet*.pak   # 3D models\n    └── ...\n```\n\n## Technical Details\n\n### HGPAK Format\n\n- **Magic:** `HGPAK\\x00\\x00\\x00` (8 bytes)\n- **Version:** 2 (uint64 LE)\n- **Compression:** LZ4 (macOS), ZSTD (Windows/Linux), Oodle (Switch)\n- Introduced in NMS 5.50 (Worlds Part II), replacing the older PSARC format\n\n### Tool Chain\n\n```bash\nhgpaktool -L \u003cpak\u003e                          # List contents (outputs filenames.json)\nhgpaktool -U -M \u003cpak\u003e -O \u003cdir\u003e             # Extract + generate manifest\nhgpaktool -R -Z \u003cmanifest\u003e -O \u003coutput.pak\u003e  # Repack with compression\n```\n\n### Caching\n\nOn first run, the tool scans all `.pak` files and builds an index cache (`_pak_index_cache.json`). This cache is valid for 24 hours. After a game update, use `--force-reindex` to rebuild it.\n\n## Troubleshooting\n\n### Permission denied (do not use `sudo python3`)\n\nThe installer must write inside `No Man's Sky.app/.../MACOSBANKS/`. If you see **Permission denied**, do **not** run it as `sudo python3 …` (that runs the script as root and can confuse file ownership).\n\n**Preferred:** install or copy the game under your user, e.g. `~/Applications/No Man's Sky.app`, so you already own the files.\n\n**If the game is in `/Applications` and owned by root**, fix ownership once, then use `./nms_mod_installer.py` as your normal user:\n\n```bash\nsudo chown -R \"$(whoami)\" \"/Applications/No Man's Sky.app\"\n```\n\n### hgpaktool not found\n\n```bash\npip3 install --user hgpaktool\n\n# If not on PATH:\nexport PATH=\"$PATH:$HOME/Library/Python/3.9/bin\"\n```\n\n### .NET runtime mismatch (EXML mods)\n\nIf you see an error like:\n- `You must install or update .NET to run this application`\n- `Framework: 'Microsoft.NETCore.App', version '8.0.xx'`\n\nInstall **.NET 8 Runtime** (arm64 on Apple Silicon), then verify:\n\n[Download .NET 8](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)\n\n```bash\ndotnet --list-runtimes\n```\n\nYou should see `Microsoft.NETCore.App 8.0.x`.\n\n### Mod stopped working after game update\n\nGame updates overwrite `.pak` files. Reinstall the mod:\n\n```bash\n./nms_mod_installer.py install ~/Downloads/MyMod --force-reindex\n```\n\n### Game won't launch / crashes\n\nRemove mods and restore originals:\n\n```bash\n./nms_mod_installer.py uninstall \"MyMod\"\n```\n\nOr manually:\n\n```bash\ncd \"No Man's Sky.app/Contents/Resources/GAMEDATA/MACOSBANKS\"\ncp _MOD_BACKUPS/MyMod/*.pak ./\n```\n\n### macOS \"damaged app\" warning\n\nModifying `.pak` files may break the app's code signature:\n\n```bash\nxattr -cr ~/Applications/No\\ Man\\'s\\ Sky.app\ncodesign --force --deep --sign - ~/Applications/No\\ Man\\'s\\ Sky.app\n```\n\n## License\n\n[MIT](LICENSE)\n\n## Credits\n\n- **[hgpaktool](https://github.com/monkeyman192/HGPAKtool)** by monkeyman192 — HGPAK extraction and repacking\n- **[Hello Games](https://hellogames.org/)** — No Man's Sky\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenki013%2Fnms-mod-installer-macos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenki013%2Fnms-mod-installer-macos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenki013%2Fnms-mod-installer-macos/lists"}