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.

Die Dokumentation für dieses Modul kann unter Modul:Entity/Location/StarSystem/doc erstellt werden

require('strict')

--- @module Entity/Location/StarSystem
--- Star-system leaf of the Location kind. Renders from the merged payload the
--- kind assembles: the location record at the top level plus the starmap
--- record at apiData.starsystem (attached by this leaf's enrich through
--- locationStarmap.attachStarsystem; may be absent — every consumer nil-guards and
--- degrades to location-only rows).

local jurisdiction = require('Module:Entity/Location/Jurisdiction')
local locationDisplay = require('Module:Entity/Location/Display')
local msg = require('Module:Entity/Message').msg
local locationStarmap = require('Module:Entity/Location/Starmap')
local locationVocabulary = require('Module:Entity/Location/Vocabulary')
local sectionBuilder = require('Module:Entity/SectionBuilder')
local statTiles = require('Module:StatTiles')
local Editorial = require('Module:Entity/Editorial')

local p = {}

--- @type string
p.parent = 'Entity/Location'

--- RSI starmap workflow status code → label. Rendered as a plain
--- "Starmap status" row (the label carries the disambiguation): this is
--- RSI's editorial state for the starmap entry, deliberately NOT badged so
--- it cannot be mistaken for an in-game availability state.
local STATUS_LABELS = {
	P = 'Published',
	D = 'Draft',
	R = 'Review',
	S = 'Stub',
	N = 'Probe data incomplete',
	U = 'Undiscovered',
	M = 'UEE Military Classified',
}

--- Tile catalog: celestial_objects type → labels, in display order. `one` is
--- the count-1 label; `title` carries the unabbreviated name as a tooltip;
--- `field` names the editorial count-override field (legacy {{System}} arg),
--- resolved through the editorial view so hand counts beat the starmap tally.
local OBJECT_TILES = {
	{ type = 'STAR', one = 'Star', many = 'Stars' },
	{ type = 'PLANET', one = 'Planet', many = 'Planets', field = 'planets' },
	{ type = 'SATELLITE', one = 'Moon', many = 'Moons', field = 'satellites' },
	{ type = 'ASTEROID_BELT', one = 'Belt', many = 'Belts', title = 'Asteroid belts', field = 'asteroidbelts' },
	{ type = 'ASTEROID_FIELD', one = 'Field', many = 'Fields', title = 'Asteroid fields', field = 'asteroidfields' },
	{ type = 'MANMADE', one = 'Station', many = 'Stations', field = 'stations' },
	{ type = 'JUMPPOINT', one = 'Jump point', many = 'Jump points', field = 'jumppoints' },
	{ type = 'ANOMALY', one = 'Anomaly', many = 'Anomalies', field = 'anomalies' },
	{ type = 'BLACKHOLE', one = 'Black hole', many = 'Black holes', field = 'blackholes' },
	{ type = 'POI', one = 'POI', many = 'POIs', field = 'pois' },
}

--- @param apiData table
--- @return table|nil
local function getStarsystem(apiData)
	return type(apiData.starsystem) == 'table' and apiData.starsystem or nil
end

--- Family token: dispatched by Location.resolveSubtype and named by a curated
--- |family= on record-less pages; the kind's default leaf.
p.family = 'starsystem'

--- @param ctx EntityHookContext
--- @return table apiData
function p.enrich(ctx)
	return locationStarmap.attachStarsystem(ctx.apiData, ctx.args)
end

