Modul:Entity/Location/JumpPoint
Aus Star Citizen Wiki
Weitere Optionen
< Modul:Entity | Location
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