Mission Screen UI

Reference for `gameplay_missions_missionScreen`, which formats mission data for the UI, handles starting options (repair costs, vehicle checks), and manages the mission details screen.

Reference for gameplay_missions_missionScreen, which formats mission data for the UI, handles starting options (repair costs, vehicle checks), and manages the mission details screen.

Module Exports (M)

Function	Signature	Description
`formatMission`	`(m)` → table	Formats a mission object for the UI with progress, stars, settings
`getMissionsAtCurrentLocationFormatted`	`()` → table	Returns all interactable missions at current marker, formatted
`getMissionScreenData`	`()` → table	Main entry: returns formatted data for the mission screen UI
`startMissionById`	`(id, userSettings, startingOptions)`	Starts a mission by ID
`stopMissionById`	`(id, force, abandonButtonPressed)`	Stops/abandons a mission by ID
`abandonCurrentMission`	`()`	Shortcut to abandon the active foreground mission
`changeUserSettings`	`(id, settings)`	Recalculates progress key for new user settings
`requestStartingOptionsForUserSettings`	`(id, userSettings)`	Async: calculates starting options (repair, fees)
`getActiveStarsForUserSettings`	`(id, userSettings)` → table	Returns which stars are active for given settings
`getRepairCostForStartingRepairType`	`(type)` → table	Returns repair cost: money (1000) or voucher (1)
`setPreselectedMissionId`	`(mId)`	Pre-selects a mission for the next screen open
`setPreselectedPage`	`(page)`	Pre-selects a page ("settings", etc.)
`activateSoundBlur`	`(active)`	Toggles audio blur effect
`activateSound`	`(soundLabel, active, pitch)`	Plays/stops money/xp/voucher counting sounds
`openAPMChallenges`	`(branch, skill)`	Opens mission menu filtered by branch/skill
`navigateToMission`	`(id)`	Opens big map and navigates to mission location
`getMissionTiles`	`(ids)` → table	Builds filterable/sortable grid of mission tiles
`isAnyMissionActive`	`()` → bool	Whether a foreground mission is running
`isMissionStartOrEndScreenActive`	`()` → bool	Checks if any mission start/end screen is active
`showMissionRules`	`(id?)`	Shows mission rules as popups
`startFromWithinMission`	`(id, settings)`	Starts a mission from within another (flattens settings)
`openVehicleSelectorForMissionBySetting`	`(mId, settingKey)`	Opens vehicle selector for a mission's custom vehicle setting

Debug / Testing

Function	Signature	Description
`enableDebug`	`(enable)`	Enables/disables ImGui debug window for mission screen history
`discoverLayouts`	`()`	Scans `/gameplay/testing/` for saved UI layouts

Hooks / Lifecycle

Function	Description
`onExtensionUnloaded`	Cleanup
`onClientEndMission`	Cleanup on level unload
`onBigMapActivated`	Handles delayed navigation to a mission on big map
`onMissionStartScreenReady`	Records UI layout history (last 20)
`onRequestMissionScreenData`	Serves test layout data in debug mode

Screen Data Contexts

getMissionScreenData() returns different data depending on state:

Context	When	Contents
`ongoingMission`	Mission is active	Single formatted mission + recovery options
`availableMissions`	At a mission marker	List of nearby missions + tiles + tutorial flag
`empty`	No missions available	Empty context
`M.abandonCurrentMission`	`()`	-
`M.activateSound`	`(soundLabel, active, pitch)`	-
`M.activateSoundBlur`	`(active)`	-
`M.changeUserSettings`	`(id, settings)`	-
`M.debugOnUpdate`	`(dt)`	-
`M.dependencies`	value	-
`M.discoverLayouts`	`()`	-
`M.enableDebug`	`(enable)`	-
`M.formatMission`	`(m)`	-
`M.getActiveStarsForUserSettings`	`(id, userSettings)`	-
`M.getMissionScreenData`	`()`	-
`M.getMissionTiles`	`(ids)`	-
`M.getMissionsAtCurrentLocationFormatted`	`()`	-
`M.getRepairCostForStartingRepairType`	`(type)`	-
`M.isAnyMissionActive`	`()`	-
`M.isMissionStartOrEndScreenActive`	`()`	-
`M.navigateToMission`	`(id)`	-
`M.onBigMapActivated`	`()`	-
`M.onClientEndMission`	`(levelPath)`	-
`M.onExtensionUnloaded`	`()`	-
`M.onMissionStartScreenReady`	`(uiLayout)`	-
`M.onRequestMissionScreenData`	`(mode)`	-
`M.openAPMChallenges`	`(branch, skill)`	-
`M.openVehicleSelectorForMissionBySetting`	`(mId, settingKey)`	-
`M.requestStartingOptionsForUserSettings`	`(id, userSettings)`	-
`M.savedLayouts`	value	-
`M.setPreselectedMissionId`	`(mId)`	-
`M.setPreselectedPage`	`(page)`	-
`M.showMissionRules`	`(id)`	-
`M.startFromWithinMission`	`(id, settings)`	-
`M.startMissionById`	`(id, userSettings, startingOptions)`	-
`M.stopMissionById`	`(id, force, abandonButtonPressed)`	-
`M.testLayout`	value	-
`M.uiLayoutHistory`	value	-

