astro.Class.ProceduralSystem

@elite-dangerous-almanac/core / astro / ProceduralSystem

Class: ProceduralSystem

Defined in: src/astro/procedural-system.ts:144

An Elite Dangerous star system, identified by its procedural name and/or system address. Hand-named systems such as Sol are deliberately outside this type.

Instances are immutable. The normal system address is validated and computed by the factory, so reading a successfully constructed system never throws; the modulated form is null when its narrower sequence field cannot represent the system.

Remarks

Failure model — factory failures are deliberately split by cause:

• ProceduralSystem.fromName returns null for a string that is not a well-formed system name (a parsing outcome, not an error).
• ProceduralSystem.fromSystemAddress / ProceduralSystem.fromModSystemAddress throw RangeError for an id64 outside the unsigned 64-bit range or one whose sector-grid slot has no assigned procedural name.
• ProceduralSystem.fromModSystemAddress also throws RangeError when the modulated layout's sequence cannot fit the normal layout. Every constructed instance guarantees a normal ProceduralSystem.systemAddress.
• ProceduralSystem.fromName throws RangeError immediately when a syntactically valid name cannot be encoded (unknown naming region, or an address field out of range).
• ProceduralSystem.fromName throws TypeError when name is not a string at all, a missing one included — that is a caller bug, not a name the scheme does not cover, so it is not reported as null.

For the galactic codex region of a system, pass its address to the standalone findCodexRegionForBoxel (from ./codex-region-lookup) — kept off this facade so ProceduralSystem does not bundle the region grid.

Example

import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';

declare const id64: bigint;
declare const x: number;
declare const y: number;
declare const z: number;

// Name -> id64
const sys = ProceduralSystem.fromName('Synuefe EN-H d11-96');
if (sys) sys.systemAddress; // bigint

// id64 -> name (pass coords so hand-authored regions render correctly)
ProceduralSystem.fromSystemAddress(id64, { x, y, z }).name;

Properties

requiresRegionPermit

readonly requiresRegionPermit: boolean

Defined in: src/astro/procedural-system.ts:163

Whether the system's region sits behind a permit lock (Col 70, Bleia, the Cone Sector, …).

Remarks

This is a region-level flag only. Individually permit-locked systems — Sol, Shinrarta Dezhra, Achenar and 51 others — are not procedurally named, so they never reach a ProceduralSystem; check those with permitLockForSystemName from ./permit-locks, which covers both kinds of lock from a name alone.

---

usesHandAuthoredRegion

readonly usesHandAuthoredRegion: boolean

Defined in: src/astro/procedural-system.ts:151

Whether the name uses a hand-authored region instead of a procedural sector.

Accessors

massCode

Get Signature

get massCode(): string

Defined in: src/astro/procedural-system.ts:358

The mass-code letter a–h.

Returns

string

---

modSystemAddress

Get Signature

get modSystemAddress(): bigint | null

Defined in: src/astro/procedural-system.ts:421

The 64-bit modulated system address, computed from the region origin, or null when the system sequence cannot fit the modulated layout.

A null result is explicit and has no deferred failure mode.

Returns

bigint | null

---

name

Get Signature

get name(): string

Defined in: src/astro/procedural-system.ts:344

The canonical system name, e.g. Synuefe EN-H d11-96.

Returns

string

---

namingRegionName

Get Signature

get namingRegionName(): string

Defined in: src/astro/procedural-system.ts:353

The region (sector) name — a procedural sector (Synuefe) or, when the system is inside a hand-authored region, that region's name (Pleiades Sector). See ProceduralSystem.usesHandAuthoredRegion to tell which.

Returns

string

---

parts

Get Signature

get parts(): SystemNameParts

Defined in: src/astro/procedural-system.ts:400

A shallow copy of the parsed name parts.

Remarks

Letters and mass code are zero-based numeric indices, not characters — the form the address encoder consumes (see SystemNameParts). Use ProceduralSystem.name / ProceduralSystem.massCode for the display strings.

Example

import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';

ProceduralSystem.fromName('Synuefe EN-H d11-96')!.parts;
// { regionName: 'Synuefe', l1: 4, l2: 13, l3: 7, massCode: 3, n1: 11, n2: 96 }

Returns

SystemNameParts

---

position

Get Signature

get position(): GalacticPosition | null

Defined in: src/astro/procedural-system.ts:380

Galactic position (light-years, Sol at origin), if known.