--- Star-system editorial fields. size overlaps the starmap aggregated size
--- attached by enrich; startypes carries no apiPath because its API value is
--- derived from the celestial-object list — the section builder passes the
--- computed value as the editorial view's fallback instead. affiliation and
--- systemtype are pure-editorial identity for the systems the starmap does
--- not list (Hyoton, Krell, Ophos, …), no property key: this leaf stores both
--- itself through the same resolvers the display uses (affiliationFromText /
--- systemTypeEntry), so a free-text affiliation and its stored value cannot
--- disagree. `type` is the legacy {{System}} arg name. The object-count
--- overrides (legacy {{System}} arg names) beat the starmap tallies; no property
--- key, getStructuredData stores the resolved counts itself.
--- @return table
function p.getEditorialManifest()
	return {
		population = { arg = 'population' },
		size = { arg = 'size', property = 'System size', apiPath = 'starsystem.aggregated.size', transform = 'number' },
		startypes = { arg = 'startypes' },
		affiliation = { arg = 'affiliation' },
		systemtype = { arg = { 'systemtype', 'type' } },
		planets = { arg = 'planets', transform = 'number' },
		satellites = { arg = 'satellites', transform = 'number' },
		asteroidbelts = { arg = 'asteroidbelts', transform = 'number' },
		asteroidfields = { arg = 'asteroidfields', transform = 'number' },
		anomalies = { arg = 'anomalies', transform = 'number' },
		stations = { arg = 'stations', transform = 'number' },
		jumppoints = { arg = 'jumppoints', transform = 'number' },
		blackholes = { arg = 'blackholes', transform = 'number' },
		pois = { arg = 'pois', transform = 'number' },
	}
end