Starting Options Flow

requestStartingOptionsForUserSettings(id, userSettings):

Checks if player uses own vehicle, custom vehicle, or provided
Outside career → always defaultStartingOptions
During tutorial → always defaultStartingOptions
Checks entry fee affordability
If walking with own vehicle required → disabled
Checks vehicle certification (WIP)
Async checks repair status via career_modules_inventory.updatePartConditions
Returns repair options: no repair (disabled), voucher repair, money repair

How It Works

-- formatMission builds the full UI data:
local function formatMission(m)
  return {
    id = m.id, name = m.name, icon = m.iconFontIcon,
    description = m.description,
    userSettings = m:getUserSettingsData(),
    progress = m.saveData.progress,
    formattedProgress = gameplay_missions_progress.formatSaveDataForUi(m.id),
    additionalAttributes = { ... }, -- vehicle, difficulty, custom
    leaderboardKey = m.defaultLeaderboardKey or 'recent',
    gameContextUiButtons = m:getMissionScreenDataUiButtons(),
    -- + parentInfo for rally loops, leagues, etc.
  }
end

Key Behaviors

Repair costs: 1000 money or 1 voucher
User settings are cached on the mission as _lastUserSettingsOutsideOfMission
Star activity depends on whether user settings match defaults
Mission tiles support grouping by: all, missionType, branchSkill, difficulty, level, league
Sound objects for money/xp/voucher counting are lazily created

Module Exports (M)

Function	Signature	Description
`formatMission`	`(m)` → table	Formats a mission object for the UI with progress, stars, settings
`getMissionsAtCurrentLocationFormatted`	`()` → table	Returns all interactable missions at current marker, formatted
`getMissionScreenData`	`()` → table	Main entry: returns formatted data for the mission screen UI
`startMissionById`	`(id, userSettings, startingOptions)`	Starts a mission by ID
`stopMissionById`	`(id, force, abandonButtonPressed)`	Stops/abandons a mission by ID
`abandonCurrentMission`	`()`	Shortcut to abandon the active foreground mission
`changeUserSettings`	`(id, settings)`	Recalculates progress key for new user settings
`requestStartingOptionsForUserSettings`	`(id, userSettings)`	Async: calculates starting options (repair, fees)
`getActiveStarsForUserSettings`	`(id, userSettings)` → table	Returns which stars are active for given settings
`getRepairCostForStartingRepairType`	`(type)` → table	Returns repair cost: money (1000) or voucher (1)
`setPreselectedMissionId`	`(mId)`	Pre-selects a mission for the next screen open
`setPreselectedPage`	`(page)`	Pre-selects a page ("settings", etc.)
`activateSoundBlur`	`(active)`	Toggles audio blur effect
`activateSound`	`(soundLabel, active, pitch)`	Plays/stops money/xp/voucher counting sounds
`openAPMChallenges`	`(branch, skill)`	Opens mission menu filtered by branch/skill
`navigateToMission`	`(id)`	Opens big map and navigates to mission location
`getMissionTiles`	`(ids)` → table	Builds filterable/sortable grid of mission tiles
`isAnyMissionActive`	`()` → bool	Whether a foreground mission is running
`isMissionStartOrEndScreenActive`	`()` → bool	Checks if any mission start/end screen is active
`showMissionRules`	`(id?)`	Shows mission rules as popups
`startFromWithinMission`	`(id, settings)`	Starts a mission from within another (flattens settings)
`openVehicleSelectorForMissionBySetting`	`(mId, settingKey)`	Opens vehicle selector for a mission's custom vehicle setting

Debug / Testing

Function	Signature	Description
`enableDebug`	`(enable)`	Enables/disables ImGui debug window for mission screen history
`discoverLayouts`	`()`	Scans `/gameplay/testing/` for saved UI layouts

