Skip to content
BranchesTags

Repository files navigation

🚀 NMS Copilot

License

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.

Two ways to use it:

Interface What it does
CLI (nms) One-shot commands for quick lookups and scripted pipelines
REPL (nms-copilot) Interactive session with persistent state, built-in MCP server for AI co-exploration

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. The built-in MCP server shares the same live model, so your AI copilot knows where you are right now.

Use --headless to run just the MCP server without the REPL (e.g., for Claude Desktop integration).

Features

  • Native save file parsing -- reads save.hg directly (LZ4 block decompression + JSON key deobfuscation), no export step needed
  • Planet search -- find planets by biome, distance, discoverer, infested status, or any combination
  • Route planning -- nearest-neighbor and 2-opt TSP solvers with warp-range hop constraints
  • Portal glyph converter -- fully multidirectional: hex, emoji, coordinates, signal booster, galactic address
  • Interactive galaxy map -- full-screen TUI with galaxy, region, and local zoom levels
  • Live file watching -- detects auto-saves while you play and updates the model in real time
  • rkyv cache -- zero-copy serialization for near-instant startup after the first load
  • Multi-save support -- switch between save slots (up to 15)
  • Export & import -- JSON/CSV export of filtered data; CSV import of community coordinates
  • MCP server -- stdio and HTTP transports for AI copilot integration (Claude Desktop, etc.)
  • Configurable color themes -- ANSI terminal themes via ~/.nms-copilot/config.toml
  • Shell completions -- bash, zsh, fish, powershell, elvish
  • Multi-galaxy routing -- per-galaxy spatial indexes across all 256 NMS galaxies

Portal Glyphs

NMS Copilot renders portal addresses as emoji throughout all interfaces:

Portal Glyphs

Index Name Hex Emoji Unicode
0 Sunset 0 🌅 U+1F305
1 Bird 1 🕊️ U+1F54A U+FE0F
2 Face 2 😑 U+1F611
3 Diplo 3 🦕 U+1F995
4 Eclipse 4 🌜 U+1F31C
5 Balloon 5 🎈 U+1F388
6 Boat 6 ⛵ U+26F5
7 Bug 7 🐜 U+1F41C
8 Dragonfly 8 🦋 U+1F98B
9 Galaxy 9 🌀 U+1F300
10 Voxel A 🕋 U+1F54B
11 Whale B 🐋 U+1F40B
12 Tent C ⛺ U+26FA
13 Rocket D 🚀 U+1F680
14 Tree E 🌳 U+1F333
15 Atlas F 🔺 U+1F53A

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

All commands below work with both the CLI (nms) and the REPL (nms-copilot), unless noted otherwise. The CLI accepts --save and --slot flags; the REPL uses its pre-loaded model.

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 --target "Base A" --target "Base B"    # explicit waypoints
nms route --round-trip                           # return to start

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 stats --discoveries               # discovery counts by type
nms saves                             # list all save slots

Coordinate Conversion

nms convert --glyphs 01717D8A4EA2                  # hex glyphs to all formats
nms convert --glyphs "🌅🕊️🐜🕊️🐜🌳🦋🕋🌜🔺🕋😑"  # emoji glyphs to all formats
nms convert --coords 0EA2:007D:08A4:0171           # signal booster format
nms convert --ga 0x40050003AB8C07                   # galactic address
nms convert --voxel 100,50,-200 --ssi 42           # voxel coordinates

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

Listing Data

Browse reference data and model collections:

nms list galaxies                      # all 256 galaxies
nms list galaxies --type Lush          # filter by galaxy type
nms list biomes                        # biome types and variants
nms list glyphs                        # portal glyph table
nms list terrain-types                 # terrain generation types
nms list bases                         # all player bases
nms list systems --limit 10            # first 10 discovered systems
nms list systems --all                 # all discovered systems

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

The REPL (nms-copilot) supports all the commands above plus session management and an interactive galaxy map:

nms-copilot

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

[Euclid │ 644 planets │ 293 systems] 🚀 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 │ 293 systems] 🚀 list bases --limit 5
  #  Base                    System            Planet          Biome
  1  Acadia National Park    Gugestor Colony   Metok-Kalpa     Lush
  2  Sealab 2038             Esurad            Sushimi         Lush
  ...

[Euclid │ 644 planets │ 293 systems] 🚀 map
  (opens full-screen interactive galaxy map with zoom levels)

REPL-only commands:

Command Description
set position <base> Set reference position for distance calculations
set biome <biome> Set default biome filter for find/route
set warp-range <ly> Set default warp range for route planning
reset [position|biome|warp-range|all] Reset session state
status Show current session state
map Interactive galaxy map (galaxy/region/local zoom)

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 + MCP server (the `nms-copilot` binary)

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

The REPL includes a built-in MCP server for AI co-exploration. It starts automatically on http://127.0.0.1:3000 and shares the same live model as the REPL.

For headless operation (e.g., Claude Desktop integration):

nms-copilot --headless                           # stdio transport
nms-copilot --headless --http 127.0.0.1:3000    # HTTP transport

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.

Installation

cargo install nms-copilot    # interactive REPL + MCP server
cargo install nms-cli        # one-shot CLI (the `nms` binary)

Or build from source:

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

Requirements

  • Rust 1.91+ (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

at your option.

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

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages