Modul:Entity/Location/Star
Aus Star Citizen Wiki
Weitere Optionen
< Modul:Entity | Location
Die Dokumentation für dieses Modul kann unter Modul:Entity/Location/Star/doc erstellt werden
require('strict')
--- @module Entity/Location/Star
--- Star leaf of the Location kind: one page per star ("Stanton (star)",
--- "Goss A"), plus the single black hole the starmap serves in the same shape
--- (Tamsa). Renders from the merged payload the kind assembles: the location
--- record at the top level, which only three stars have — Stanton, Pyro and
--- Nyx are the only ones in the game — plus the starmap celestial-object
--- record at apiData.celestialobject, attached by this leaf's enrich through
--- locationStarmap.attachCelestialObject from the editor's starmap code. Every
--- other star page is record-less and renders from the starmap alone, so every
--- consumer nil-guards and degrades to what it has.
local Editorial = require('Module:Entity/Editorial')
local format = require('Module:Entity/Format')
local jurisdiction = require('Module:Entity/Location/Jurisdiction')
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: dispatched by Location.resolveSubtype for the three in-game
--- Star records, and named by a curated |family=star on every other star page.
p.family = 'star'
--- @param ctx EntityHookContext
--- @return table apiData
function p.enrich(ctx)
return locationStarmap.attachCelestialObject(
ctx.apiData,
Editorial.rawArg(ctx.args, p.getEditorialManifest().starmapcode)
)
end
--- `code`, `classification` and `system` are the legacy {{Astronomical object}}
--- arg names. `radius` is the only source of a radius for the stars whose
--- starmap size is a placeholder (see radiusKm); `satellites` is the star's own
--- planet count, which no endpoint this leaf fetches carries, and for a binary
--- it is per-star rather than per-system. No entry takes a property key —
--- getStructuredData stores these itself, so display and store cannot diverge.
--- This leaf declares all five itself, which is the only reason reading its own
--- fragment below (rather than the merged chain manifest) is correct.
--- @return table
function p.getEditorialManifest()
return {
starmapcode = { arg = { 'starmapcode', 'code' } },
classification = { arg = 'classification' },
radius = { arg = 'radius', transform = 'number' },
satellites = { arg = 'satellites', transform = 'number' },
system = { arg = 'system' },
}
end
--- @param apiData table
--- @return table|nil
local function getCelestialObject(apiData)
return type(apiData.celestialobject) == 'table' and apiData.celestialobject or nil
end
--- Read from the RAW arg, not the editorial view: getTypeInfo runs before
--- editorial resolution in Data.get. The field is a plain passthrough, so the
--- raw arg IS the resolved value and every consumer can share this accessor.
--- @param args table|nil
--- @return string|nil
local function editorialClassification(args)
return Editorial.rawArg(args, p.getEditorialManifest().classification)
end
--- The vocabulary entry for the record's own sub_type, or nil. The single
--- accessor the subtitle and the category both resolve through, so the link
--- target and the filed category can never name different classes.
--- @param apiData table
--- @return table|nil
local function starTypeEntry(apiData)
local celestial = getCelestialObject(apiData)
return celestial and locationVocabulary.starTypeEntry(celestial.sub_type) or nil
end
--- Editorial text wins: Pyro is a flare star by lore, which the starmap does
--- not carry. nil where nothing classes the object, so callers fall back to the
--- generic rather than inventing a class.
---
--- DELINKED here, once, because three of the four consumers cannot take markup:
--- getTypeInfo's name is stored as the indexed `Subject type` and is the
--- short-description fallback, and getSubtitle wraps the text in a link, so an
--- editor's own `[[…]]` would nest and render as literal brackets.
--- @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 = starTypeEntry(apiData)
if entry then
return entry.classification
end
local celestial = getCelestialObject(apiData)
return celestial and celestial.type == 'BLACKHOLE' and 'Black hole' or nil
end
--- The starmap serves star sizes in KILOMETRES, but eighteen unsurveyed stars
--- carry a bare `1` and Stanton a `1.2`, placeholders in no unit at all.
--- Nothing stellar is smaller than a neutron star's ~10 km, so the cut sits
--- below that: it drops all nineteen and keeps Banshee's real 13.91 km.
local MIN_PLAUSIBLE_RADIUS_KM = 5
--- The IAU nominal solar radius, for the R☉ comparison.
local SOLAR_RADIUS_KM = 695700
--- The location record's own `size` is never read: Pyro and Nyx share one
--- byte-identical 57,072,000 m value, so it is a placeholder in the game data
--- too, and only Stanton's happens to be real.
--- @param apiData table
--- @param resolved table|nil
--- @return number|nil
local function radiusKm(apiData, resolved)
local editorialValue = tonumber(Editorial.view(resolved):value('radius'))
if editorialValue and editorialValue > 0 then
return editorialValue
end
local celestial = getCelestialObject(apiData)
local size = celestial and tonumber(celestial.size) or nil
if not size or size < MIN_PLAUSIBLE_RADIUS_KM then
return nil
end
-- A class that declares a ceiling is one whose size the physics pins down
-- (see STAR_TYPES.maxRadiusKm): above it the figure is not a measurement.
local entry = starTypeEntry(apiData)
if entry and entry.maxRadiusKm and size > entry.maxRadiusKm then
return nil
end
return size
end
--- The R☉ test is on the ROUNDED figure, not the raw ratio: a white dwarf at
--- 0.0090 prints a useful '0.01 R☉', while a neutron star's 0.00002 would print
--- a meaningless 0.00 and is dropped. Sub-100 km radii keep their decimals for
--- the same reason.
--- @param km number|nil
--- @return string|nil
local function radiusDisplay(km)
if not km then
return nil
end
local text = (
km < 100 and locationDisplay.decimal(string.format('%.2f', km)) or format.formatNum(math.floor(km + 0.5))
) .. ' km'
local solar = string.format('%.2f', km / SOLAR_RADIUS_KM)
if solar ~= '0.00' then
text = text .. ' (' .. locationDisplay.decimal(solar) .. ' R☉)'
end
return text
end
--- Never the page title: "Terra Nova" is the star of Terra and "Goss A" one of
--- two suns, so a title-derived name is wrong for exactly the pages a fallback
--- would exist to rescue. The editorial arg is LAST, for the stars the starmap
--- does not list at all (78 Leonis), where nothing else can name the system.
--- @param apiData table
--- @param args table|nil
--- @param raw boolean|nil return the source value verbatim for the storage
--- path and the system row label (see Starmap.storedSystem)
--- @return string|nil
local function systemName(apiData, args, raw)
local fromRecord = locationStarmap.entrySystem(apiData, raw)
if fromRecord then
return fromRecord
end
local celestial = getCelestialObject(apiData)
local starsystem = celestial and type(celestial.starsystem) == 'table' and celestial.starsystem or nil
if starsystem then
if raw then
return locationStarmap.rawSystem(starsystem.name)
end
return locationStarmap.systemShortName(starsystem.name)
end
local arg = Editorial.rawArg(args, p.getEditorialManifest().system)
if raw then
return locationStarmap.rawSystem(arg)
end
return locationStarmap.systemShortName(arg)
end
--- The ARK starmap code, from the record or the arg that would have fetched it.
--- @param apiData table
--- @param args table|nil
--- @return string|nil
local function starmapCode(apiData, args)
return locationStarmap.celestialStarmapCode(apiData, Editorial.rawArg(args, p.getEditorialManifest().starmapcode))
end
--- `name` must stay PLAIN: Entity stores it as `Subject type` and falls back to
--- it for the short description. The linked form is getSubtitle's. No row
--- repeats it, since it is the subtitle. Tamsa files under Stars too; the
--- spectral type is a facet on top (getCategories).
--- @param ctx EntityHookContext
--- @return { name: string, category: string }
function p.getTypeInfo(ctx)
return {
name = classification(ctx.apiData, ctx.args) or 'Star',
category = 'Stern',
}
end
--- The two classifications that come from no sub_type at all: a star the ARK
--- never classed, and a black hole it gave none. Each carries BOTH its index
--- page and its category, because the pair has to move together — a subtitle
--- reading "Black hole" filed under Unknown spectral type stars would break the
--- invariant starTypeEntry exists to hold.
local GENERIC = {
['Star'] = { page = 'Stern mit unbekanntem Spektraltyp', category = 'Stern mit unbekanntem Spektraltyp' },
['Black hole'] = { page = 'Schwarzes Loch', category = 'Schwarzes Loch' },
}
--- The classification linked to its index page. DISPLAY ONLY — getTypeInfo
--- keeps the plain form because that one is stored. An editor's wording is kept
--- as the display while the target comes from the record's class, so Pyro reads
--- "flare star" and still points at the K-type index. Nothing resolvable leaves
--- it plain rather than inventing a target.
--- @param ctx EntityHookContext
--- @return string|nil
function p.getSubtitle(ctx)
local english = classification(ctx.apiData, ctx.args) or 'Star'
local entry = starTypeEntry(ctx.apiData) or locationVocabulary.starTypeFromText(editorialClassification(ctx.args))
local text = msg(english)
if entry then
return locationVocabulary.starTypeLink(entry, text)
end
local generic = GENERIC[english]
return generic and locationVocabulary.starTypeLink(generic, text) or text
end
--- Two categories, one browse and one functional.
---
--- The spectral facet comes from the record FIRST, so an editor who elaborates
--- the wording still files under the class the data gives. Editorial text is
--- matched back only where the record classes nothing, the record-less pages'
--- one route to a category; a star nothing classes is genuinely of unknown
--- spectral type, itself a live category.
--- @param ctx EntityHookContext
--- @return string[]
function p.getCategories(ctx)
local entry = starTypeEntry(ctx.apiData) or locationVocabulary.starTypeFromText(editorialClassification(ctx.args))
local generic = not entry and GENERIC[classification(ctx.apiData, ctx.args) or 'Star'] or nil
local categories =
{ entry and entry.category or (generic and generic.category) or 'Stern mit unbekanntem Spektraltyp' }
local system = systemName(ctx.apiData, ctx.args)
if system then
categories[#categories + 1] = system .. '-System'
end
return categories
end
--- @param ctx EntityHookContext
--- @return EntitySectionEntry[]
function p.getSections(ctx)
local apiData, resolved = ctx.apiData, ctx.resolved
local ed = Editorial.view(resolved)
local general = {}
-- The row links the canonical stored title (systemLinkTarget), fetched
-- raw: a short-form target would collapse 'Foo (Alpha)' onto 'Foo' and an
-- alias onto a red-link spelling, pages the stored value never names.
local systemTarget = locationStarmap.systemLinkTarget(systemName(apiData, ctx.args, true))
sectionBuilder.push(general, msg('System'), systemTarget and ('[[' .. systemTarget .. ']]'))
sectionBuilder.push(general, msg('Radius'), radiusDisplay(radiusKm(apiData, resolved)))
-- formatNum, not the raw value: InfoboxLua's item schema requires STRING
-- content, and validateAndConstruct drops a number without a word.
sectionBuilder.push(general, msg('Satellites'), format.formatNum(ed:value('satellites')))
local jurisdictionName = type(apiData.jurisdiction) == 'table' and apiData.jurisdiction.name or nil
sectionBuilder.push(general, msg('Jurisdiction'), jurisdiction.display(jurisdictionName))
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 = 'lore', label = msg('Lore'), collapsible = true, items = lore })
)
end
--- The system stores through Starmap.storedSystem (the ORIGINAL value
--- verbatim under SMW, canonicalized once at the store seam; the backend's
--- page name under Bucket), queries then resolve real pages. A
--- star's satellites reuse Planet count rather than adding a column for the
--- same fact; note that every live binary carries the SYSTEM total on both
--- stars (Tyrol A and B both 7), so a star row's planet_count is not a per-star
--- figure and an aggregate query must filter by subject_type. discoveredin/discoveredby belong to the kind's
--- manifest, not here.
--- @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 class = classification(apiData, args)
return {
system = locationStarmap.storedSystem(system),
classification = class and Editorial.toStoredValue(class) or nil,
radius = radiusKm(apiData, resolved),
planet_count = tonumber(Editorial.view(resolved):value('satellites')),
}
end
--- "<K-Hauptreihenstern> im Sternensystem Stanton". No system resolves -> the
--- catch-all, since a bare classification names no place and reads like a
--- definition. An editor's own wording passes through untranslated, as it must.
--- 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 system = locationStarmap.systemLinkLabel(systemName(ctx.apiData, ctx.args, true))
if not system then
return msg('A star in Star Citizen')
end
return msg(classification(ctx.apiData, ctx.args) or 'Star') .. msg(' in the $1 system', { system })
end
--- RSI Starmap as a footer action button, from the shared code accessor.
--- @param ctx EntityHookContext
--- @return table[]
function p.getFooterButtons(ctx)
return locationDisplay.starmapFooterButtons(starmapCode(ctx.apiData, ctx.args))
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, ctx.args))
end
-- Test-only exports. Not part of the public API.
p._internal = {
classification = classification,
starTypeEntry = starTypeEntry,
radiusKm = radiusKm,
radiusDisplay = radiusDisplay,
systemName = systemName,
starmapCode = starmapCode,
MIN_PLAUSIBLE_RADIUS_KM = MIN_PLAUSIBLE_RADIUS_KM,
SOLAR_RADIUS_KM = SOLAR_RADIUS_KM,
}
return p