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/Belt/doc erstellt werden

require('strict')

--- @module Entity/Location/Belt
--- Asteroid-formation leaf of the Location kind: belts, clusters and planetary
--- rings in one module. They differ only in what they orbit and what the wiki
--- calls them, the same argument that puts planets and moons in one leaf.
---
--- Unlike the Body leaf there is effectively no game record behind these. The
--- locations API does type 682 records `Asteroid`, but they are in-system points
--- of interest -- mining claims, mining bases, extraction stations, the Lagrange
--- clusters -- and not the formations the starmap catalogues; only the handful of
--- pages named for a Lagrange point overlap. So this leaf renders from the
--- starmap STAR-SYSTEM record at
--- apiData.starsystem, for the same reason the Body leaf needs it: the starmap
--- gives a parent only as a numeric `parent_id`, resolvable against its own
--- system's object list.

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

local p = {}

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

--- Family token, curated on every page: no record types these, so nothing
--- dispatches here automatically.
p.family = 'belt'

--- `code`, `classification` and `system` are the legacy {{Astronomical object}}
--- arg names. No entry takes a property key — getStructuredData stores these
--- itself, so display and store cannot diverge. This leaf declares every entry,
--- which is the only reason reading its own fragment below is correct.
--- @return table
function p.getEditorialManifest()
	return {
		starmapcode = { arg = { 'starmapcode', 'code' } },
		classification = { arg = 'classification' },
		system = { arg = 'system' },
		affiliation = { arg = 'affiliation' },
		designation = { arg = 'designation' },
	}
end

--- @param args table|nil
--- @return string|nil
local function starmapCode(args)
	return locationStarmap.manifestArg(args, p.getEditorialManifest(), 'starmapcode')
end

--- The ARK object types this leaf may resolve to. The two are one family to the
--- wiki but two tokens to the ARK, and a cluster can carry either.
local BELT_OBJECT_TYPES = { ASTEROID_BELT = true, ASTEROID_FIELD = true }

--- This formation's own object inside the attached system payload: by the
--- editor's `code` when there is one, else by name. A code is never derivable
--- here either — Hades IV split is `HADES.PLANET.HADESIVSPLIT`, a PLANET
--- segment on an asteroid cluster.
--- @param apiData table
--- @param args table|nil
--- @return table|nil
local function celestial(apiData, args)
	local starsystem = locationStarmap.starsystemOf(apiData)
	return locationStarmap.celestialByCode(starsystem, starmapCode(args))
		or locationStarmap.celestialByName(starsystem, locationStarmap.subjectName(apiData, args), BELT_OBJECT_TYPES)
end

--- @param apiData table
--- @param args table|nil
--- @return string|nil
local function resolvedStarmapCode(apiData, args)
	return locationStarmap.resolvedStarmapCode(args, p.getEditorialManifest(), celestial(apiData, args))
end

--- @param args table|nil
--- @return string|nil
local function editorialClassification(args)
	return locationStarmap.manifestArg(args, p.getEditorialManifest(), 'classification')
end

--- The vocabulary entry this page's starmap object resolves to.
--- @param apiData table
--- @param args table|nil
--- @return { classification: string, category: string, page: string }|nil
local function beltEntry(apiData, args)
	local obj = celestial(apiData, args) or {}
	return locationVocabulary.beltTypeEntry(obj.sub_type, obj.type)
end

--- The formation's classification: the editor's text when given, delinked so it
--- can reach the stored `Subject type` safely; else the starmap object's
--- vocabulary entry; else nil, leaving the bare kind noun.
--- @param apiData table
--- @param args table|nil
--- @return string|nil
local function classification(apiData, args)
	local editorialText = editorialClassification(args)
	if type(editorialText) == 'string' and editorialText ~= '' then
		return Editorial.toStoredValue(editorialText)
	end
	local entry = beltEntry(apiData, args)
	return entry and entry.classification or nil
end

--- The system's short name: the editorial arg the sweep writes, else the
--- record's own. NOT the starmap code's first segment, which is not always the
--- system.
--- @param apiData table
--- @param args table|nil
--- @param raw boolean|nil forwarded to systemNameFrom for the storage path
---   and the system row label
--- @return string|nil
local function systemName(apiData, args, raw)
	return locationStarmap.systemNameFrom(apiData, args, p.getEditorialManifest(), raw)