Remarks

Only ever the position you supplied to ProceduralSystem.fromSystemAddress or ProceduralSystem.fromModSystemAddress — a name or an id64 does not carry an exact position, so this is null for a system built from either alone. For an approximate position from an address, use findCodexRegionForBoxel(id64) from ./codex-region-lookup, which returns the boxel corner in light-years.

Returns

GalacticPosition | null

A copy of the position, or null when none is known (null, not undefined — every "absent" result in this library is null).

---

sequence

Get Signature

get sequence(): number

Defined in: src/astro/procedural-system.ts:363

The system's sequence number (N2).

Returns

number

---

systemAddress

Get Signature

get systemAddress(): bigint

Defined in: src/astro/procedural-system.ts:411

The validated 64-bit system address.

Remarks

Construction validates the naming region and every normal-address field, so this getter has no deferred failure mode.

Returns

bigint

Methods

fromModSystemAddress()

static fromModSystemAddress(id64, position?): ProceduralSystem

Defined in: src/astro/procedural-system.ts:295

Build a system from its 64-bit modulated system address.

Parameters

id64

SystemAddressInput

The modulated system address, as a bigint, a safe-integer number, or a decimal string (see SystemAddressInput). Modulated addresses routinely exceed 2^53; those values must be supplied as a bigint or string because a JS number has already lost precision.

position?

GalacticPosition

Galactic position (light-years, Sol at origin). Optional, but required for correct hand-authored-region names.

Returns

ProceduralSystem

The system at that address.

Throws

If the address is not a usable representation.

Throws

If the address is outside 64 bits or its grid slot has no assigned procedural name, or if its sequence cannot fit the normal address layout that every ProceduralSystem exposes.

Example

import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';

declare const modulatedAddress: bigint;

const normal = ProceduralSystem.fromModSystemAddress(modulatedAddress);
normal.systemAddress; // normal-layout id64

---

fromName()

static fromName(name): ProceduralSystem | null

Defined in: src/astro/procedural-system.ts:209

Build a system from a procedural name.

Procedural and catalogued hand-authored region names are re-cased canonically. Unknown naming regions and out-of-range address fields are rejected here rather than creating an object whose address getter fails later.

Parameters

name

string

A system name in any casing, with optional surrounding whitespace, e.g. blae eock kc-c d0.

Returns

ProceduralSystem | null

The system, or null when name is not a procedurally named system. Hand-named systems (Sol, Maia, Shinrarta Dezhra) have no algorithmic address and so yield null too — that is a "not covered by the scheme" answer, not "your string was malformed".

Throws

If name is not a string. A missing or wrong-typed argument is a caller bug, not a name the scheme does not cover, so it is not reported as null.

Throws

If a syntactically valid name has no known naming-region origin, or a name field cannot fit the normal system-address layout.

Example

import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';

ProceduralSystem.fromName('blae eock kc-c d0')?.name; // -> 'Blae Eock KC-C d0'
ProceduralSystem.fromName('Sol');                     // -> null (hand-named system)

---

fromSystemAddress()

static fromSystemAddress(id64, position?): ProceduralSystem

Defined in: src/astro/procedural-system.ts:263

Build a system from its 64-bit system address.

When position is supplied and the system sits inside a hand-authored region, the name is overridden with the hand-authored one (as the game displays it). Without position, the procedural name is used.

Parameters

id64

SystemAddressInput

The system address, as a bigint, a normally parsed journal number (event.SystemAddress), or a decimal string (see SystemAddressInput).

position?

GalacticPosition

Galactic position (light-years, Sol at origin). Optional, but required for correct hand-authored-region names.

Returns

ProceduralSystem

The system at that address.

Remarks

Pass position if you can. An id64 alone encodes only the boxel, not the exact position, so it cannot tell whether the system falls inside a hand-authored region (Pleiades, Coalsack, …). Without position, such a system silently renders under its procedural name instead of the name the game shows. Coordinates come from an external source you already have the id64 from — the player journal, EDSM or Spansh — in light-years with Sol at origin.

Throws

If the address is not a usable representation — a non-integer, or a number beyond 2^53 - 1 that has already been rounded.

Throws

If the address is outside 64 bits or its grid slot has no assigned procedural name.

Example

import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';

ProceduralSystem.fromSystemAddress(3309179996515n).name;
// -> 'Synuefe EN-H d11-96'