Jump to content
Menü aufrufen
Toggle preferences menu
Persönliches Menü aufrufen
Nicht angemeldet
Ihre IP-Adresse wird öffentlich sichtbar sein, wenn Sie Änderungen vornehmen.
Modul Dokumentation[view][edit][history][purge]
Diese Dokumentation wird von Modul:Entity/Location/doc aus übernommen. Änderungen können auf der Diskussionsseite vorgeschlagen werden.
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, als Data.get(args).kind exponiert.
  • 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 Typ Anomaly, den sie sich mit Wrackteilen teilen; ein Gate wird am exakten Jump Point-Namenspräfix/-suffix erkannt.
  • p.resolveSubtype(apiData, args): ein typisierter Datensatz entscheidet allein. recordFamily ist dreiwertig und die Unterscheidung trägt: String nennt das Leaf, false markiert einen typisierten Datensatz, den kein Leaf modelliert (Wrack, schlichter Asteroid), nil heißt gar kein Datensatz. Nur nil fällt an |family= durch.
  • p.getApiConfigs(): der Identitäts-Endpunkt locations/%s.
  • p.getEditorialManifest(): die kindweiten Lore-Felder discoveredin, 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; getCategories löst die Spektralklasse aus dem Starmap-sub_type, bevor der Anzeigetext drankommt. Radius bevorzugt |radius=, sonst die Starmap-size in 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, da apiData.name der Körper selbst ist. Mond-oder-Planet entscheidet in fünf Schritten (Datensatz-Elterntyp, eigener Typ, |type=, Starmap-Token, Default Planet). Radius liest die size des 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 die Asteroid-Zeilen der Locations-API in-systemische POIs sind, nicht die Formationen der Starmap; jede Seite trägt |family=belt|system=. BELT_TYPES bildet die ARK-sub_types auf die Wiki-Begriffe ab; jeder Eintrag nennt page, weil die Familie eine Konzeptseite hat statt Typindizes. Die Distanz-Zeile ist ARK-distance in 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: apiData resettet auf {} und die Kette rerunt enrich allein aus args — so bekommt auch ein Starmap-only-System seine Brücke.
  • attachStarsystem namespaced den Starmap-Datensatz als apiData.starsystem und merged nie flach: beide Payloads tragen kollidierende name/type/description/affiliation-Schlüssel.
  • attachCelestialObject fragt ?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
Cookies helfen uns bei der Bereitstellung dieses Wikis. Durch die Nutzung des Star Citizen Wiki erklärst du dich damit einverstanden, dass wir Cookies speichern.