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: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
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.