end

--- Bridges by the SYSTEM name, explicitly, for the same reason the Body leaf
--- does: this page's own name is the formation, not its system.
--- @param ctx EntityHookContext
--- @return table apiData
function p.enrich(ctx)
	local system = systemName(ctx.apiData, ctx.args)
	if not system then
		return ctx.apiData
	end
	return locationStarmap.attachStarsystem(ctx.apiData, ctx.args, system)
end

--- What this formation orbits, as display name plus link target. A belt or
--- cluster hangs off the star; a ring hangs off its planet, which is the whole
--- difference between them. The starmap parent is the ONLY source here: unlike
--- a body, a formation has no record to carry one.
--- @param apiData table
--- @param args table|nil
--- @return string|nil name
--- @return string|nil target
local function parentAnchor(apiData, args)
	return locationDisplay.celestialParentAnchor(locationStarmap.starsystemOf(apiData), celestial(apiData, args))
end

--- @param apiData table
--- @param args table|nil
--- @return string|nil
local function locationChain(apiData, args)
	local parentName, parentTarget = parentAnchor(apiData, args)
	-- Raw system value: the chain's target derives the stored spelling from
	-- the original (Starmap.systemLinkTarget), not a pre-shortened name.
	return locationDisplay.locationChain(
		locationStarmap.starsystemOf(apiData),
		systemName(apiData, args, true),
		parentName,
		parentTarget
	)
end

--- @param apiData table
--- @param resolved table|nil
--- @return string|nil
local function affiliationText(apiData, resolved)
	return locationDisplay.affiliationDisplay(locationStarmap.starsystemOf(apiData), resolved)
end

--- The distance from what it orbits, in AU. Parent-relative, not star-relative,
--- so it is only comparable between siblings; a ring reports 0 because it sits
--- on its planet.
--- @param apiData table
--- @param args table|nil
--- @return string|nil
local function distanceAu(apiData, args)
	local au = tonumber((celestial(apiData, args) or {}).distance)
	if not au or au <= 0 then
		return nil
	end
	return locationDisplay.decimal((string.format('%.2f', au):gsub('%.?0+$', ''))) .. locationDisplay.astronomicalUnit()
end

--- The classification is the subtitle, so no row repeats it. `name` must stay
--- PLAIN: Entity stores it as `Subject type`.
--- @param ctx EntityHookContext
--- @return { name: string, category: string }
function p.getTypeInfo(ctx)
	local entry = beltEntry(ctx.apiData, ctx.args)
		or locationVocabulary.beltTypeFromText(editorialClassification(ctx.args))
	return {
		name = classification(ctx.apiData, ctx.args) or 'Asteroid formation',
		category = entry and entry.category or 'Asteroidenformation',
	}
end

--- The classification linked to its index page. DISPLAY ONLY: getTypeInfo keeps
--- the plain form, because that one is stored; the display word localizes.
--- @param ctx EntityHookContext
--- @return string|nil
function p.getSubtitle(ctx)
	local text = classification(ctx.apiData, ctx.args)
	local entry = beltEntry(ctx.apiData, ctx.args) or locationVocabulary.beltTypeFromText(text)
	if entry and text then
		return locationVocabulary.starTypeLink(entry, msg(text))
	end
	return text
end

--- Only the system category: the type category is structural and comes from
--- getTypeInfo.
--- @param ctx EntityHookContext
--- @return string[]
function p.getCategories(ctx)
	local system = systemName(ctx.apiData, ctx.args)
	return system and { system .. '-System' } or {}
