Career Branches

Manages the career progression hierarchy: domains → branches → skills. Loads branch definitions from `/gameplay/domains/`, computes levels, XP, unlocks, and ordering.

Manages the career progression hierarchy: domains → branches → skills. Loads branch definitions from /gameplay/domains/, computes levels, XP, unlocks, and ordering.

Module Info

Field	Value
Path	`extensions/career/branches.lua`
Global	`career_branches`
Type	Extension

Internal State

Field	Type	Description
`M.oldAttributeNamesToNewNames`	table	Maps legacy branch names to new path-based names (e.g. `"drift"` → `"bmra-drift"`)
`M.newAttributeNamesToOldNames`	table	Reverse mapping of `oldAttributeNamesToNewNames`

Public API

Function	Signature	Description
`getBranches`	`()`	Returns all branches in a dict by ID. Lazy-loads and caches from `/gameplay/domains/`
`getBranchById`	`(id)`	Alias for `getBranchByPath(id)`
`getBranchByPath`	`(pathId)`	Looks up a branch by its path-based ID. Falls back to legacy name mapping
`getBranchByDomainBranchSkill`	`(domainId, branchId, skillId)`	Builds a path ID from domain/branch/skill and looks up
`getSortedBranches`	`()`	Returns branches sorted by hierarchical order
`getBranchLevel`	`(id)`	Returns current level for a branch from player attributes
`getBranchLevelByPath`	`(pathId)`	Same as getBranchLevel but takes a pathId
`getBranchXP`	`(id)`	Returns current XP value for a branch
`getXPNeededForLevel`	`(id, level)`	Returns requiredValue for a given level
`getBranchIcon`	`(id)`	Returns icon string for a branch
`getLevelLabel`	`(id, level)`	Returns display label for a branch level
`getLevelRewardMultiplier`	`(id)`	Returns reward multiplier for current level of a branch
`getBranchSimpleInfo`	`(id)`	Returns compact info: label, level, icon, progress, max
`calcBranchLevelFromValue`	`(val, id)`	Calculates level from XP value. Returns level, curLvlProgress, neededForNext, prevThreshold, nextThreshold
`orderAttributeKeysByBranchOrder`	`(list)`	Sorts attribute keys by branch display order
`orderBranchNamesKeysByBranchOrder`	`(list)`	Sorts branch name keys by order
`expandUnlocks`	`(skill, level, unlocks)`	Expands automatic unlock entries (e.g., mission counts)
`checkUnlocks`	`()`	Re-evaluates unlock conditions for all branches
`extractBranchPathIdFromFilePath`	`(filePath)`	Extracts a branch pathId from a file system path
`getOrder`	`(key)`	Returns sort order for an attribute key

Hooks

Hook	Description
`onSaveCurrentSaveSlot`	Saves branch unlock state to `branchUnlocks.json`
`onCareerModulesActivated`	Loads saved unlock data
`onGetUnlockFlagDefinitions`	Registers unlock flag definitions for all branch levels and certifications
`onPlayerAttributesChanged`	(registered but defined externally)

Branch Hierarchy

Domain (e.g. "apm")
  └─ Branch (e.g. "apm-motorsport")
       └─ Skill (e.g. "apm-motorsport-timeTrials")

Each branch has: isDomain, isBranch, isSkill, parentId, parentDomain, parentBranch.

Legacy Name Mapping

oldAttributeNamesToNewNames maps old names like "drift" → "bmra-drift", "delivery" → "logistics-delivery".

Usage Example

-- Get branch level
local level = career_branches.getBranchLevel("logistics-delivery")

-- Get XP progress
local xp = career_branches.getBranchXP("logistics-delivery")

-- Calculate level from arbitrary value
local lvl, progress, needed = career_branches.calcBranchLevelFromValue(250, "logistics-delivery")

-- Get sorted branches for UI display
for _, branch in ipairs(career_branches.getSortedBranches()) do
  print(branch.name, branch.id)
end

Additional Exports

Functions

