🚀 NMS Copilot

A real-time galactic copilot for No Man's Sky, built in Rust.

Search planets by biome. Plan warp routes through the stars. Convert portal glyphs with emoji. Watch your save file live as you play — and let an AI explore the galaxy with you.

[Euclid │ 644 planets │ 293 systems] 🚀 find --biome Lush --nearest 5

  #  Planet            Biome   System             Distance   Portal Glyphs
  1  Metok-Kalpa       Lush    Gugestor Colony       0 ly    🌅🕊️🐜🕊️🐜🌳🦋🕋🌜🔺🕋😑
  2  Sushimi           Lush    Esurad               18K ly   🌅🕊️🐜🦕🌜🎈⛵🐜🦋🌀🕋🐋
  3  (unnamed)         Lush    Ogsjov XV            42K ly   🌅😑🐜🕊️🐜🌳🌜🕋🌅🔺🕋🦕
  4  (unnamed)         Lush    Rastarc-Zukk         67K ly   🌅🦕🐜🕊️🐜🌅🦋🕋🌜🔺🕋🐜
  5  Dipadri Grosso    Lush    Ipswic               91K ly   🌅🌜🐜🕊️🐜🌳🌜🕋🌅🌀🕋😑

What is this?

NMS Copilot reads your No Man's Sky save files — either the raw binary format (save.hg) directly or exported JSON — and builds a live, in-memory model of every system, planet, and base you've discovered. It's not a save editor. It's a queryable atlas of your personal galaxy.

Three ways to use it:

The copilot watches your save directory for changes. When you warp to a new system, scan a planet, or build a base, it detects the auto-save and updates the model automatically. If you're running the MCP server, your AI copilot knows where you are right now.

Portal Glyphs

NMS Copilot renders portal addresses as emoji throughout all interfaces:

Portal Glyphs

Convert freely between formats:

# Emoji → coordinates
nms convert --glyphs "🌅🕊️🐜🕊️🐜🌳🦋🕋🌜🔺🕋😑"

# Hex glyphs → coordinates
nms convert --glyphs 01717D8A4EA2

# Signal booster → emoji glyphs
nms convert --coords 0EA2:007D:08A4:0171

# Galactic address → everything
nms convert --ga 0x40050003AB8C07

Commands

Search

Find planets matching any combination of criteria, sorted by distance:

nms find --biome Lush                          # all lush planets
nms find --biome Scorched --infested           # infested scorched only
nms find --biome Barren --within 100000        # within 100K ly
nms find --biome Lava --nearest 5              # 5 closest lava planets
nms find --biome Swamp --from "Sealab 2038"   # distance from a named base
nms find --named --discoverer oubiwann         # your named discoveries

Route Planning

Plan optimal routes through the galaxy with warp range constraints:

nms route --biome Scorched                       # visit all scorched, nearest-neighbor
nms route --biome Scorched --within 500000       # only within radius
nms route --biome Lush,Swamp --warp-range 2500   # S-class hyperdrive hops
nms route --biome Frozen --algo 2opt             # improved TSP
nms route --targets "Base A" "Base B" "Base C"   # explicit waypoints

Info & Details

nms info                            # save overview, player location, discovery counts
nms show system 369                 # system details + all planets
nms show base "Acadia National Park"  # base details with portal glyphs
nms stats --biomes                  # biome distribution table
nms saves                           # list all save slots

Export & Import

nms export --format json                          # export all planets as JSON
nms export --biome Lush --format csv              # export filtered planets as CSV
nms import community_data.csv --source "NMSCE"    # import community coordinates

Shell Completions

nms completions bash > ~/.bash_completion.d/nms   # bash completions
nms completions zsh > ~/.zfunc/_nms               # zsh completions
nms completions fish > ~/.config/fish/completions/nms.fish  # fish completions

Multi-Save Support

nms info --slot 3                   # use save slot 3 instead of most recent
nms find --slot 5 --biome Lush      # search slot 5's discoveries

Interactive REPL

nms-copilot

[Euclid │ 644 planets] 🚀 set position "Acadia National Park"
📍 Position set to Acadia National Park (Lush, Gugestor Colony)

