Modul:Entity/Location
Weitere Optionen
| Function list |
|---|
| L 68 — p.getApiConfigs L 102 — isJumpPointRecord L 142 — recordFamily L 176 — p.matches L 190 — p.resolveSubtype L 205 — p.getEditorialManifest |
Orts-Art (Location-Kind) des Entity-Frameworks: Entitäten hinter dem Spieldaten-Endpunkt /api/locations (Sternensysteme, Sprungpunkte, Sterne, Planeten, Monde, Asteroidenformationen und Orte). Sechs Leafs rendern es: StarSystem, JumpPoint, Star, Body, Belt und Place.
Editoren rufen dieses Modul nie direkt auf; es läuft innerhalb von Vorlage:Location, die die Art deklariert, oder innerhalb von Vorlage:Entity, wenn die UUID der Seite einen Datensatz dieser Art auflöst. Pipeline und Hook-Tabelle stehen auf Modul:Entity.
Für Modul-Editoren
API
p.name = 'Location': kanonischer Artname, alsData.get(args).kindexponiert.p.editorialMode = true: eine artdeklarierte Seite ohne echten Datensatz rendert über den redaktionellen Zweig — der Einstieg für Lore-Systeme, die nur in der Starmap existieren.p.defaultFamily = 'starsystem': das Leaf, das eine artdeklarierte Seite ohne typisierten Datensatz annimmt.p.matches(apiData): wahr für eine Standort-Signatur (respawn_location_type) und einen Datensatz, den ein Leaf rendert. Sprungpunkt-Gates tragen den TypAnomaly, den sie sich mit Wrackteilen teilen; ein Gate wird am exaktenJump Point-Namenspräfix/-suffix erkannt.p.resolveSubtype(apiData, args): ein typisierter Datensatz entscheidet allein.recordFamilyist dreiwertig und die Unterscheidung trägt: String nennt das Leaf,falsemarkiert einen typisierten Datensatz, den kein Leaf modelliert (Wrack, schlichter Asteroid),nilheißt gar kein Datensatz. Nurnilfällt an|family=durch.p.getApiConfigs(): der Identitäts-Endpunktlocations/%s.p.getEditorialManifest(): die kindweiten Lore-Felderdiscoveredin,discoveredby,historicalnames.
Leaves
Zwei Starmap-Brücken bedienen alle sechs Leafs und schließen einander aus: StarSystem, Body, Belt und Place holen über attachStarsystem ein ganzes System als apiData.starsystem; JumpPoint und Star über attachCelestialObject ein Objekt als apiData.celestialobject.
- StarSystem (
starsystem): Brücke über den Systemnamen. Liefert Systemtyp- und Zugehörigkeitskategorien, einen eingeklappten Orbitalzonen-Abschnitt sowie Starmap-Schaltfläche und Metadatenzeile. - JumpPoint (
jumppoint): Brücke über|starmapcode=. Ein- und Ausgangssystem kommen zuerst aus dem kanonischen Seitennamen, dann aus der Starmap-Bezeichnung. - Star (
star): eine Seite pro Stern, dazu das schwarze Loch in derselben Gestalt. Die Klassifizierung ist der Infobox-Untertitel;getCategorieslöst die Spektralklasse aus dem Starmap-sub_type, bevor der Anzeigetext drankommt. Radius bevorzugt|radius=, sonst die Starmap-sizein km, unterdrückt unter 5 km und über dem Klassen-maxRadiusKm. - Body (
body): Planeten und Monde in einem Leaf, weil sich ein Mond von einem Planeten nur im Elternteil unterscheidet. Gibt den SYSTEMNAMen explizit weiter, daapiData.nameder Körper selbst ist. Mond-oder-Planet entscheidet in fünf Schritten (Datensatz-Elterntyp, eigener Typ,|type=, Starmap-Token, Default Planet). Radius liest diesizedes Datensatzes in Metern, nie die der Starmap; ohne Datensatz gilt|radius=in Kilometern. - Belt (
belt): Gürtel, Haufen und Planetenringe. Nichts dispatcht hier aus einem Datensatz, weil dieAsteroid-Zeilen der Locations-API in-systemische POIs sind, nicht die Formationen der Starmap; jede Seite trägt|family=belt|system=.BELT_TYPESbildet die ARK-sub_types auf die Wiki-Begriffe ab; jeder Eintrag nenntpage, weil die Familie eine Konzeptseite hat statt Typindizes. Die Distanz-Zeile ist ARK-distancein AE, elternrelativ; ein Ring meldet 0 und die Zeile entfällt. - Place (
place): Stationen, Außenposten, Landezonen und ihre Einrichtungen; die Klasse ist ein kuratiertes|classification=aus classes.json. Die Zone (surface, orbit, lagrange, inside, star) kommt zuerst aus|lagrange=/|zone=, dann aus dem Datensatz, sonst der Klassen-Default. Die Zuständigkeit kommt aus Modul:Entity/Location/Jurisdiction.
Erweitern
Ein weiteres Leaf: pages/module/Entity/Location/<Name>.lua mit p.parent = 'Entity/Location' und einem p.family, das mit seinem LOCATION_SUBTYPE_MAP-Schlüssel übereinstimmt. Genau ein Eintrag in LOCATION_SUBTYPE_MAP (ein Loader), und recordFamily muss den Token für die beanspruchten Datensätze liefern. testSubtypeLeavesConformToChainLinkContract in den Testcases validiert jedes Leaf gegen Modul:Entity/Contract im strikten Modus; ein neues Leaf ist damit abgedeckt, sobald es in der Map steht.
Stolperfallen
- Ein datensatzloses Lore-System rendert über den redaktionellen Zweig:
apiDataresettet auf{}und die Kette reruntenrichallein ausargs— so bekommt auch ein Starmap-only-System seine Brücke. attachStarsystemnamespaced den Starmap-Datensatz alsapiData.starsystemund merged nie flach: beide Payloads tragen kollidierendename/type/description/affiliation-Schlüssel.attachCelestialObjectfragt?include=starsystem, weil das der einzige verlässliche Weg ist, das System eines Objekts zu benennen: das erste Segment eines Starmap-Codes ist ein Code, kein Name.- Die
Jump Point-Namensanker sind absichtlich case-sensitiv und ungetrimmt: die API emittiert die Titelcase-Form ohne nachfolgende Leerzeichen auf jedem beobachteten Datensatz.
require('strict')
--- @module Entity/Location
--- Location kind: entities backed by the game-data /api/locations endpoint
--- (star systems, planets, moons, stations, …). Six leaves render it:
--- SolarSystem (StarSystem), jump points (JumpPoint), stars (Star), planets
--- and moons (Body), asteroid formations (Belt, reached only through
--- |family=) and places (Place: stations, outposts, landing zones and the
--- venues inside them). matches() claims exactly the records a leaf renders.
--- Jump-point gates are recognised by name, because the locations API types
--- them 'Anomaly', a token shared with wreck sites (see isJumpPointRecord).
--- Wreck sites and plain Asteroid records stay unclaimed. This module is kind
--- identity only; the starmap vocabulary, the starmap bridges the leaves'
--- enrich hooks call, and the rows they share live in
--- Module:Entity/Location/Vocabulary, /Starmap and /Display.
local subtypeResolver = require('Module:Entity/SubtypeResolver')
local p = {}
--- Canonical kind name, exposed as Data.get(args).kind (non-empty and
--- unique, enforced by the Registry conformance test).
p.name = 'Location'
--- Kind-declared pages (Template:Location injects |kind=Location) render
--- through the editorial fork when no location record resolves — the entry
--- path for the ~84 lore systems that exist only in the starmap.
p.editorialMode = true
--- @type string
p.parent = 'Entity/Base'
--- Family token → leaf loader (see Module:Entity/SubtypeResolver). The
--- tokens are the leaves' p.family tags and the values a curated |family=
--- may name on a record-less page.
local LOCATION_SUBTYPE_MAP = {
starsystem = function()
return require('Module:Entity/Location/StarSystem')
end,
jumppoint = function()
return require('Module:Entity/Location/JumpPoint')
end,
star = function()
return require('Module:Entity/Location/Star')
end,
body = function()
return require('Module:Entity/Location/Body')
end,
belt = function()
return require('Module:Entity/Location/Belt')
end,
place = function()
return require('Module:Entity/Location/Place')
end,
-- The corpus's POI pages (lore islands, facilities without records) are
-- places in this framework; the census wording keeps resolving when an
-- editor carries it over.
poi = function()
return require('Module:Entity/Location/Place')
end,
}
--- The leaf a kind-declared page with no typed record resolves to: the lore
--- star systems that exist only in the starmap. Overridden by |family=.
p.defaultFamily = 'starsystem'
--- @return EntityApiConfig[]
function p.getApiConfigs()
return {
{
name = 'StarCitizenWikiAPI',
endpoint = 'locations/%s',
-- The endpoint is fully locale-invariant (probed 2026-11-04: zero
-- field differences en_EN vs de_DE), so no ingest aliases are needed;
-- de_DE keeps the every-request locale policy uniform.
params = { locale = 'de_DE' },
responseDataPath = 'data',
},
}
end
--- The literal name suffix that separates a jump-point gate from every other
--- Anomaly-typed record. One constant so the length arithmetic below cannot
--- drift from the text.
local JUMP_POINT_SUFFIX = 'Jump Point'
--- Is this location record a jump-point gate? The locations API types jump
--- points as 'Anomaly', a token it shares with records that are NOT jump
--- points (the "Stanton-Pyro Jump Point Wreck Site"), so the type alone cannot
--- dispatch; a gate's name either ends exactly in "Jump Point" (every record
--- but one) or begins exactly with "Jump Point " (the one upstream misnaming,
--- "Jump Point Pyro Castra" — a real Pyro gate whose page still deserves its
--- record). Exact anchored matches, never a substring one: the wreck site
--- carries the words mid-name (neither anchor) and stays unresolved.
--- Case-sensitive and untrimmed BY DESIGN: the API emits the title-case
--- 'Jump Point' form with no trailing whitespace on every observed record,
--- and normalizing here would loosen the gate beyond observed data. The ONE
--- predicate recordFamily uses to tell a gate from every other Anomaly-typed
--- record, so matches() and resolveSubtype() cannot drift.
--- @param apiData table|nil
--- @return boolean
local function isJumpPointRecord(apiData)
if type(apiData) ~= 'table' or type(apiData.type) ~= 'table' then
return false
end
-- The unambiguous token: a handful of records (the Stanton-side gates) are
-- typed 'JumpPoint' outright — no name check needed or wanted there, since
-- repurposed gates carry STALE names ("Stanton - Magnus Jump Point" is the
-- in-game Stanton - Nyx gate; its parent object, Nyx Gateway, is the
-- truth). Name anchors below apply only to the ambiguous 'Anomaly' token.
if apiData.type.name == 'JumpPoint' then
return true
end
if apiData.type.name ~= 'Anomaly' or type(apiData.name) ~= 'string' then
return false
end
return apiData.name:sub(-#JUMP_POINT_SUFFIX) == JUMP_POINT_SUFFIX
or apiData.name:sub(1, #JUMP_POINT_SUFFIX + 1) == JUMP_POINT_SUFFIX .. ' '
end
--- Record types the Place leaf renders. Plain 'Asteroid' is absent on purpose:
--- those records are formation clusters, not places anyone travels to.
local PLACE_TYPES = {
Outpost = true,
Outpost_InvalidQT = true,
Manmade = true,
Manmade_VisibleOnInteraction = true,
LandingZone = true,
PointOfInterest = true,
NavPoint = true,
Asteroid_ValidQT = true,
}
--- Family token of a typed location record: 'jumppoint' for a gate,
--- 'starsystem' for a SolarSystem record, 'star' for a Star record, 'body' for a
--- Planet or Moon record, 'place' for a station, outpost, landing zone or
--- venue, false for a typed record no leaf models (wreck sites, plain
--- asteroids), nil when the record carries no type table at all (no record, or
--- the editorial fork's empty apiData).
--- @param apiData table|nil
--- @return string|false|nil
local function recordFamily(apiData)
if type(apiData) ~= 'table' or type(apiData.type) ~= 'table' then
return nil
end
if isJumpPointRecord(apiData) then
return 'jumppoint'
end
if apiData.type.name == 'SolarSystem' then
return 'starsystem'
end
-- Only three stars are in the game (Stanton, Pyro, Nyx); every other star
-- page is record-less and reaches the Star leaf through a curated |family=.
if apiData.type.name == 'Star' then
return 'star'
end
-- One leaf serves both: a moon differs from a planet only in what its
-- parent is, which is a value rather than a shape.
if apiData.type.name == 'Planet' or apiData.type.name == 'Moon' then
return 'body'
end
if PLACE_TYPES[apiData.type.name] then
return 'place'
end
return false
end
--- Positive identification: a location signature (`respawn_location_type`, a
--- field no item, vehicle, commodity, mission, or blueprint record carries)
--- AND a record one of this kind's leaves renders. Nil-safe, strict boolean,
--- order-independent — the declared-kind gate offers a record of any kind to
--- matches(), and a kind claims a record exactly when it can render it.
---
--- @param apiData table|nil
--- @return boolean
function p.matches(apiData)
return apiData ~= nil and apiData.respawn_location_type ~= nil and type(recordFamily(apiData)) == 'string'
end
--- Refine to the family leaf. A typed record decides alone: its family token
--- (see recordFamily), or nil for a record no leaf models — a declared kind
--- or a |family= arg never rescues a wreck site. With no typed record (the
--- editorial fork), the curated |family= names the leaf when it is one this
--- kind maps (the starmap-only tunnels declare `jumppoint`); otherwise a
--- kind-declared page takes the StarSystem default, and an undeclared page
--- resolves nothing.
--- @param apiData table|nil
--- @param args table|nil
--- @return table|nil leaf module
function p.resolveSubtype(apiData, args)
local family = recordFamily(apiData)
if family == nil then
family = subtypeResolver.familyArg(args)
if (family == nil or LOCATION_SUBTYPE_MAP[family] == nil) and type(args) == 'table' and args.kind ~= nil then
family = p.defaultFamily
end
end
return subtypeResolver.resolve(family or nil, LOCATION_SUBTYPE_MAP)
end
--- Editorial fields every location leaf renders in its Lore section:
--- API-absent, pure-editorial. Leaf-specific fields live on the leaves and
--- merge over this fragment (Module:Entity/Assembly.mergeEditorialManifests).
--- @return table
function p.getEditorialManifest()
return {
discoveredin = { arg = 'discoveredin', property = 'Discovered in' },
discoveredby = { arg = 'discoveredby', property = 'Discovered by' },
historicalnames = { arg = 'historicalnames' },
}
end
-- Test-only exports. Not part of the public API.
p._internal = {
isJumpPointRecord = isJumpPointRecord,
recordFamily = recordFamily,
LOCATION_SUBTYPE_MAP = LOCATION_SUBTYPE_MAP,
}
return p

