Progress

Reference for `gameplay_missions_progress`, the system that tracks mission attempts, aggregates progress, manages leaderboards, computes star rewards, and formats progress data for the UI.

Reference for gameplay_missions_progress, the system that tracks mission attempts, aggregates progress, manages leaderboards, computes star rewards, and formats progress data for the UI.

Module Exports (M)

Core Progress

Function	Signature	Description
`aggregateAttempt`	`(id, attempt, progressKey)` → table	Aggregates an attempt into mission progress; returns unlock/reward changes
`newAttempt`	`(type, data)` → table	Creates an attempt: `{type, date, humanDate, data}`
`saveMissionSaveData`	`(id, dirtyDate)`	Persists mission save data to JSON
`loadMissionSaveData`	`(mission)` → table, bool	Loads save data from file or creates clean defaults
`ensureProgressExistsForKey`	`(mission, progressKey)`	Creates empty progress for a key if missing

Star & Reward Management

Function	Signature	Description
`reduceCareerRewardsForDefaultStars`	`(mission)`	Reduces money rewards to 10% after first unlock; removes vouchers
`setDynamicStarRewards`	`(mission, userSettings)`	Calls mission's `getDynamicStarReward` for each star
`addCareerRewardInfo`	`(starRewards, mission, attempt)` → table	Formats career rewards with progress bars and animations

UI Formatting

Function	Signature	Description
`formatSaveDataForUi`	`(id, progressKey, ...)` → table	Formats progress/leaderboards/stars for mission screen
`formatSaveDataForBigmap`	`(id)` → table	Simplified star summary for big map
`formatAttemptSimple`	`(attempt, mission)` → table	Formats a single attempt for display
`tryBuildContext`	`(label, data)` → table	Builds translation context from mission data

Save Slot Management

Function	Signature	Description
`setSaveSlot`	`(slotName)`	Changes the active progress save slot
`getSaveSlot`	`()` → name, path	Returns current save slot name and path
`setSavePath`	`(path?)`	Overrides the save path directly

Star & Progress Queries

Function	Signature	Description
`formatStars`	`(mission)` → table	Formats unlocked star data for UI
`formatAggregatesForMissionTypeWithProgKey`	-	Formats aggregate data across missions of same type
`getProgressAggregateCache`	-	Returns cached aggregate data
`getUnlockedStarCountsForMissionById`	`(id)` → total, default, bonus	Returns unlocked star counts
`startConditionMet`	-	Checks if a mission's start condition is met

Unlock Queries

Function	Signature	Description
`missionHasQuickTravelUnlocked`	`(missionId)` → bool	Always true outside career
`missionHasUserSettingsUnlocked`	`(missionId)` → bool	Always true outside career
`getLeaderboardChangeKeys`	`(missionId)` → table	Maps leaderboard keys to change detection keys

Batch Mode

Function	Signature	Description
`startBatchMode`	`()`	Disables unlock processing during batch operations
`endBatchMode`	`()`	Re-enables unlock processing
`getBatchMode`	`()` → bool	Returns current batch mode state

Testing & Debug

Function	Signature	Description
`generateAttempt`	`(id, addAttemptData)` → table	Generates a random attempt for a mission
`generateAttempts`	`(id, amount, dumpChange?)`	Generates multiple random attempts
`testHelper`	table	Utility functions: `randomBool`, `randomAttemptType`, `randomMedal`, `randomVehicle`, `randomNumber`
`exportAllProgressToCSV`	`()`	Stub for CSV export

Hooks / Lifecycle

Function	Description
`onExtensionLoaded`	Loads condition type modules from `progress/conditions/`

Auto-Aggregate Types

Configured per-mission in mission.autoAggregates:

Type	Description	Key Config
`simpleHighscore`	Tracks best value (ascending/descending) + leaderboard	`attemptKey`, `aggregateKey`, `sorting`
`simpleMedal`	Tracks best medal (gold > silver > bronze > wood)	`attemptKey`, `aggregateKey`
`simpleSum`	Accumulates totals	`attemptKey`, `aggregateKey`
`simpleComboCounter`	Tracks consecutive successes	`attemptKey`, `aggregateKeyCurrent/Max`
`successFailCounter`	Counts successes and failures separately	`attemptKey`, `aggregateKeySuccessCount/FailCount`