Function	Description
`M.getOrder(key)`	No description available

Values/Properties

Export	Description
`M.calcBranchLevelFromValue`	Value: `calcBranchLevelFromValue`
`M.checkUnlocks`	Value: `checkUnlocks`
`M.expandUnlocks`	Value: `expandUnlocks`
`M.extractBranchPathIdFromFilePath`	Value: `extractBranchPathIdFromFilePath`
`M.getBranchByDomainBranchSkill`	Value: `getBranchByDomainBranchSkill`
`M.getBranchById`	Value: `getBranchById`
`M.getBranchByPath`	Value: `getBranchByPath`
`M.getBranchIcon`	Value: `getBranchIcon`
`M.getBranchLevel`	Value: `getBranchLevel`
`M.getBranchLevelByPath`	Value: `getBranchLevelByPath`
`M.getBranchSimpleInfo`	Value: `getBranchSimpleInfo`
`M.getBranchXP`	Value: `getBranchXP`
`M.getBranches`	Value: `getBranches`
`M.getLevelLabel`	Value: `getLevelLabel`
`M.getLevelRewardMultiplier`	Value: `getLevelRewardMultiplier`
`M.getSortedBranches`	Value: `getSortedBranches`
`M.getXPNeededForLevel`	Value: `getXPNeededForLevel`
`M.onCareerModulesActivated`	Value: `onCareerModulesActivated`
`M.onGetUnlockFlagDefinitions`	Value: `onGetUnlockFlagDefinitions`
`M.onPlayerAttributesChanged`	Value: `onPlayerAttributesChanged`
`M.onSaveCurrentSaveSlot`	Value: `onSaveCurrentSaveSlot`
`M.orderAttributeKeysByBranchOrder`	Value: `orderAttributeKeysByBranchOrder`
`M.orderBranchNamesKeysByBranchOrder`	Value: `orderBranchNamesKeysByBranchOrder`

Manages the career progression hierarchy: domains → branches → skills. Loads branch definitions from /gameplay/domains/, computes levels, XP, unlocks, and ordering.

Module Info

Field	Value
Path	`extensions/career/branches.lua`
Global	`career_branches`
Type	Extension

Internal State

Field	Type	Description
`M.oldAttributeNamesToNewNames`	table	Maps legacy branch names to new path-based names (e.g. `"drift"` → `"bmra-drift"`)
`M.newAttributeNamesToOldNames`	table	Reverse mapping of `oldAttributeNamesToNewNames`

Public API

Function	Signature	Description
`getBranches`	`()`	Returns all branches in a dict by ID. Lazy-loads and caches from `/gameplay/domains/`
`getBranchById`	`(id)`	Alias for `getBranchByPath(id)`
`getBranchByPath`	`(pathId)`	Looks up a branch by its path-based ID. Falls back to legacy name mapping
`getBranchByDomainBranchSkill`	`(domainId, branchId, skillId)`	Builds a path ID from domain/branch/skill and looks up
`getSortedBranches`	`()`	Returns branches sorted by hierarchical order
`getBranchLevel`	`(id)`	Returns current level for a branch from player attributes
`getBranchLevelByPath`	`(pathId)`	Same as getBranchLevel but takes a pathId
`getBranchXP`	`(id)`	Returns current XP value for a branch
`getXPNeededForLevel`	`(id, level)`	Returns requiredValue for a given level
`getBranchIcon`	`(id)`	Returns icon string for a branch
`getLevelLabel`	`(id, level)`	Returns display label for a branch level
`getLevelRewardMultiplier`	`(id)`	Returns reward multiplier for current level of a branch
`getBranchSimpleInfo`	`(id)`	Returns compact info: label, level, icon, progress, max
`calcBranchLevelFromValue`	`(val, id)`	Calculates level from XP value. Returns level, curLvlProgress, neededForNext, prevThreshold, nextThreshold
`orderAttributeKeysByBranchOrder`	`(list)`	Sorts attribute keys by branch display order
`orderBranchNamesKeysByBranchOrder`	`(list)`	Sorts branch name keys by order
`expandUnlocks`	`(skill, level, unlocks)`	Expands automatic unlock entries (e.g., mission counts)
`checkUnlocks`	`()`	Re-evaluates unlock conditions for all branches
`extractBranchPathIdFromFilePath`	`(filePath)`	Extracts a branch pathId from a file system path
`getOrder`	`(key)`	Returns sort order for an attribute key