end

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

	local general = {}
	sectionBuilder.push(general, msg('Location'), locationChain(apiData, args))
	sectionBuilder.push(general, msg('Affiliation'), affiliationText(apiData, resolved))
	sectionBuilder.push(general, msg('Designation'), ed:value('designation'))
	sectionBuilder.push(general, msg('Distance'), distanceAu(apiData, args))

	-- The same rows a body gets, from the same block. A formation's readings are
	-- often all zero, which is the starmap's no-reading sentinel, so the section
	-- simply does not appear.
	local sensor = {}
	local readings = (celestial(apiData, args) or {}).sensor
	if type(readings) == 'table' then
		locationDisplay.appendSensorMeter(sensor, msg('Economy'), readings.economy)
		locationDisplay.appendSensorMeter(sensor, msg('Population'), readings.population)
		locationDisplay.appendSensorMeter(sensor, msg('Danger'), readings.danger)
	end

	local lore = {}
	sectionBuilder.push(lore, msg('Discovered in'), ed:value('discoveredin'))

	return sectionBuilder.build(
		sectionBuilder.section({ key = 'general', items = general }),
		sectionBuilder.section({ key = 'sensor', label = msg('Sensor readings'), items = sensor }),
		sectionBuilder.section({ key = 'lore', label = msg('Lore'), collapsible = true, items = lore })
	)
end

--- The system and parent store as wiki PAGE names, the vocabulary the other
--- Location leaves use, so queries resolve real pages.
--- @param ctx EntityHookContext
--- @return table<string, any>
function p.getStructuredData(ctx)
	local apiData, args, resolved = ctx.apiData, ctx.args, ctx.resolved
	-- raw: storedSystem hands the ORIGINAL value on and the store seam's
	-- single pass is the only canonicalization; a pre-shortened name would
	-- strip a second ' System' suffix or merge 'Foo (Alpha)' into 'Foo'
	-- before that pass sees it.
	local system = systemName(apiData, args, true)
	local _, parentTarget = parentAnchor(apiData, args)
	local readings = (celestial(apiData, args) or {}).sensor
	readings = type(readings) == 'table' and readings or {}
	local function rating(value)
		return locationDisplay.formatSensor(value) and tonumber(value) or nil
	end
	return {
		system = locationStarmap.storedSystem(system),
		affiliation = locationVocabulary.storedAffiliation(locationStarmap.starsystemOf(apiData), resolved),
		parent = parentTarget,
		classification = classification(apiData, args),
		designation = Editorial.view(resolved):value('designation'),
		population_rating = rating(readings.population),
		economy_rating = rating(readings.economy),
		danger_rating = rating(readings.danger),
	}
end

--- "<Asteroidengürtel> im Sternensystem Osiris"; a ring names the planet it
--- sits on, which is the fact that distinguishes it from every other ring.
--- The system labels through the shared row label (Starmap.systemLinkLabel,
--- fed the RAW value): the short form would strip a parenthetical that
--- distinguishes two systems and nest a linked spelling's wikitext. Bucket
--- keeps the legacy short form, so its wording is unchanged.
--- @param ctx EntityHookContext
--- @return string
function p.getShortDescription(ctx)
	local apiData, args = ctx.apiData, ctx.args
	local system = locationStarmap.systemLinkLabel(systemName(apiData, args, true))
	local head = classification(apiData, args) or 'Asteroid formation'
	local text = msg(head)
	if not system then
		return text .. msg(' in Star Citizen')
	end
	-- Keyed on the resolved entry, not `head`: an editor's |classification= is a
	-- display string and any variant wording would drop the parent clause.
	if beltEntry(apiData, args) == locationVocabulary.BELT_TYPES['Planetary Ring'] then
		local parentName = parentAnchor(apiData, args)
		if parentName then
			text = text .. msg(' of $1', { parentName })
		end
	end
	return text .. msg(' in the $1 system', { system })
end

--- @param ctx EntityHookContext
--- @return table[]
function p.getFooterButtons(ctx)
	return locationDisplay.starmapFooterButtons(resolvedStarmapCode(ctx.apiData, ctx.args))
end

--- @param ctx EntityHookContext
--- @return EntityItemData[]
function p.getMetadataItems(ctx)
	return locationDisplay.starmapMetadataItems(resolvedStarmapCode(ctx.apiData, ctx.args))
end

-- Test-only exports. Not part of the public API.
p._internal = {
	classification = classification,
	systemName = systemName,
	parentAnchor = parentAnchor,
	locationChain = locationChain,
	affiliationText = affiliationText,
	distanceAu = distanceAu,
	resolvedStarmapCode = resolvedStarmapCode,
}

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.