Attempt Types & Priority

Type	Priority	Description
`completed`	0	All default + bonus stars earned
`passed`	10	At least 1 default star earned
`attempted`	20	Tried but no stars
`abandoned`	50	Player quit
`failed`	100	Explicit failure

Save Data Structure

{
  version = 20,  -- current version
  progress = {
    default = {
      aggregate = { bestType, passed, completed, attemptCount, dnfCount, ... },
      attempts = { {type, date, data, unlockedStars, ...}, ... },
      leaderboards = { recent = {attemptIdx, ...}, ... }
    }
  },
  unlockedStars = { starKey = count, ... },
  quickTravelUnlocked = bool,
  userSettingsUnlocked = bool,
}

Career Reward Flow

-- During aggregateAttempt:
-- 1. Sanitize attempt (remove inactive stars, auto-calculate type)
-- 2. Aggregate generic progress (bestType, attemptCount, recent leaderboard)
-- 3. Set dynamic star rewards
-- 4. For each unlocked star: accumulate rewards, apply branch multiplier to money
-- 5. Add career reward info (progress bars, level-up animations)
-- 6. Apply rewards via career_modules_playerAttributes.addAttributes()
-- 7. Reduce future rewards (10% money, 0 vouchers after first unlock)
-- 8. Update mission unlocks, check for newly unlocked missions/leagues

Format Functions

Used in leaderboard/aggregate UI formatting:

Function	Input → Output
`distance`	meters → localized distance string
`detailledTime`	seconds → `M:SS:mmm`
`rallyTimeFormatter`	seconds → `H:MM:SS.T` (adaptive)
`rallyPenaltyFormatter`	seconds → `+Ns`
`timespan`	timestamp → timespan object
`stars`	unlockedStars → `DDBb` style star string
`M.addCareerRewardInfo`	`(starRewards, mission, attempt)`
`M.aggregateAttempt`	`(id, attempt, progressKey)`
`M.endBatchMode`	`()`
`M.ensureProgressExistsForKey`	`(missionInstance, progressKey)`
`M.exportAllProgressToCSV`	`()`
`M.formatAggregatesForMissionTypeWithProgKey`	value
`M.formatAttemptSimple`	`(attempt, mission)`
`M.formatSaveDataForBigmap`	`(id)`
`M.formatSaveDataForUi`	`(id, onlyKey, includeMostRecentAttempt, fillAttempts)`
`M.formatStars`	`(mission)`
`M.generateAttempt`	`(id, addAttemptData)`
`M.generateAttempts`	`(id, amount, dumpChange)`
`M.getBatchMode`	`()`
`M.getLeaderboardChangeKeys`	`(missionId)`
`M.getProgressAggregateCache`	value
`M.getSaveSlot`	`()`
`M.getSaveSlotVersion`	value
`M.getUnlockedStarCountsForMissionById`	`(id)`
`M.loadMissionSaveData`	`(mission)`
`M.missionHasQuickTravelUnlocked`	`(missionId)`
`M.missionHasUserSettingsUnlocked`	`(missionId)`
`M.newAttempt`	`(type, data)`
`M.onExtensionLoaded`	`()`
`M.reduceCareerRewardsForDefaultStars`	`(mission)`
`M.saveMissionSaveData`	`(id, dirtyDate)`
`M.setDynamicStarRewards`	`(mission, userSettings)`
`M.setSavePath`	`(path)`
`M.setSaveSlot`	`(slotName)`
`M.setSaveSlotVersion`	value
`M.startBatchMode`	`()`
`M.startConditionMet`	value
`M.testHelper`	value
`M.tryBuildContext`	`(label, data)`

Key Behaviors

Save path: settings/cloud/missionProgress/{slot}/{missionId}.json
Version upgrades iterate attempts through mission:updateAttempt() and re-aggregate
Batch mode suppresses unlock calculations during save data loading
Leaderboard default size: 5 entries
Money branch multiplier applied from career_branches.getLevelRewardMultiplier()
Progress bar animations handle multi-level-up scenarios with segmented animations

Module Exports (M)

Core Progress