Hooks

Hook	Description
`onSaveCurrentSaveSlot`	Saves branch unlock state to `branchUnlocks.json`
`onCareerModulesActivated`	Loads saved unlock data
`onGetUnlockFlagDefinitions`	Registers unlock flag definitions for all branch levels and certifications
`onPlayerAttributesChanged`	(registered but defined externally)

Branch Hierarchy

Domain (e.g. "apm")
  └─ Branch (e.g. "apm-motorsport")
       └─ Skill (e.g. "apm-motorsport-timeTrials")

Each branch has: isDomain, isBranch, isSkill, parentId, parentDomain, parentBranch.

Legacy Name Mapping

oldAttributeNamesToNewNames maps old names like "drift" → "bmra-drift", "delivery" → "logistics-delivery".

Usage Example

-- Get branch level
local level = career_branches.getBranchLevel("logistics-delivery")

-- Get XP progress
local xp = career_branches.getBranchXP("logistics-delivery")

-- Calculate level from arbitrary value
local lvl, progress, needed = career_branches.calcBranchLevelFromValue(250, "logistics-delivery")

-- Get sorted branches for UI display
for _, branch in ipairs(career_branches.getSortedBranches()) do
  print(branch.name, branch.id)
end

Additional Exports

Functions

Function	Description
`M.getOrder(key)`	No description available

Values/Properties

Export	Description
`M.calcBranchLevelFromValue`	Value: `calcBranchLevelFromValue`
`M.checkUnlocks`	Value: `checkUnlocks`
`M.expandUnlocks`	Value: `expandUnlocks`
`M.extractBranchPathIdFromFilePath`	Value: `extractBranchPathIdFromFilePath`
`M.getBranchByDomainBranchSkill`	Value: `getBranchByDomainBranchSkill`
`M.getBranchById`	Value: `getBranchById`
`M.getBranchByPath`	Value: `getBranchByPath`
`M.getBranchIcon`	Value: `getBranchIcon`
`M.getBranchLevel`	Value: `getBranchLevel`
`M.getBranchLevelByPath`	Value: `getBranchLevelByPath`
`M.getBranchSimpleInfo`	Value: `getBranchSimpleInfo`
`M.getBranchXP`	Value: `getBranchXP`
`M.getBranches`	Value: `getBranches`
`M.getLevelLabel`	Value: `getLevelLabel`
`M.getLevelRewardMultiplier`	Value: `getLevelRewardMultiplier`
`M.getSortedBranches`	Value: `getSortedBranches`
`M.getXPNeededForLevel`	Value: `getXPNeededForLevel`
`M.onCareerModulesActivated`	Value: `onCareerModulesActivated`
`M.onGetUnlockFlagDefinitions`	Value: `onGetUnlockFlagDefinitions`
`M.onPlayerAttributesChanged`	Value: `onPlayerAttributesChanged`
`M.onSaveCurrentSaveSlot`	Value: `onSaveCurrentSaveSlot`
`M.orderAttributeKeysByBranchOrder`	Value: `orderAttributeKeysByBranchOrder`
`M.orderBranchNamesKeysByBranchOrder`	Value: `orderBranchNamesKeysByBranchOrder`

Career Branches

Module Info

Internal State

Public API

Hooks

Branch Hierarchy

Legacy Name Mapping

Usage Example

See Also

Additional Exports

Functions

Values/Properties

On this page

Career Branches

Module Info

Internal State

Public API

Hooks

Branch Hierarchy

Legacy Name Mapping

Usage Example

See Also

Additional Exports

Functions

Values/Properties

On this page