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

require('strict')

--- @module Entity/Location/JumpPoint
--- Jump-point leaf of the Location kind: the in-game gate pages (one page per
--- gate, "Pyro - Nyx jump point"). Renders from the merged payload the kind
--- assembles: the location record at the top level (name, system, jurisdiction,
--- quantum_travel radii) plus the starmap celestial-object record at
--- apiData.celestialobject (attached by this leaf's enrich through
--- locationStarmap.attachCelestialObject from the editor's starmap code; may be
--- absent — every consumer nil-guards and degrades to location-only rows).
--- apiData.starsystem is never present here: the two starmap bridges are
--- mutually exclusive by construction.

local boolean = require('Module:Boolean')
local jurisdiction = require('Module:Entity/Location/Jurisdiction')
local locationDisplay = require('Module:Entity/Location/Display')
local locationStarmap = require('Module:Entity/Location/Starmap')
local msg = require('Module:Entity/Message').msg
local sectionBuilder = require('Module:Entity/SectionBuilder')
local Editorial = require('Module:Entity/Editorial')

local p = {}

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

--- Family token: dispatched by Location.resolveSubtype and named by a curated
--- |family=jumppoint on the starmap-only tunnels that have no location record.
p.family = 'jumppoint'

--- @param ctx EntityHookContext
--- @return table apiData
function p.enrich(ctx)
	return locationStarmap.attachCelestialObject(
		ctx.apiData,
		Editorial.rawArg(ctx.args, p.getEditorialManifest().starmapcode),
		require('Module:Entity/StructuredData').backend() == 'smw'
	)
end

--- The starmap celestial-object code (`code` is the legacy {{Astronomical
--- object}} arg name). No property key, no transform: this leaf surfaces it itself
--- (metadata row, Starmap button). enrich and the starmapCode accessor read
--- the RAW arg through Editorial.rawArg with this entry, so the alias order
--- is declared here once.
--- This leaf declares the starmapcode entry itself, so its own fragment is
--- the merged chain manifest's value for the field — reading its own entry
--- here (rather than the merged manifest) is correct only because of that.
--- @return table
function p.getEditorialManifest()
	return {
		starmapcode = { arg = { 'starmapcode', 'code' } },
	}
end

--- Jump-point gates file under their ENTRY system's category ("Pyro-System"),
--- not the destination's. The legacy pages' flat 'Astronomical
--- objects'/'Locations' memberships are deliberately NOT carried over: the
--- classification bucket (the Sprungpunkt structural category) covers that
--- taxonomy.
--- @param ctx EntityHookContext
--- @return string[]
function p.getCategories(ctx)
	local apiData = ctx.apiData
	local entry = locationStarmap.gateEntrySystem(apiData)
	if entry then
		return { entry .. '-System' }
	end
	return {}
end

--- Starmap jumppoints.size letter → label. The SIZE_LABELS value is the
--- STORED size (English machine token); SIZE_WORDS is the display word and
--- SIZE_ADJECTIVES the inflected short-description prefix. An unmapped letter
--- yields nil (no Size row, nothing stored) rather than leaking a raw code;
--- the qualified keys exist because the vehicle dataset already maps the bare
--- 'Medium' to a weight-class adjective.
local SIZE_LABELS = {
	S = 'Small',
	M = 'Medium',
	L = 'Large',
}

local SIZE_WORDS = {
	S = 'Small (jump point size)',
	M = 'Medium (jump point size)',
	L = 'Large (jump point size)',
}

local DIRECTION_LABELS = { B = 'Bidirektional', U = 'Unidirektional' }

local SIZE_ADJECTIVES = {
	S = 'Kleiner',
	M = 'Mittlerer',
	L = 'Großer',
}

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