--- Category parity with the legacy Module:System beyond the `Systems` bucket
--- (typeInfo.category supplies that one): the system-type and affiliation
--- trees. A free-text affiliation categorizes as `<text> systems` exactly as
--- the legacy template did (Kr'Thak systems, Unknown systems — both live
--- categories).
--- @param ctx EntityHookContext
--- @return string[]
function p.getCategories(ctx)
	local apiData, resolved = ctx.apiData, ctx.resolved
	local categories = {}
	local starsystem = getStarsystem(apiData)
	local _, typeEntry = locationVocabulary.resolveSystemType(starsystem, resolved)
	if typeEntry then
		categories[#categories + 1] = typeEntry.category
	end
	local affiliation = locationVocabulary.resolveAffiliation(starsystem, resolved)
	if affiliation then
		categories[#categories + 1] = locationVocabulary.systemsCategory(affiliation)
	end
	return categories
end

--- The ARK starmap code (the `?location=` key), or nil. Two consumers read it —
--- the Starmap footer button and the Metadata row — and they open-coded the same
--- guard, which let an empty-string code through both: a `?location=` button
--- pointing at the starmap index, and a blank "Starmap code" row. One accessor,
--- so they cannot drift and the empty case is rejected once.
--- @param apiData table
--- @return string|nil
local function starmapCode(apiData)
	local starsystem = getStarsystem(apiData)
	local code = starsystem and starsystem.code or nil
	if type(code) ~= 'string' or code == '' then
		return nil
	end
	return code
end

--- @param starsystem table|nil
--- @return table aggregated ({} when absent)
local function getAggregated(starsystem)
	local aggregated = starsystem and starsystem.aggregated
	return type(aggregated) == 'table' and aggregated or {}
end

--- Count celestial objects by type.
--- @param starsystem table|nil
--- @return table<string, number>
local function countObjects(starsystem)
	local counts = {}
	local objects = starsystem and starsystem.celestial_objects
	if type(objects) ~= 'table' then
		return counts
	end
	for _, obj in ipairs(objects) do
		if type(obj) == 'table' and type(obj.type) == 'string' then
			counts[obj.type] = (counts[obj.type] or 0) + 1
		end
	end
	return counts
end

--- StatTiles items for the object counts, catalog order, zeros omitted.
--- Editorial overrides (`ed`, optional) beat the starmap tallies per tile.
--- @param starsystem table|nil
--- @param ed table|nil Editorial view
--- @return StatTilesItem[]
local function buildObjectTiles(starsystem, ed)
	local counts = countObjects(starsystem)
	local tiles = {}
	for _, def in ipairs(OBJECT_TILES) do
		local count = counts[def.type]
		if def.field and ed then
			count = ed:value(def.field, count)
		end
		count = tonumber(count)
		if count and count > 0 then
			tiles[#tiles + 1] = {
				value = count,
				label = count == 1 and msg(def.one) or msg(def.many),
				title = def.title and msg(def.title) or nil,
			}
		end
	end
	return tiles
end

--- Display list of the system's star types, each linked to its index page,
--- deduplicated and comma-joined. Deduplication keys on the LABEL rather than
--- the rendered link, so a binary whose two stars share a class still lists it
--- once. Display only: no star-type value is stored, so the markup reaches
--- nothing but the row.
--- @param starsystem table|nil
--- @return string|nil
local function starTypeList(starsystem)
	local objects = starsystem and starsystem.celestial_objects
	if type(objects) ~= 'table' then
		return nil
	end
	local names, seen = {}, {}
	for _, obj in ipairs(objects) do
		if type(obj) == 'table' and obj.type == 'STAR' and type(obj.sub_type) == 'table' then
			local name = locationVocabulary.starTypeLabel(obj.sub_type)
			if type(name) == 'string' and not seen[name] then
				seen[name] = true
				-- Deduplicated on the English word; the display localizes so a
				-- binary's shared class still lists once.
				names[#names + 1] =
					locationVocabulary.starTypeLink(locationVocabulary.starTypeEntry(obj.sub_type), msg(name))
			end
		end
	end
	if #names == 0 then
		return nil
	end
	return table.concat(names, ', ')
end

--- Affiliation display text: canonical entries link their label
--- ("[[United Empire of Earth]]"), a free-text entry renders exactly what the
--- editor wrote (`display`) - they decide whether [[Kr'Thak]] links, so
--- 'Unknown' is never painted red by an auto-link - and a `link = false`
--- entry renders its plain label because no article exists to link.
--- @param starsystem table|nil
--- @param resolved table|nil
--- @return string|nil
local function affiliationDisplay(starsystem, resolved)
	local affiliation = locationVocabulary.resolveAffiliation(starsystem, resolved)
	if not affiliation then
		return nil
	end
	if affiliation.display then
		return affiliation.display
	end
	if affiliation.link == false then
		return affiliation.label
	end
	return '[[' .. affiliation.label .. ']]'
end

--- The system's two orbital-zone distances, in AU from the star: the habitable
--- zone (where liquid water is possible — Stanton's four planets all sit inside
--- it) and the frost line (beyond which volatiles stay frozen). Zero is the
--- starmap's no-data sentinel here, not a measurement: every unsurveyed system
--- reports a flat 0/0/0, so each value is guarded independently rather than as
--- a block — Oberon publishes a frost line with no habitable zone at all.
--- @param starsystem table|nil
--- @return EntityItemData[]
local function buildZoneItems(starsystem)
	local items = {}
	if type(starsystem) ~= 'table' then
		return items
	end
	local inner = tonumber(starsystem.habitable_zone_inner)
	local outer = tonumber(starsystem.habitable_zone_outer)
	if inner and outer and inner > 0 and outer > 0 then
		sectionBuilder.push(
			items,
			msg('Habitable zone'),
			locationDisplay.decimal(inner)
				.. ' – '
				.. locationDisplay.decimal(outer)
				.. locationDisplay.astronomicalUnit()
		)
	end
	local frost = tonumber(starsystem.frost_line)
	if frost and frost > 0 then
		sectionBuilder.push(
			items,
			msg('Frost line'),
			locationDisplay.decimal(frost) .. locationDisplay.astronomicalUnit()
		)
	end
	return items
end

--- Type info runs before editorial resolution in Data.get, so the editorial
--- system type is read from the raw args through Editorial.rawArg with this
--- leaf's own manifest entry; everything downstream of resolution goes
--- through locationVocabulary.resolveSystemType instead.
--- This leaf declares the systemtype entry itself, so its own
--- getEditorialManifest fragment is the merged chain manifest's value for
--- the field — reading its own entry here is correct only because of that.
--- @param ctx EntityHookContext
--- @return { name: string, category: string }
function p.getTypeInfo(ctx)
	local apiData, args = ctx.apiData, ctx.args
	local _, editorialEntry =
		locationVocabulary.systemTypeEntry(Editorial.rawArg(args, p.getEditorialManifest().systemtype))
	local starsystem = getStarsystem(apiData)
	local typeInfo = editorialEntry or (starsystem and locationVocabulary.SYSTEM_TYPES[starsystem.type] or nil)
	return {
		name = typeInfo and typeInfo.label or 'Star system',
		category = 'Sternensystem',
	}
end

--- @param ctx EntityHookContext
--- @return EntitySectionEntry[]
function p.getSections(ctx)
	local apiData, resolved = ctx.apiData, ctx.resolved
	local ed = Editorial.view(resolved)
	local starsystem = getStarsystem(apiData)
	local aggregated = getAggregated(starsystem)

	local general = {}
	sectionBuilder.push(general, msg('Affiliation'), affiliationDisplay(starsystem, resolved))
	local jurisdictionName = type(apiData.jurisdiction) == 'table' and apiData.jurisdiction.name or nil
	sectionBuilder.push(general, msg('Jurisdiction'), jurisdiction.display(jurisdictionName))
	local size = ed:value('size', aggregated.size)
	sectionBuilder.push(
		general,
		msg('Size'),
		size and (locationDisplay.decimal(size) .. locationDisplay.astronomicalUnit())
	)
	local starTypes = ed:value('startypes', starTypeList(starsystem))
	local starLabel = (type(starTypes) == 'string' and starTypes:find(',', 1, true)) and msg('Star types')
		or msg('Star type')
	sectionBuilder.push(general, starLabel, starTypes)
	sectionBuilder.push(general, msg('Population'), ed:value('population'))
	sectionBuilder.push(general, msg('Starmap status'), starsystem and msg(STATUS_LABELS[starsystem.status]) or nil)

	local sensor = {}
	locationDisplay.appendSensorMeter(sensor, msg('Economy'), aggregated.economy)
	locationDisplay.appendSensorMeter(sensor, msg('Population'), aggregated.population)

	local objects = {}
	local tiles = buildObjectTiles(starsystem, ed)
	if #tiles > 0 then
		objects[#objects + 1] = {
			content = statTiles.render({ items = tiles }),
			class = 't-infobox-item--block',
		}
	end

	local lore = {}
	sectionBuilder.push(lore, msg('Discovered in'), ed:value('discoveredin'))
	sectionBuilder.push(lore, msg('Discovered by'), ed:value('discoveredby'))
	sectionBuilder.push(lore, msg('Historical names'), ed:value('historicalnames'))

	return sectionBuilder.build(
		sectionBuilder.section({ key = 'general', items = general }),
		sectionBuilder.section({ key = 'sensor', label = msg('Sensor readings'), items = sensor }),
		sectionBuilder.section({ key = 'objects', label = msg('Astronomical objects'), items = objects }),
		-- Collapsed, unlike Lore: the zones are reference astronomy with no
		-- bearing on play, so they stay out of the way until asked for.
		sectionBuilder.section({
			key = 'zones',
			label = msg('Orbital zones'),
			collapsible = true,
			collapsed = true,
			items = buildZoneItems(starsystem),
		}),
		sectionBuilder.section({ key = 'lore', label = msg('Lore'), collapsible = true, items = lore })
	)
end

--- Pure-API structured data. size / discoveredin / discoveredby storage is
--- owned by the editorial manifest (property fields there) — do not double-store.
--- @param ctx EntityHookContext
--- @return table<string, any>
function p.getStructuredData(ctx)
	local apiData, resolved = ctx.apiData, ctx.resolved
	local starsystem = getStarsystem(apiData)
	local ed = Editorial.view(resolved)
	local counts = countObjects(starsystem)
	-- No early return without a starmap record: the no-record lore systems
	-- (Hyoton, Krell, …) carry their identity and counts editorially, and
	-- those must store exactly like everyone else's.
	-- System type stores the SYSTEM_TYPES display label ('Single star
	-- system'), the same string the infobox subtitle shows, so store and
	-- display cannot disagree — the raw-code vocabulary existed to share one
	-- query bucket with the legacy Module:System pages, and that constraint
	-- retired with the module (this leaf is now the property's only writer).
	-- An unmapped code stores raw as the fallback: a future ARK type degrades
	-- to a visible code instead of vanishing, and self-heals once mapped.
	-- Affiliation stores the compact form (UEE / Unclaimed), or the delinked
	-- free text for affiliations only lore knows (Kr'Thak). Counts go through
	-- the editorial view so the stored numbers always equal the displayed
	-- tiles (hand counts beat the starmap tallies).
	local typeCode, typeEntry = locationVocabulary.resolveSystemType(starsystem, resolved)
	local affiliation = locationVocabulary.resolveAffiliation(starsystem, resolved)
	return {
		system_type = typeEntry and typeEntry.label or typeCode,
		affiliation = affiliation and (affiliation.short or affiliation.label) or nil,
		star_count = counts.STAR,
		planet_count = tonumber(ed:value('planets', counts.PLANET)),
		moon_count = tonumber(ed:value('satellites', counts.SATELLITE)),
		station_count = tonumber(ed:value('stations', counts.MANMADE)),
		jump_point_count = tonumber(ed:value('jumppoints', counts.JUMPPOINT)),
	}
end

--- German short description: "<UEE->Einsternsystem mit 4 Planeten"; no
--- planets -> no count clause; no type -> "Sternensystem mit N Planeten"; no
--- record at all -> the catch-all. The affiliation joins as a prefix only
--- where it compounds: free text, developing and unknown do not (an unbounded
--- or mis-composed prefix reads wrong there, so the row and category carry
--- those and the short description stays predictable).
--- @param ctx EntityHookContext
--- @return string
function p.getShortDescription(ctx)
	local apiData, typeInfo, resolved = ctx.apiData, ctx.typeInfo, ctx.resolved
	local starsystem = getStarsystem(apiData)
	local _, typeEntry = locationVocabulary.resolveSystemType(starsystem, resolved)
	local planets = tonumber(Editorial.view(resolved):value('planets', countObjects(starsystem).PLANET)) or 0
	local countClause = planets == 1 and msg(' with 1 planet') or msg(' with $1 planets', { planets })

	if typeEntry then
		local noun = msg(typeInfo and typeInfo.name or 'Star system')
		local affiliation = locationVocabulary.resolveAffiliation(starsystem, resolved)
		local prefix = affiliation and not affiliation.display and locationVocabulary.shortPrefix(affiliation) or nil
		local desc = (prefix or '') .. noun
		if planets > 0 then
			desc = desc .. countClause
		end
		return desc
	end
	if planets > 0 then
		return msg('System') .. countClause
	end
	return msg('A star system in Star Citizen')
end

--- RSI Starmap as a footer action button (from the starsystem code), sitting
--- beside the Galactapedia and Wiki API buttons. Galactapedia itself is NOT
--- handled here: the Infobox footer already renders it from
--- args.galactapediaurl.
--- @param ctx EntityHookContext
--- @return table[]
function p.getFooterButtons(ctx)
	return locationDisplay.starmapFooterButtons(starmapCode(ctx.apiData))
end

--- Chain-contributed Metadata rows: the ARK starmap code, through the same
--- accessor as the footer button so the two cannot disagree.
--- @param ctx EntityHookContext
--- @return EntityItemData[]
function p.getMetadataItems(ctx)
	return locationDisplay.starmapMetadataItems(starmapCode(ctx.apiData))
end

-- Test-only exports. Not part of the public API.
p._internal = {
	buildZoneItems = buildZoneItems,
	countObjects = countObjects,
	buildObjectTiles = buildObjectTiles,
	starTypeList = starTypeList,
	affiliationDisplay = affiliationDisplay,
	starmapCode = starmapCode,
	STATUS_LABELS = STATUS_LABELS,
}

return p
Zuletzt geändert
Urheberrecht
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.