Hooks / Lifecycle

Function	Description
`onExtensionUnloaded`	Cleanup
`onClientEndMission`	Cleanup on level unload
`onBigMapActivated`	Handles delayed navigation to a mission on big map
`onMissionStartScreenReady`	Records UI layout history (last 20)
`onRequestMissionScreenData`	Serves test layout data in debug mode

Screen Data Contexts

getMissionScreenData() returns different data depending on state:

Context	When	Contents
`ongoingMission`	Mission is active	Single formatted mission + recovery options
`availableMissions`	At a mission marker	List of nearby missions + tiles + tutorial flag
`empty`	No missions available	Empty context
`M.abandonCurrentMission`	`()`	-
`M.activateSound`	`(soundLabel, active, pitch)`	-
`M.activateSoundBlur`	`(active)`	-
`M.changeUserSettings`	`(id, settings)`	-
`M.debugOnUpdate`	`(dt)`	-
`M.dependencies`	value	-
`M.discoverLayouts`	`()`	-
`M.enableDebug`	`(enable)`	-
`M.formatMission`	`(m)`	-
`M.getActiveStarsForUserSettings`	`(id, userSettings)`	-
`M.getMissionScreenData`	`()`	-
`M.getMissionTiles`	`(ids)`	-
`M.getMissionsAtCurrentLocationFormatted`	`()`	-
`M.getRepairCostForStartingRepairType`	`(type)`	-
`M.isAnyMissionActive`	`()`	-
`M.isMissionStartOrEndScreenActive`	`()`	-
`M.navigateToMission`	`(id)`	-
`M.onBigMapActivated`	`()`	-
`M.onClientEndMission`	`(levelPath)`	-
`M.onExtensionUnloaded`	`()`	-
`M.onMissionStartScreenReady`	`(uiLayout)`	-
`M.onRequestMissionScreenData`	`(mode)`	-
`M.openAPMChallenges`	`(branch, skill)`	-
`M.openVehicleSelectorForMissionBySetting`	`(mId, settingKey)`	-
`M.requestStartingOptionsForUserSettings`	`(id, userSettings)`	-
`M.savedLayouts`	value	-
`M.setPreselectedMissionId`	`(mId)`	-
`M.setPreselectedPage`	`(page)`	-
`M.showMissionRules`	`(id)`	-
`M.startFromWithinMission`	`(id, settings)`	-
`M.startMissionById`	`(id, userSettings, startingOptions)`	-
`M.stopMissionById`	`(id, force, abandonButtonPressed)`	-
`M.testLayout`	value	-
`M.uiLayoutHistory`	value	-

Starting Options Flow

requestStartingOptionsForUserSettings(id, userSettings):

Checks if player uses own vehicle, custom vehicle, or provided
Outside career → always defaultStartingOptions
During tutorial → always defaultStartingOptions
Checks entry fee affordability
If walking with own vehicle required → disabled
Checks vehicle certification (WIP)
Async checks repair status via career_modules_inventory.updatePartConditions
Returns repair options: no repair (disabled), voucher repair, money repair

How It Works

-- formatMission builds the full UI data:
local function formatMission(m)
  return {
    id = m.id, name = m.name, icon = m.iconFontIcon,
    description = m.description,
    userSettings = m:getUserSettingsData(),
    progress = m.saveData.progress,
    formattedProgress = gameplay_missions_progress.formatSaveDataForUi(m.id),
    additionalAttributes = { ... }, -- vehicle, difficulty, custom
    leaderboardKey = m.defaultLeaderboardKey or 'recent',
    gameContextUiButtons = m:getMissionScreenDataUiButtons(),
    -- + parentInfo for rally loops, leagues, etc.
  }
end

Key Behaviors

Repair costs: 1000 money or 1 voucher
User settings are cached on the mission as _lastUserSettingsOutsideOfMission
Star activity depends on whether user settings match defaults
Mission tiles support grouping by: all, missionType, branchSkill, difficulty, level, league
Sound objects for money/xp/voucher counting are lazily created

Mission Screen UI

Module Exports (M)

Debug / Testing

Hooks / Lifecycle

Screen Data Contexts

Starting Options Flow

How It Works

Key Behaviors

See Also

On this page

Mission Screen UI

Module Exports (M)

Debug / Testing

Hooks / Lifecycle

Screen Data Contexts

Starting Options Flow

How It Works

Key Behaviors

See Also

On this page