[Euclid │ 644 planets] 🚀 find --biome Lava --nearest 3
  #  Planet       Biome  Distance   Portal Glyphs
  1  (unnamed)    Lava     127K ly  🌅🦕🌀🕊️🐜🌳🌜🕋🌅🌀🕋🦕
  2  (unnamed)    Lava     204K ly  🌅🌜🐜🕊️🐜🌳🦋🕋🌜🔺🕋😑
  3  (unnamed)    Lava     318K ly  🌅😑🐜🕊️🐜🌅🌜🕋🌅🔺🕋🐜

[Euclid │ 644 planets] 🚀 route --targets 1 2 3 --warp-range 2500
  Planning route from current position through 3 waypoints...
  Hop  System              Distance    Cumulative   Glyphs
   1   Ikusam-Rista          127K ly      127K ly   🌅🦕🌀🕊️🐜🌳🌜🕋🌅🌀🕋🦕
   2   Ovfast XI              77K ly      204K ly   🌅🌜🐜🕊️🐜🌳🦋🕋🌜🔺🕋😑
   3   Yatsinbur-Epp         114K ly      318K ly   🌅😑🐜🕊️🐜🌅🌜🕋🌅🔺🕋🐜
  Total: 318K ly, 3 hops (128 warp jumps at 2500 ly range)

Architecture

NMS Copilot is a Rust workspace of focused crates:

nms/
├─ nms-core       Types, enums, address math, glyph emoji
├─ nms-save       Raw binary save parser (LZ4 + XXTEA + key mapping)
├─ nms-compat     Format adapters (NomNom save format detection)
├─ nms-graph      petgraph spatial model, R-tree index, routing
├─ nms-query      Shared query engine (find, route, show, stats)
├─ nms-watch      File watcher, delta computation, live updates
├─ nms-cache      rkyv zero-copy serialization for fast startup
├─ nms-cli        clap one-shot CLI (the `nms` binary)
├─ nms-copilot    reedline interactive REPL (the `nms-copilot` binary)
└─ nms-mcp        MCP server for AI integration

The data flows in one direction:

save file → parser → galaxy model → query engine → CLI / REPL / MCP
                          ↑
               file watcher (live updates)

The galaxy model is the core: a petgraph of systems with an R-tree spatial index, incrementally updated as the game auto-saves. All three interfaces share the same query engine — no duplicated logic.

How Save Parsing Works

NMS saves are LZ4 block-compressed JSON (not a proprietary binary format). The pipeline:

1. Read sequential 16-byte block headers (magic 0xFEEDA1E5) + LZ4 payloads
2. Decompress and concatenate all blocks
3. Deobfuscate JSON keys using MBINCompiler's mapping.json
4. Deserialize into typed Rust structs via serde

No encryption on modern saves (format 2002+, post-Frontiers). The only crypto is XXTEA on the small metadata file (mf_save.hg), used for integrity verification.

MCP Server

Run alongside Claude or another AI assistant for real-time co-exploration:

nms-mcp                           # stdio transport (for Claude Desktop)
nms-mcp --http 127.0.0.1:3000    # HTTP transport (for remote clients)

The MCP server exposes all query capabilities as tools — your AI copilot can search planets, plan routes, convert coordinates, and track your position as you play.

Status

All 7 phases complete.

Installation

cargo install nms-copilot    # interactive REPL
cargo install nms-cli        # one-shot CLI (the `nms` binary)
cargo install nms-mcp        # MCP server for AI integration

Or build from source:

git clone https://github.com/oxur/nms-copilot
cd nms-copilot
make build

Requirements

• Rust 1.85+ (2024 edition)
• No Man's Sky save files (Steam, GOG, or Mac)
• A terminal with emoji support (most modern terminals)

Acknowledgements

NMS Copilot builds on a decade of community reverse engineering. Special thanks to:

• libNOM.io / NomNom by zencq — the most complete save format implementation
• MBINCompiler by monkeyman192 — game data decompilation and key mapping
• Chase-san — the cleanest minimal save decoder
• MetaIdea/nms-savetool — definitive format 2001 encryption documentation
• NMSCD — community developer tools and coordinate converters
• The NMS Modding Discord community — collective format knowledge
• Hello Games — for building a universe worth exploring 🌌

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

"The universe is a pretty big place. It's good to have a copilot." 🚀🦀