Modul:SystemMap/Data
Aus Star Citizen Wiki
Weitere Optionen
Die Dokumentation für dieses Modul kann unter Modul:SystemMap/Data/doc erstellt werden
require('strict')
--- @module SystemMap/Data
--- Loads Module:SystemMap/systems.json and turns a system name plus the current
--- page title into a render-ready model. Pure: no HTML building, no page-title
--- lookups, no frame access. Every branch here is covered by
--- Module:SystemMap/testcases, which is why the entry point keeps
--- parser-dependent work (page existence, categories) out of this file.
local p = {}
p._internal = {}
local DATA = mw.loadJsonData('Module:SystemMap/systems.json')
--- Planet subtype -> glyph kind. The kind becomes a `data-kind` attribute that
--- styles.css keys the disc gradient off. Anything absent degrades to 'unknown',
--- which renders a neutral disc rather than erroring — a new CIG planet type
--- should look plain, not break the page.
---
--- Keys are the SENTENCE-CASE strings systems.json stores, not upstream's Title
--- Case: 'Gas Giant' is stored as 'Gas giant'. The transform is not mechanical —
--- 'Super-Earth' and 'Super Jupiter' keep their proper nouns — so the generator
--- that writes systems.json carries the same explicit mapping. A disagreement
--- between the two is silent: the body just renders 'unknown'. Change them
--- together.
---
--- Twenty-two subtypes share eleven kinds. The grouping is deliberate: a 6-24px
--- disc cannot carry twenty-two distinguishable colours, so subtypes that would
--- read the same at that size share one. Existing kinds must keep their colours;
--- widening a bucket is safe only while no live body carries the added subtype.
--- @type table<string, string>
local SUBTYPE_KIND = {
['Super-Earth'] = 'super-earth',
-- Anything with a thick envelope. Rendered banded, so size differences within
-- the bucket read as banding rather than needing separate colours.
['Gas giant'] = 'gas-giant',
['Gas dwarf'] = 'gas-giant',
['Super Jupiter'] = 'gas-giant',
['Puffy planet'] = 'gas-giant',
['Ice giant'] = 'ice-giant',
['Smog planet'] = 'smog',
['Protoplanet'] = 'protoplanet',
-- Solid bodies differing mainly in what the rock is made of, which is not a
-- distinction a disc this size can carry.
['Terrestrial rocky'] = 'rocky',
['Iron planet'] = 'rocky',
['Carbon planet'] = 'rocky',
['Coreless planet'] = 'rocky',
['Desert planet'] = 'rocky',
['Chthonian planet'] = 'rocky',
-- Solid bodies whose surface IS the identifying fact, so each keeps a colour.
['Lava planet'] = 'lava',
['Ice planet'] = 'ice',
['Ocean planet'] = 'ocean',
['Dwarf planet'] = 'dwarf',
['Mesoplanet'] = 'dwarf',
-- Not a composition: origin (Artificial), orbit (Rogue) and state
-- (Evaporating). One instance each, and nothing a reader predicts a colour
-- for — so they share one that reads as "unusual" rather than as a material.
['Artificial'] = 'exotic',
['Rogue planet'] = 'exotic',
['Evaporating planet'] = 'exotic',
}
local UNKNOWN_KIND = 'unknown'
local MOON_KIND = 'moon'
local BELT_KIND = 'belt'
local RING_KIND = 'ring'
--- A belt renders as a fixed band, not a scaled disc: upstream reports its size
--- as 0/null, and a belt has no meaningful diameter to scale anyway.
local BELT_BAND = { width = 11, height = 26 }
--- A planetary ring gets the same treatment for the same reason, turned on its
--- side: it sits in the moon column, where the layout is a row, so the band lies
--- flat the way a ring reads edge-on. It is deliberately NOT a disc — a ring is
--- not a body, and drawing it as one would say it is a moon.
local RING_BAND = { width = 15, height = 5 }
--- The tiers whose glyph is a fixed band rather than a scaled disc.
--- @type table<string, { width: number, height: number }>
local BANDS = { belt = BELT_BAND, ring = RING_BAND }
--- Tiers that are drawn at a DIFFERENT tier's scale, and classified as one.
---
--- Every entry is a body whose PLACE on the rail and NATURE disagree, which is
--- the one thing a single tier cannot carry. The tier says where it is drawn;
--- this table says what it is measured and coloured as.
---
--- `companion` and `paired` are the second star of a binary, and exist as tiers
--- of their own only so that styles.css can lay them out differently —
--- `companion` sits in the column where a moon sits, `paired` shares the head
--- slot with the primary. Neither changes what the body IS: it is a star, it
--- takes a star's spectral glyph, and it keeps star-tier sizing even at 22.8px in
--- a row where moons are 6-14px. A companion drawn at moon scale would read as an
--- absurdly large moon, which is the opposite of what the data says.
---
--- `rail-moon` is the mirror case: a moon that holds a top-level slot on the
--- planet rail, because upstream parents it to the star and there is no planet
--- under which to nest it. Odin's Gainey is the only one in all 90 systems. It is
--- laid out as a rail column like its neighbours and measured and coloured as
--- the moon it is.
---
--- Without this the lookup would miss twice over, and both misses are silent:
--- glyphKind would fall through to the planet branch and return 'unknown', and
--- discSize would find no extents for the tier and return the tier maximum —
--- every companion at 30px, the size reserved for the largest star in the file.
--- @type table<string, string>
local SCALE_TIER = { companion = 'star', paired = 'star', ['rail-moon'] = 'moon' }
--- The `tier` marker a top-level body carries -> the tier it is RENDERED at.
--- Anything unmarked is a planet, which is what the absence of the key means.
--- The two differ only for a rail moon: the file says what the body is, and the
--- model says where it sits, because the layout of a rail column is nothing like
--- the layout of a moon in a moon column.
--- @type table<string, string>
local RAIL_TIER = { belt = 'belt', moon = 'rail-moon' }
--- Resolve the tier a body is measured and classified against.
--- @param tier string
--- @return string
local function scaleTier(tier)
return SCALE_TIER[tier] or tier
end
--- @class SystemMapBody
--- @field tier string 'star' | 'companion' | 'paired' | 'planet' | 'belt' | 'rail-moon' | 'moon' | 'ring'
--- @field page string Wiki page title, MediaWiki-normalised
--- @field label string Display name (may differ in case from `page`)
--- @field designation string|nil
--- @field subtype string|nil Display string; never parsed
--- @field kind string Glyph kind for `data-kind`
--- @field disc number Rendered disc diameter in px (log-scaled within its tier)
--- @field icon string|nil Wiki file name of the body's render, when one exists
--- @field iconRatio number|nil Width/height, set only when the icon is wider than
--- tall because the body has rings (Terminus, Pyro IV)
--- @field current boolean True when this body is the page being rendered
--- @field missing boolean Set later by Module:SystemMap; always false here
--- @field band { width: number, height: number }|nil Set for the tiers drawn as a
--- fixed band (belt, ring) instead of a scaled disc
--- @field moons SystemMapBody[]|nil Planets only; holds the planet's rings too
--- @class SystemMapModel
--- @field key string
--- @field page string
--- @field affiliation string|nil Lower-cased AFFILIATIONS code; absent when upstream files none
--- @field star SystemMapBody|nil Absent for a system upstream files no star for
--- @field companion SystemMapBody|nil Second star; absent for the 85 systems with one
--- @field companionShape string|nil 'nested' | 'paired'; set only alongside `companion`
--- @field bodies SystemMapBody[] Planets, belts and the one star-parented moon,
--- in orbital order
--- Resolve a user-supplied system name to a key in systems.json.
--- Accepts 'Stanton', 'stanton', 'STANTON', 'Stanton system', and surrounding
--- whitespace. Also accepts the name of the system's article where that differs
--- from the key, which is how {{System map|Kyuk'ya}} finds "Kyuk'ya (Indra)".
--- Returns nil for anything unrecognised.
--- @param input string|nil
--- @return string|nil
function p.resolveKey(input)
if type(input) ~= 'string' then
return nil
end
local name = mw.text.trim(input)
if name == '' then
return nil
end
-- Strip a trailing ' system' so {{System map|Stanton system}} works too. No
-- empty-result guard is needed: the pattern requires whitespace before
-- 'system', and `name` is already trimmed, so the bare input 'system'
-- does not match and the gsub can never return ''.
name = name:gsub('%s+[Ss][Yy][Ss][Tt][Ee][Mm]$', '')
local wanted = mw.ustring.lower(name)
for key in pairs(DATA.systems) do
if mw.ustring.lower(key) == wanted then
return key
end
end
-- Failing that, the name of the system's own ARTICLE.
--
-- The key is upstream's name, which is the identity a correction survives a
-- refetch by — but it is not always what the wiki calls the system, and it is
-- never what an editor types. Upstream still carries a Perry Line alias and
-- names one system "Kyuk'ya (Indra)"; the article is "Kyuk'ya system", every
-- other template on it is called {{... |Kyuk'ya}}, and without this
-- {{System map|Kyuk'ya}} would land in "System map with unknown system" and
-- render nothing at all.
--
-- Second pass rather than one merged loop, so an exact key match always wins:
-- if some system's article name ever collides with another system's key, the
-- key is the answer.
--
-- For the fourteen systems whose page is "<key> system" this is the same
-- comparison as above and changes nothing.
for key, system in pairs(DATA.systems) do
if type(system.page) == 'string' then
local article = system.page:gsub('%s+[Ss][Yy][Ss][Tt][Ee][Mm]$', '')
if mw.ustring.lower(article) == wanted then
return key
end
end
end
return nil
end
--- Classify a body into a glyph kind.
--- Stars key off spectral class, planets off subtype, moons off subtype when
--- they declare one (Pyro IV is a rocky planet sitting at the moon tier) and
--- fall back to the neutral moon disc otherwise.
---
--- Belts and rings short-circuit before any of that. Neither is a body: upstream
--- gives both a subtype that only restates the tier ('System Belt', 'Planetary
--- Ring'), and both are drawn as bands. A ring sits at the moon tier and must
--- never fall through to the moon disc, which would draw it as the thing it
--- orbits alongside.
---
--- `class` is normally a single spectral letter, giving star-o … star-m. The two
--- remnants upstream describes without one — White Dwarf-Degenerate-A and
--- Neutron — are stored with the WORD as their class ('degenerate', 'neutron'),
--- which falls out of the same concatenation as star-degenerate / star-neutron
--- and needs no branch here. Stars with no class at all (Variable, Subgiant, and
--- the fifteen upstream leaves unclassified) get the generic disc.
--- The two companion tiers are stars and are classified as such: a second star
--- keeps its spectral glyph whether it is nested under the primary or sharing
--- the head slot with it.
--- @param tier string 'star' | 'companion' | 'paired' | 'planet' | 'moon' | 'rail-moon' | 'belt' | 'ring'
--- @param subtype string|nil
--- @param class string|nil Spectral letter, or 'degenerate'/'neutron'; stars only
--- @return string
function p.glyphKind(tier, subtype, class)
if tier == 'belt' then
return BELT_KIND
end
if tier == 'ring' then
return RING_KIND
end
-- Both branches below ask what the body IS, so both ask it of the scale tier
-- rather than of the layout one. A moon on the planet rail carries no subtype
-- — only planets and stars have one — so a fallback keyed on the literal tier
-- would drop it through to the neutral 'unknown' disc, which is precisely the
-- claim the marker exists to prevent.
local scale = scaleTier(tier)
if scale == 'star' then
if type(class) == 'string' and class ~= '' then
return 'star-' .. mw.ustring.lower(class)
end
return 'star'
end
if type(subtype) == 'string' then
local kind = SUBTYPE_KIND[subtype]
if kind then
return kind
end
end
if scale == 'moon' then
return MOON_KIND
end
return UNKNOWN_KIND
end
--- Rendered disc diameter per tier, in px. The floor is not decoration: at true
--- scale the smallest planet computes to 0.05px, so something has to catch it.
--- @type table<string, { min: number, max: number }>
local DISC = {
star = { min = 22, max = 30 },
planet = { min = 6, max = 24 },
moon = { min = 6, max = 14 },
}
--- The tiers that scale. Belts are absent on purpose: they render as a fixed
--- band, carry no `km`, and have no meaningful diameter to scale.
--- @type string[]
local SCALED_TIERS = { 'star', 'planet', 'moon' }
--- Largest and smallest `km` per tier, measured from a document's own contents.
---
--- This is the FALLBACK. It is correct but not stable: the answer depends on
--- which systems happen to be in the file, so every rollout batch would resize
--- the discs on every page already published — adding Terra and Castra alone
--- moved Nyx's star from 30.0px to 24.3px. The generator therefore records the
--- extents against the whole upstream dataset and this only runs when that key
--- is missing, so an older or hand-trimmed file still renders.
---
--- Exported for the tests, which need to exercise both paths without a second
--- JSON page to load.
--- @param data table Anything shaped like systems.json
--- @return table<string, { min: number, max: number }>
function p.computeExtents(data)
local computed = {}
local function note(tier, km)
if type(km) ~= 'number' or km <= 0 then
return
end
local e = computed[tier]
if not e then
computed[tier] = { min = km, max = km }
return
end
if km < e.min then
e.min = km
end
if km > e.max then
e.max = km
end
end
for _, system in pairs(data.systems or {}) do
-- Both stars, and neither assumed present: `star` is absent for a system
-- upstream files none for, and `companion` for the 85 with one star. A
-- companion is measured at the star tier because that is what it is.
note('star', system.star and system.star.km)
note('star', system.companion and system.companion.km)
for _, body in ipairs(system.bodies or {}) do
-- Belts are skipped rather than assumed to carry no km: one given a
-- size by hand would otherwise widen the planet tier with a figure
-- nothing draws.
if body.tier ~= 'belt' then
note('planet', body.km)
if body.moons then
for _, moon in ipairs(body.moons) do
-- Rings are skipped for the same reason belts are: they
-- share the moons array but render as a fixed band, so a
-- km on one would stretch the moon scale by a figure
-- nothing draws.
if moon.tier ~= 'ring' then
note('moon', moon.km)
end
end
end
end
end
end
return computed
end
--- Resolve the disc scale for a document: what it records, else what it holds.
---
--- Merged per tier rather than all-or-nothing. A file recording only some tiers
--- would otherwise leave the rest with no extents at all, and `discSize` returns
--- the tier maximum when it has none — every planet on the page drawn at 24px.
--- @param data table
--- @return table<string, { min: number, max: number }>
function p.resolveExtents(data)
local recorded, found = {}, 0
if type(data.extents) == 'table' then
for _, tier in ipairs(SCALED_TIERS) do
local e = data.extents[tier]
if type(e) == 'table' and type(e.min) == 'number' and type(e.max) == 'number' then
recorded[tier] = { min = e.min, max = e.max }
found = found + 1
end
end
end
if found == #SCALED_TIERS then
return recorded
end
local resolved = p.computeExtents(data)
for tier, e in pairs(recorded) do
resolved[tier] = e
end
return resolved
end
--- @type table<string, { min: number, max: number }>|nil
local extents
--- @return table<string, { min: number, max: number }>
local function tierExtents()
if not extents then
extents = p.resolveExtents(DATA)
end
return extents
end
--- Map a body's diameter to a rendered disc size.
---
--- Logarithmic, anchored at both ends of its tier. Planets span 472:1, so a
--- linear map puts the smallest at 0.05px — invisible. Log spends the pixel
--- budget on the crowded small end, where most bodies actually are, while
--- keeping the ordering exact.
---
--- This is NOT proportional and must not be described as such: Pyro V is 6.6x
--- Hurston by diameter but renders about 1.3x. It is rank-preserving only.
---
--- The extents are now recorded in systems.json against all 90 upstream systems,
--- so a body outside them is a real possibility rather than a contradiction: an
--- upstream refetch can add a larger star before the file is regenerated. Such a
--- body lands on its tier's cap. It reads as "at least as big as anything else
--- here", which is true, and it cannot overflow the rail.
--- @param tier string
--- @param km number|nil
--- @return number px
function p.discSize(tier, km)
-- A companion is measured at the star tier, not at the tier of the row it
-- happens to sit in. Tyrol B renders at 22.8px in the moon column because it
-- is a star that small, not because the column is.
tier = scaleTier(tier)
local d = DISC[tier] or DISC.planet
-- No size upstream, so no claim: draw the tier's floor rather than its
-- ceiling. The ceiling was actively misleading — Lanisto is the one body in
-- the file with no `km`, and at the moon maximum it rendered 14.0px against
-- the 13.3px of Tyrol I, the planet it orbits. A moon drawn larger than its
-- own planet states something the data never said. The floor cannot exceed a
-- sized sibling, so at worst it understates.
if type(km) ~= 'number' or km <= 0 then
return d.min
end
local e = tierExtents()[tier]
-- A non-positive minimum would make math.log(e.min) infinite and the whole
-- fraction NaN, which none of the comparisons below would catch.
if not e or type(e.min) ~= 'number' or type(e.max) ~= 'number' or e.min <= 0 or e.max <= e.min then
return d.min
end
local lo, hi = math.log(e.min), math.log(e.max)
local px = d.min + (d.max - d.min) * (math.log(km) - lo) / (hi - lo)
-- Clamped in pixels rather than only in the fraction, so that whatever
-- arrives — a body outside the recorded extents, a corrupt bound, a NaN from
-- arithmetic that got past the guard above — leaves the rail intact. NaN
-- fails every comparison, so it is tested by inequality with itself.
if px ~= px then
-- Same reasoning as the unsized case above: an uncomputable size falls to
-- the floor, never the ceiling.
return d.min
elseif px < d.min then
return d.min
elseif px > d.max then
return d.max
end
return px
end
--- Copy one body out of the frozen JSON into a mutable model node.
--- @param source table
--- @param tier string
--- @param currentTitle string
--- @return SystemMapBody
local function toBody(source, tier, currentTitle)
return {
tier = tier,
page = source.page,
label = source.label,
designation = source.designation,
subtype = source.subtype,
kind = p.glyphKind(tier, source.subtype, source.class),
disc = p.discSize(tier, source.km),
icon = source.icon,
iconRatio = source.iconRatio,
band = BANDS[tier],
current = source.page == currentTitle,
missing = false,
}
end
--- The German wiki uses the capitalized system title for its redirects.
--- @param page string
--- @return string
local function systemPage(page)
return (page:gsub(' system$', ' System'))
end
--- Build the render model for one system.
--- @param input string|nil System name as written in the template call
--- @param currentTitle string Page title being rendered, MediaWiki-normalised
--- @return SystemMapModel|nil
function p.buildModel(input, currentTitle)
local key = p.resolveKey(input)
if not key then
return nil
end
currentTitle = currentTitle or ''
local system = DATA.systems[key]
local model = {
key = key,
page = systemPage(system.page),
affiliation = system.affiliation,
bodies = {},
}
-- The head of the rail is one star, two stars, or none.
--
-- `star` is absent for Min, which upstream files no star for and whose rail is
-- headed by a rogue gas giant carrying four moons — the picture Min's own
-- article describes. Nothing here may assume a head exists: the guard is what
-- let that system be rolled out as a data change rather than a code change.
if system.star then
model.star = toBody(system.star, 'star', currentTitle)
end
if system.companion then
-- Two shapes, because upstream describes two different objects. A
-- companion upstream parents to the primary really does orbit it, and is
-- nested where a moon nests; a pair upstream leaves unparented has no
-- centre, and both stars share the head slot.
--
-- `nested` is the default for an unrecognised value: it is the reading
-- that claims less. Saying "B orbits A" where the truth is a co-orbit
-- misplaces one body; saying "these co-orbit" where B really orbits A
-- misdescribes the whole system.
local paired = system.companionShape == 'paired'
model.companionShape = paired and 'paired' or 'nested'
model.companion = toBody(system.companion, paired and 'paired' or 'companion', currentTitle)
if paired then
-- Both stars are drawn as equals inside one rail slot, so the primary
-- takes the same tier as the companion. It keeps its own page, label
-- and glyph — only the layout is shared.
if model.star then
model.star.tier = 'paired'
end
elseif model.star then
-- The rail nests exactly one level and this is that level, so the
-- companion goes where a moon would go, reusing the moon list, the
-- connector line and the row layout wholesale. It is still a star:
-- `companion` is its tier, which is what keeps it at star size with a
-- star's glyph rather than reading as an impossibly large moon.
model.star.moons = { model.companion }
end
end
for _, source in ipairs(system.bodies) do
local tier = RAIL_TIER[source.tier] or 'planet'
local body = toBody(source, tier, currentTitle)
body.moons = {}
if source.moons then
for _, sourceMoon in ipairs(source.moons) do
-- A planet's rings share this array with its moons, because the
-- rail nests exactly one level and a ring wants that level. The
-- `tier: ring` marker is what keeps them apart from there on: it
-- picks the ring glyph, the band and the ring row.
local moonTier = sourceMoon.tier == 'ring' and 'ring' or 'moon'
body.moons[#body.moons + 1] = toBody(sourceMoon, moonTier, currentTitle)
end
end
model.bodies[#model.bodies + 1] = body
end
return model
end
--- page → where it sits, built once per parse.
--- @type table<string, table>|nil
local bodyIndex
--- Build the page-to-body index from a systems table. Exposed for testing.
--- @param systems table<string, table> Systems keyed by name, shaped like DATA.systems
--- @return table<string, table>
function p._internal.buildBodyIndex(systems)
local index = {}
for key, system in pairs(systems) do
local where = { key = key, page = systemPage(system.page), affiliation = system.affiliation }
if system.star and type(system.star.page) == 'string' and system.star.page ~= '' then
index[system.star.page] = { system = where, kind = 'star', entry = system.star }
end
if system.companion and type(system.companion.page) == 'string' and system.companion.page ~= '' then
index[system.companion.page] = { system = where, kind = 'star', entry = system.companion }
end
for _, body in ipairs(system.bodies) do
if body.tier ~= 'belt' and type(body.page) == 'string' and body.page ~= '' then
index[body.page] = { system = where, kind = body.tier == 'moon' and 'moon' or 'planet', entry = body }
end
for _, moon in ipairs(body.moons or {}) do
if moon.tier ~= 'ring' and type(moon.page) == 'string' and moon.page ~= '' then
index[moon.page] = { system = where, kind = 'moon', entry = moon, planet = body }
end
end
end
end
return index
end
--- Where a page sits in the system data: its system (key, page, affiliation
--- code), whether it is a star, planet or moon, its own entry, and a moon's
--- planet. nil for anything else (belts, rings, places, unknown titles).
--- @param page string|nil
--- @return table|nil
function p.findBody(page)
if type(page) ~= 'string' or page == '' then
return nil
end
bodyIndex = bodyIndex or p._internal.buildBodyIndex(DATA.systems)
return bodyIndex[page]
end
return p