--- The gate's two systems, read off the page's own canonical name. The title
--- IS the curated statement of which gate this is ("<Entry> - <Destination>
--- jump point") and it uses canonical system names by construction, whereas
--- the upstream celestial designation carries three naming forms that are not
--- wiki page names: alias parentheticals ("Kyuk'ya (Indra)"), the Vanduul
--- catalogue form (VS-9 "Vulture"), and — on one live tunnel — a bare legacy
--- name ("Th.us'ūng (Pallas) - Hadur", where Hadur is now Yā'mon). Each would
--- render a red link, file a wrong category and store a junk System value, and
--- the legacy-name case cannot be repaired by stripping decorations at all.
--- The designation stays as the fallback for a page whose name is not
--- gate-shaped.
--- @param args table|nil
--- @param raw boolean|nil return the sides verbatim for the storage path
---   (see Starmap.storedSystem)
--- @return string|nil entry
--- @return string|nil destination
local function titleSystems(args, raw)
	local name = args and type(args.name) == 'string' and args.name ~= '' and args.name or nil
	if not name then
		local title = mw.title.getCurrentTitle()
		name = title and title.text or nil
	end
	if type(name) ~= 'string' then
		return nil, nil
	end
	local base = mw.text.trim((name:gsub('%s+[Jj]ump%s+[Pp]oint$', '')))
	local a, b = base:match('^(.-)%s+%-%s+(.+)$')
	if not a then
		return nil, nil
	end
	if raw then
		return locationStarmap.rawSystem(a), locationStarmap.rawSystem(b)
	end
	return locationStarmap.systemShortName(a), locationStarmap.systemShortName(b)
end

--- The gate's entry system: the canonical name on the page first, then the
--- kind's record/designation chain.
--- @param apiData table
--- @param args table|nil
--- @param raw boolean|nil forwarded for the storage path (see
---   Starmap.storedSystem)
--- @return string|nil
local function entryFor(apiData, args, raw)
	local fromTitle = titleSystems(args, raw)
	return fromTitle or locationStarmap.gateEntrySystem(apiData, raw)
end

--- The system on the far side of the tunnel (short form), parsed from the
--- celestial designation "<A> - <B>". The destination is WHICHEVER side is not
--- the entry system - the designation's order is not assumed, so a record
--- that leads with the far side still resolves correctly. When the entry
--- system is unknown or matches neither side, nil: guessing a side could name
--- the gate's own system as its destination. The side match is backend-split:
--- Bucket keeps the English wiki's legacy compare, SMW matches the same
--- shaped canonical title the row links and the store seam stores.
--- @param apiData table
--- @param args table|nil
--- @param raw boolean|nil return the far side verbatim for the storage path
---   (see Starmap.storedSystem)
--- @return string|nil
local function destinationSystem(apiData, args, raw)
	local _, fromTitle = titleSystems(args, raw)
	if fromTitle then
		return fromTitle
	end
	local celestial = getCelestialObject(apiData)
	local designation = celestial and celestial.designation or nil
	if type(designation) ~= 'string' then
		return nil
	end
	local rawA, rawB = designation:match('^(.-)%s+%-%s+(.+)$')
	if not rawA then
		return nil
	end
	local farSide = function(side)
		return raw and side or locationStarmap.systemShortName(side)
	end
	local structuredData = require('Module:Entity/StructuredData')
	if structuredData.backend() ~= 'smw' then
		-- Bucket keeps the legacy compare, display and storage alike: the
		-- trimmed designation side against the short entry. The English wiki's
		-- rows and stored values were built by it, and the canonical-title
		-- fold below also resolves spellings this compare deliberately leaves
		-- unmatched (a suffixed or paren-carrying side).
		local entry = entryFor(apiData, args)
		if not entry then
			return nil
		end
		local sideA, sideB = mw.text.trim(rawA), mw.text.trim(rawB)
		if sideA:lower() == entry:lower() then
			return farSide(rawB)
		end
		if sideB:lower() == entry:lower() then
			return farSide(rawA)
		end
		return nil
	end
	-- SMW matches entry and sides as the SAME shaped canonical title the row
	-- links and the store seam stores (Starmap.systemLinkTarget's
	-- composition: the writer's PAGE pass shapedPageTitle, then the canonical
	-- fold): a short-name compare strips the parentheticals that distinguish
	-- 'Foo (Alpha)' from 'Foo (Beta)', so both sides of such a designation
	-- would match and the entry system would come back as its own destination,
	-- and a shaped spelling of one system ('Stanton_System') would miss its
	-- plainly spelled side. The canonical fold still merges a side's alias
	-- parenthetical ("Th.us'ūng (Pallas)") with the entry's bare spelling.
	local canonicalTitle = function(value)
		return locationStarmap.systemPageTitle(structuredData.shapedPageTitle(value))
	end
	local entryTitle = canonicalTitle(entryFor(apiData, args, true))
	if not entryTitle then
		return nil
	end
	local titleA, titleB = canonicalTitle(rawA), canonicalTitle(rawB)
	if titleA and titleA:lower() == entryTitle:lower() then
		return farSide(rawB)
	end
	if titleB and titleB:lower() == entryTitle:lower() then
		return farSide(rawA)
	end
	return nil
end

--- @param celestial table|nil
--- @return string|nil
local function destinationGate(celestial)
	local tunnel = celestial and celestial.jumppoints
	if type(tunnel) ~= 'table' or type(tunnel.entry) ~= 'table' or type(tunnel.exit) ~= 'table' then
		return nil
	end
	local code, entry, exit = celestial.code, tunnel.entry.code, tunnel.exit.code
	if type(code) ~= 'string' or code == '' or type(entry) ~= 'string' or type(exit) ~= 'string' then
		return nil
	end
	local other
	if code == entry and code ~= exit then
		other = exit
	elseif code == exit and code ~= entry then
		other = entry
	end
	if not other or other == '' then
		return nil
	end
	local ok, rows = pcall(require('Module:Entity/Store').query, {
		kind = 'Location',
		filters = { 'Category:Sprungpunkt', { 'Starmap code', '=', other } },
		columns = { { builtin = 'page_name', as = 'page' } },
		limit = 2,
	})
	if not ok or type(rows) ~= 'table' or #rows ~= 1 or type(rows[1]) ~= 'table' then
		return nil
	end
	local page = rows[1].page
	return type(page) == 'string' and page ~= '' and page or nil
end

--- @param celestial table|nil
--- @return string|nil
local function directionLabel(celestial)
	local jump = celestial and type(celestial.jumppoints) == 'table' and celestial.jumppoints or nil
	local direction = jump and jump.direction
	if type(direction) ~= 'string' or mw.text.trim(direction) == '' then
		return nil
	end
	return DIRECTION_LABELS[string.upper(direction)] or direction
end

--- @param celestial table|nil
--- @return string|nil the starmap size letter ('S' | 'M' | 'L')
local function sizeLetter(celestial)
	local jumppoints = celestial and type(celestial.jumppoints) == 'table' and celestial.jumppoints or nil
	local size = jumppoints and jumppoints.size or nil
	return size ~= nil and size or nil
end

--- The stored size token for the letter, or nil when the tables do not map it.
--- @param celestial table|nil
--- @return string|nil 'Small' | 'Medium' | 'Large'
local function sizeLabel(celestial)
	local letter = sizeLetter(celestial)
	return letter ~= nil and SIZE_LABELS[letter] or nil
end

--- The localized Size-row word for the same letter.
--- @param celestial table|nil
--- @return string|nil
local function sizeWord(celestial)
	local letter = sizeLetter(celestial)
	return letter ~= nil and msg(SIZE_WORDS[letter]) or nil
end

--- The gate's parent anchor (display name + link-candidate title). A Star
--- parent's candidate is its `(star)` page ("Pyro (star)"); anything else —
--- the gateway stations — gets the wiki's system-disambiguated title
--- ("Pyro Gateway (Stanton)": two stations share the name "Pyro Gateway", one
--- per side, so the bare title is a disambiguation page and must not be
--- linked). The candidate may be nil (no entry system to disambiguate with)
--- while the name still displays as plain text.
--- @param apiData table
--- @return string|nil name
--- @return string|nil candidate
local function parentLinkCandidate(apiData, args)
	local parent = type(apiData.parent) == 'table' and apiData.parent or nil
	local name = parent and type(parent.name) == 'string' and parent.name ~= '' and parent.name or nil
	if not name then
		return nil, nil
	end
	if parent.type_name == 'Star' then
		return name, name .. ' (star)'
	end
	local entry = entryFor(apiData, args)
	return name, entry and (name .. ' (' .. entry .. ')') or nil
end

--- Display wrapper over parentLinkCandidate: link the candidate when its page
--- exists (one existence check per render), else plain text. Kept thin and
--- untested offline — the runner's title shim cannot answer `exists`; the
--- candidate selection above carries the logic and the tests.
--- @param apiData table
--- @return string|nil
local function parentDisplay(apiData, args)
	local name, candidate = parentLinkCandidate(apiData, args)
	if not name then
		return nil
	end
	local title = candidate and mw.title.new(candidate) or nil
	if title and title.exists then
		return '[[' .. candidate .. '|' .. name .. ']]'
	end
	return name
end

--- The Starmap row: whether the gate appears in the in-game starmap app, as
--- the standard tri-state boolean icon (Mission's Shareable row is the
--- precedent). The value is `hide_in_starmap` NEGATED — the icon answers "is
--- it on the starmap?", so a shown gate gets the green check. An absent field
--- yields no row, never the Unknown icon: that would claim uncertainty about
--- data the record simply does not carry.
--- @param apiData table
--- @return string|nil
local function starmapVisibility(apiData)
	if type(apiData.hide_in_starmap) ~= 'boolean' then
		return nil
	end
	return boolean.render(not apiData.hide_in_starmap)
end

--- The ARK starmap code (the `?location=` key), read through the manifest entry
--- enrich fetches with, so a page whose fetch soft-failed still gets its button
--- and metadata row from the arg that would have keyed 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

--- @param ctx EntityHookContext
--- @return { name: string, category: string }
function p.getTypeInfo(ctx)
	return {
		name = 'Jump point',
		category = 'Sprungpunkt',
	}
end

--- The infobox link for one gate side: the shared display accessor
--- (Starmap.systemLinkTarget), fed the RAW side - the canonical stored title
--- under SMW (a shortened target would collapse 'Foo (Alpha)' and 'Foo
--- (Beta)' onto one page), the legacy short-form page name under Bucket.
--- @param raw string|nil
--- @return string|nil
local function sideLink(raw)
	local target = locationStarmap.systemLinkTarget(raw)
	return target and '[[' .. target .. ']]' or nil
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 celestial = getCelestialObject(apiData)

	local general = {}
	-- Both rows link the RAW side's canonical stored title under SMW
	-- (sideLink): the short forms feed the short description, but a shortened
	-- link target would collapse 'Foo (Alpha)' and 'Foo (Beta)' onto one page.
	sectionBuilder.push(general, msg('System'), sideLink(entryFor(apiData, args, true)))
	sectionBuilder.push(general, msg('Destination'), sideLink(destinationSystem(apiData, args, true)))
	sectionBuilder.push(general, msg('Parent'), parentDisplay(apiData, args))
	sectionBuilder.push(general, msg('Size'), sizeWord(celestial))
	local jurisdictionName = type(apiData.jurisdiction) == 'table' and apiData.jurisdiction.name or nil
	sectionBuilder.push(general, msg('Jurisdiction'), jurisdiction.display(jurisdictionName))

	local travel = {}
	local radii = type(apiData.quantum_travel) == 'table' and apiData.quantum_travel or {}
	sectionBuilder.push(travel, msg('Arrival radius'), radii.arrival_radius_formatted)
	sectionBuilder.push(travel, msg('Obstruction radius'), radii.obstruction_radius_formatted)
	sectionBuilder.push(travel, msg('Starmap'), starmapVisibility(apiData))

	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 }),
		-- collapsible with no `collapsed` renders open (StarSystem's Lore
		-- idiom): the radii are the gate's headline in-game numbers.
		sectionBuilder.section({
			key = 'travel',
			label = msg('Travel (jump point)'),
			collapsible = true,
			items = travel,
		}),
		sectionBuilder.section({ key = 'lore', label = msg('Lore'), collapsible = true, items = lore })
	)