Function	Signature	Description
`aggregateAttempt`	`(id, attempt, progressKey)` → table	Aggregates an attempt into mission progress; returns unlock/reward changes
`newAttempt`	`(type, data)` → table	Creates an attempt: `{type, date, humanDate, data}`
`saveMissionSaveData`	`(id, dirtyDate)`	Persists mission save data to JSON
`loadMissionSaveData`	`(mission)` → table, bool	Loads save data from file or creates clean defaults
`ensureProgressExistsForKey`	`(mission, progressKey)`	Creates empty progress for a key if missing

Star & Reward Management

Function	Signature	Description
`reduceCareerRewardsForDefaultStars`	`(mission)`	Reduces money rewards to 10% after first unlock; removes vouchers
`setDynamicStarRewards`	`(mission, userSettings)`	Calls mission's `getDynamicStarReward` for each star
`addCareerRewardInfo`	`(starRewards, mission, attempt)` → table	Formats career rewards with progress bars and animations

UI Formatting

Function	Signature	Description
`formatSaveDataForUi`	`(id, progressKey, ...)` → table	Formats progress/leaderboards/stars for mission screen
`formatSaveDataForBigmap`	`(id)` → table	Simplified star summary for big map
`formatAttemptSimple`	`(attempt, mission)` → table	Formats a single attempt for display
`tryBuildContext`	`(label, data)` → table	Builds translation context from mission data

Save Slot Management

Function	Signature	Description
`setSaveSlot`	`(slotName)`	Changes the active progress save slot
`getSaveSlot`	`()` → name, path	Returns current save slot name and path
`setSavePath`	`(path?)`	Overrides the save path directly

Star & Progress Queries

Function	Signature	Description
`formatStars`	`(mission)` → table	Formats unlocked star data for UI
`formatAggregatesForMissionTypeWithProgKey`	-	Formats aggregate data across missions of same type
`getProgressAggregateCache`	-	Returns cached aggregate data
`getUnlockedStarCountsForMissionById`	`(id)` → total, default, bonus	Returns unlocked star counts
`startConditionMet`	-	Checks if a mission's start condition is met

Unlock Queries

Function	Signature	Description
`missionHasQuickTravelUnlocked`	`(missionId)` → bool	Always true outside career
`missionHasUserSettingsUnlocked`	`(missionId)` → bool	Always true outside career
`getLeaderboardChangeKeys`	`(missionId)` → table	Maps leaderboard keys to change detection keys

Batch Mode

Function	Signature	Description
`startBatchMode`	`()`	Disables unlock processing during batch operations
`endBatchMode`	`()`	Re-enables unlock processing
`getBatchMode`	`()` → bool	Returns current batch mode state

Testing & Debug

Function	Signature	Description
`generateAttempt`	`(id, addAttemptData)` → table	Generates a random attempt for a mission
`generateAttempts`	`(id, amount, dumpChange?)`	Generates multiple random attempts
`testHelper`	table	Utility functions: `randomBool`, `randomAttemptType`, `randomMedal`, `randomVehicle`, `randomNumber`
`exportAllProgressToCSV`	`()`	Stub for CSV export

Hooks / Lifecycle

Function	Description
`onExtensionLoaded`	Loads condition type modules from `progress/conditions/`

Auto-Aggregate Types

Configured per-mission in mission.autoAggregates:

Type	Description	Key Config
`simpleHighscore`	Tracks best value (ascending/descending) + leaderboard	`attemptKey`, `aggregateKey`, `sorting`
`simpleMedal`	Tracks best medal (gold > silver > bronze > wood)	`attemptKey`, `aggregateKey`
`simpleSum`	Accumulates totals	`attemptKey`, `aggregateKey`
`simpleComboCounter`	Tracks consecutive successes	`attemptKey`, `aggregateKeyCurrent/Max`
`successFailCounter`	Counts successes and failures separately	`attemptKey`, `aggregateKeySuccessCount/FailCount`

Attempt Types & Priority

Type	Priority	Description
`completed`	0	All default + bonus stars earned
`passed`	10	At least 1 default star earned
`attempted`	20	Tried but no stars
`abandoned`	50	Player quit
`failed`	100	Explicit failure

Save Data Structure

{
  version = 20,  -- current version
  progress = {
    default = {
      aggregate = { bestType, passed, completed, attemptCount, dnfCount, ... },
      attempts = { {type, date, data, unlockedStars, ...}, ... },
      leaderboards = { recent = {attemptIdx, ...}, ... }
    }
  },
  unlockedStars = { starKey = count, ... },
  quickTravelUnlocked = bool,
  userSettingsUnlocked = bool,
}

