POI Collection Format
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
- The file MUST be JSON (RFC 8259) encoded as UTF-8. The extension SHOULD be
.json. - The top level is either a collection object (recommended) or a plain array of points.
Collection object
| Field | Type | Required | Meaning |
|---|---|---|---|
points | array | yes | The points, see below. MAY be empty. |
title | string | no | Short name of the collection, e.g. "NMS Communities". Shown when the file is listed or imported. |
description | string | no | One sentence about what is in the collection. |
url | string | no | The collection's web page (see Links). |
$schema | string | no | MAY 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
type | string | yes | What the point is: "region", "system", "station", "planet" or "base". |
galaxy | integer | yes | Galaxy index 0–255. Euclid is 0, Hilbert Dimension 1, Calypso 2, … (the in-game galaxy number minus 1). |
region | string | yes | Region address: 8 hex digits YYZZZXXX, see Addresses. |
system | string | for system, station, planet, base | Star system index within the region: hex, up to 3 digits (SSS). |
planet | integer or string | for planet, base | Planet index 0–15 (the P digit of a portal code). A string MUST be its decimal form, e.g. "2". |
name | string | for base | The place's name, replacing the procedurally generated one. For a base it identifies the base on its planet. |
caption | string | no | A label for the marker, e.g. why the place is interesting. Shown on the map and in the location list. |
color | integer or string | no | Marker color: an integer 0–16777215 (0xRRGGBB), or a hex string "#RRGGBB" or "RRGGBB". |
url | string | no | A 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
type | Fields needed beyond type, galaxy, region | What it is |
|---|---|---|
region | – | A region (one voxel of the galaxy, up to several hundred systems). |
system | system | A star system. |
station | system | The space station of a system. |
planet | system, planet | A planet or moon. |
base | system, planet, name | A 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):
| Digits | Field |
|---|---|
P | planet |
SSS | system |
YYZZZXXX | region |
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.
Links
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:
- be an absolute
http://orhttps://URL to a named host (no IP address, no single-word host likelocalhost), - have no user name or password,
- be at most 2048 characters,
- not contain whitespace, control characters, quotes,
<,>,`,\,{,},|or^(percent-encode them).
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
- 1 (2026-11): first documented version. It describes what NMS Galaxy Map has read since its first POI files. Later versions will only add optional fields and types, so a version 1 file stays valid.