end

--- Store what the infobox displays: the mapped size label and the two system
--- values through Starmap.storedSystem (the ORIGINAL values verbatim under
--- SMW, canonicalized once at the store seam; the page names under Bucket),
--- fetched raw so a meaningful parenthetical survives to that pass and
--- [[System::...]] queries resolve the actual wiki pages.
--- discoveredin/discoveredby storage is owned by the editorial manifest -
--- not double-stored here.
--- @param ctx EntityHookContext
--- @return table<string, any>
function p.getStructuredData(ctx)
	local apiData, args = ctx.apiData, ctx.args
	local entry = entryFor(apiData, args, true)
	local destination = destinationSystem(apiData, args, true)
	local structured = {
		jump_point_size = sizeLabel(getCelestialObject(apiData)),
		system = locationStarmap.storedSystem(entry),
		destination_system = locationStarmap.storedSystem(destination),
	}
	if require('Module:Entity/StructuredData').backend() == 'smw' then
		local celestial = getCelestialObject(apiData)
		structured.jump_point_direction = directionLabel(celestial)
		structured.starmap_code = starmapCode(apiData, args)
		structured.destination_gate = destinationGate(celestial)
	end
	return structured
end

--- Gate-directional, no trailing period: "Mittlerer Sprungpunkt von Pyro
--- nach Nyx" (the adjective agrees with the masculine noun). No size ->
--- "Sprungpunkt von Pyro nach Nyx"; either system unresolvable -> the
--- catch-all (a bare "Mittlerer Sprungpunkt" names no route and reads wrong).
--- The two systems label through the shared row label (Starmap.
--- systemLinkLabel, fed the RAW side): the short forms would strip the
--- parentheticals that distinguish 'Foo (Alpha)' from 'Foo (Beta)' and the
--- route would read "von Foo nach Foo". Bucket keeps the legacy short
--- forms, so its wording is unchanged.
--- @param ctx EntityHookContext
--- @return string
function p.getShortDescription(ctx)
	local apiData, args = ctx.apiData, ctx.args
	local entry = locationStarmap.systemLinkLabel(entryFor(apiData, args, true))
	local destination = locationStarmap.systemLinkLabel(destinationSystem(apiData, args, true))
	if entry and destination then
		local letter = sizeLetter(getCelestialObject(apiData))
		local adjective = letter and SIZE_ADJECTIVES[letter]
		local head = adjective and (adjective .. ' ' .. msg('Jump point')) or msg('Jump point')
		return head .. msg(' from $1 to $2', { entry, destination })
	end
	return msg('A jump point in Star Citizen')
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 = {
	destinationSystem = destinationSystem,
	sizeLabel = sizeLabel,
	parentLinkCandidate = parentLinkCandidate,
	parentDisplay = parentDisplay,
	starmapVisibility = starmapVisibility,
	starmapCode = starmapCode,
	SIZE_LABELS = SIZE_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.