Career Reward Flow

-- During aggregateAttempt:
-- 1. Sanitize attempt (remove inactive stars, auto-calculate type)
-- 2. Aggregate generic progress (bestType, attemptCount, recent leaderboard)
-- 3. Set dynamic star rewards
-- 4. For each unlocked star: accumulate rewards, apply branch multiplier to money
-- 5. Add career reward info (progress bars, level-up animations)
-- 6. Apply rewards via career_modules_playerAttributes.addAttributes()
-- 7. Reduce future rewards (10% money, 0 vouchers after first unlock)
-- 8. Update mission unlocks, check for newly unlocked missions/leagues

Format Functions

Used in leaderboard/aggregate UI formatting:

Function	Input → Output
`distance`	meters → localized distance string
`detailledTime`	seconds → `M:SS:mmm`
`rallyTimeFormatter`	seconds → `H:MM:SS.T` (adaptive)
`rallyPenaltyFormatter`	seconds → `+Ns`
`timespan`	timestamp → timespan object
`stars`	unlockedStars → `DDBb` style star string
`M.addCareerRewardInfo`	`(starRewards, mission, attempt)`
`M.aggregateAttempt`	`(id, attempt, progressKey)`
`M.endBatchMode`	`()`
`M.ensureProgressExistsForKey`	`(missionInstance, progressKey)`
`M.exportAllProgressToCSV`	`()`
`M.formatAggregatesForMissionTypeWithProgKey`	value
`M.formatAttemptSimple`	`(attempt, mission)`
`M.formatSaveDataForBigmap`	`(id)`
`M.formatSaveDataForUi`	`(id, onlyKey, includeMostRecentAttempt, fillAttempts)`
`M.formatStars`	`(mission)`
`M.generateAttempt`	`(id, addAttemptData)`
`M.generateAttempts`	`(id, amount, dumpChange)`
`M.getBatchMode`	`()`
`M.getLeaderboardChangeKeys`	`(missionId)`
`M.getProgressAggregateCache`	value
`M.getSaveSlot`	`()`
`M.getSaveSlotVersion`	value
`M.getUnlockedStarCountsForMissionById`	`(id)`
`M.loadMissionSaveData`	`(mission)`
`M.missionHasQuickTravelUnlocked`	`(missionId)`
`M.missionHasUserSettingsUnlocked`	`(missionId)`
`M.newAttempt`	`(type, data)`
`M.onExtensionLoaded`	`()`
`M.reduceCareerRewardsForDefaultStars`	`(mission)`
`M.saveMissionSaveData`	`(id, dirtyDate)`
`M.setDynamicStarRewards`	`(mission, userSettings)`
`M.setSavePath`	`(path)`
`M.setSaveSlot`	`(slotName)`
`M.setSaveSlotVersion`	value
`M.startBatchMode`	`()`
`M.startConditionMet`	value
`M.testHelper`	value
`M.tryBuildContext`	`(label, data)`

Key Behaviors

Save path: settings/cloud/missionProgress/{slot}/{missionId}.json
Version upgrades iterate attempts through mission:updateAttempt() and re-aggregate
Batch mode suppresses unlock calculations during save data loading
Leaderboard default size: 5 entries
Money branch multiplier applied from career_branches.getLevelRewardMultiplier()
Progress bar animations handle multi-level-up scenarios with segmented animations

Progress

Module Exports (M)

Core Progress

Star & Reward Management

UI Formatting

Save Slot Management

Star & Progress Queries

Unlock Queries

Batch Mode

Testing & Debug

Hooks / Lifecycle

Auto-Aggregate Types

Attempt Types & Priority

Save Data Structure

Career Reward Flow

Format Functions

Key Behaviors

See Also

On this page

Progress

Module Exports (M)

Core Progress

Star & Reward Management

UI Formatting

Save Slot Management

Star & Progress Queries

Unlock Queries

Batch Mode

Testing & Debug

Hooks / Lifecycle

Auto-Aggregate Types

Attempt Types & Priority

Save Data Structure

Career Reward Flow

Format Functions

Key Behaviors

See Also

On this page