POI Collection Format

Version 1 · JSON Schema · NMS Galaxy Map

A POI collection is a JSON file listing points of interest (POIs) in the No Man's Sky universe: regions, star systems, space stations, planets and bases. It is how NMS Galaxy Map imports locations (Load/Save panel → Custom POI Collections), and it is meant as a simple, open way for players and tools to exchange interesting locations. Anyone may write or read this format. NMS Galaxy Map also writes it: a tag's Save & export saves the tagged locations as a collection (with $schema, the tag as title, its description and link, and each location's address, caption and link).

The key words MUST, SHOULD and MAY are used as in RFC 2119.

At a glance

{
  "title": "My Favorite Places",
  "description": "Paradise planets and community capitals I found worth a visit",
  "url": "https://example.com/my-nms-places",
  "points": [
    { "type": "region", "galaxy": 0, "region": "03556C4D", "caption": "Galactic Hub Project", "color": "#4EE44E" },
    { "type": "system", "galaxy": 0, "region": "F8FFEFFF", "system": "1E0", "caption": "Common galaxy hop system" },
    { "type": "planet", "galaxy": 0, "region": "D058AC1D", "system": "205", "planet": 2, "caption": "Lush paradise",
      "url": "https://example.com/my-nms-places#paradise" }
  ]
}

The file

Collection object

FieldTypeRequiredMeaning
pointsarrayyesThe points, see below. MAY be empty.
titlestringnoShort name of the collection, e.g. "NMS Communities". Shown when the file is listed or imported.
descriptionstringnoOne sentence about what is in the collection.
urlstringnoThe collection's web page (see Links).
$schemastringnoMAY be "https://gyrconos.github.io/NMSGalaxyMap/schema/poi-collection.schema.json", so editors can check the file.

Other top-level fields are allowed and ignored by readers that don't know them. Writers SHOULD NOT rely on them being kept.

Plain array

[
  { "type": "region", "galaxy": 0, "region": "00000000", "caption": "Galaxy Center" }
]

This is the same as a collection object with only points.

Points

Each point is a JSON object. It names one place, from a region down to a base.

FieldTypeRequiredMeaning
typestringyesWhat the point is: "region", "system", "station", "planet" or "base".
galaxyintegeryesGalaxy index 0–255. Euclid is 0, Hilbert Dimension 1, Calypso 2, … (the in-game galaxy number minus 1).
regionstringyesRegion address: 8 hex digits YYZZZXXX, see Addresses.
systemstringfor system, station, planet, baseStar system index within the region: hex, up to 3 digits (SSS).
planetinteger or stringfor planet, basePlanet index 0–15 (the P digit of a portal code). A string MUST be its decimal form, e.g. "2".
namestringfor baseThe place's name, replacing the procedurally generated one. For a base it identifies the base on its planet.
captionstringnoA label for the marker, e.g. why the place is interesting. Shown on the map and in the location list.
colorinteger or stringnoMarker color: an integer 0–16777215 (0xRRGGBB), or a hex string "#RRGGBB" or "RRGGBB".
urlstringnoA web page about the place (see Links).

Hex digits are case-insensitive; writers SHOULD use uppercase and SHOULD write system with 3 digits ("015", not "15"). Readers SHOULD treat different spellings of the same address as the same place (NMS Galaxy Map converts them to uppercase and pads system to 3 digits).

Types

typeFields needed beyond type, galaxy, regionWhat it is
region–A region (one voxel of the galaxy, up to several hundred systems).
systemsystemA star system.
stationsystemThe space station of a system.
planetsystem, planetA planet or moon.
basesystem, planet, nameA base, settlement or other named place on a planet. planet 0 is used for places not on a planet, e.g. freighters.

Readers SHOULD skip points of a type they don't know, so new types can be added later without breaking older readers. NMS Galaxy Map skips them, and skips points of a type that lack the fields it needs.

Additional fields

Points MAY have other fields (for example seed or ts in points exported from save files). Readers SHOULD keep fields they don't understand when they store a point and MAY ignore them. These names are reserved and MUST NOT be used for additional fields, because readers use them for their own data: systems, planets, station, bases, generatedName, generatedNameVersion, importIds, __proto__, constructor, prototype. Readers MUST NOT let a point's fields change anything but the entry for that point.

Several points for one place

A place can appear in several points, e.g. a region with a caption and, separately, a system in it. A point for a system, planet or base implies its region (and system, planet), so there is no need to list those separately. When two points name the same place and type, their fields are merged, the later point winning.

Addresses

The address fields come straight from the game's portal glyph code, 12 hex digits P SSS YY ZZZ XXX (each glyph is one hex digit, in the order the glyphs are shown in the game, 0–F):

DigitsField
Pplanet
SSSsystem
YYZZZXXXregion

So the portal code 2205D058AC1D is "planet": 2, "system": "205", "region": "D058AC1D".

XXX, YY and ZZZ are the region's position relative to the galaxy center as two's complement numbers: X and Z from −2048 to 2047 (12 bits), Y from −128 to 127 (8 bits, the height above the galactic plane). The galaxy center is region 00000000.

From galactic coordinates (as shown by a signal booster, XXXX:YYYY:ZZZZ:SSSS, hex):

X = (XXXX + 0x801) mod 0x1000
Y = (YYYY + 0x81)  mod 0x100
Z = (ZZZZ + 0x801) mod 0x1000
region = YY ZZZ XXX (Y as 2 digits, Z and X as 3 digits), system = SSSS (last 3 digits)

For example, 0C4C:0082:0D55:0122 is region 0355644D, system 122.

url, of the collection or of a point, links to a web page. Readers show it as a link, so it has to be safe. A link MUST:

NMS Galaxy Map leaves out links that break these rules, imports the rest of the file and tells the user what was left out.

Validation

A reader SHOULD reject a file that isn't JSON, has no points array, or has a point that isn't an object or has a type, galaxy, region, system, planet or color of the wrong form, and SHOULD say which point is wrong (by its index, starting at 0). The JSON Schema describes these rules; the reference implementation is parsePOICollection() in src/poifile.ts.

Examples

The collections served with NMS Galaxy Map are examples, for instance nms-communities.json.

A collection of bases and a station:

{
  "title": "Our Colony",
  "points": [
    { "type": "station", "galaxy": 1, "region": "0A1B2C3D", "system": "07F", "name": "Colony Trade Hub" },
    { "type": "base", "galaxy": 1, "region": "0A1B2C3D", "system": "07F", "planet": 1, "name": "Main Farm", "color": 65280 },
    { "type": "base", "galaxy": 1, "region": "0A1B2C3D", "system": "07F", "planet": "3", "name": "Gold Mine" }
  ]
}

Versions