java.lang.Object
mekhq.campaign.mission.contract.utilities.MHQMorale

public class MHQMorale extends Object
Handles contract morale checks and morale/report calculation for campaign missions.

Provides utility methods to evaluate contract performance, calculate morale outcomes, and generate result reports based on recent scenarios and modifiers.

Since:
0.50.10
  • Field Details

    • RALLYING_TARGET_NUMBER

      public static final int RALLYING_TARGET_NUMBER
      See Also:
    • NO_CHANGE_TARGET_NUMBER

      public static final int NO_CHANGE_TARGET_NUMBER
      See Also:
    • WAVERING_TARGET_NUMBER

      public static final int WAVERING_TARGET_NUMBER
      See Also:
    • DECISIVE_MARGIN

      public static final int DECISIVE_MARGIN
      How many points one side must out-score the other by, over a month, for the result to be decisive (see MHQMorale.PerformanceTally.outcome()).
      See Also:
    • RAID_DIE_SIZE

      public static final int RAID_DIE_SIZE
      A garrison-type contract's enemy raids on a roll of 0 on a die of this size each month: a 1 in 4 chance.
      See Also:
    • SETBACK_VICTORY_POINT_SHARE

      public static final double SETBACK_VICTORY_POINT_SHARE
      The share of a contract's Contract Victory Point target a monthly setback costs (see applyMonthlySetback(mekhq.campaign.mission.contract.AbstractContract, boolean, boolean)).
      See Also:
    • LOW_AMMUNITION_MODIFIER

      public static final String LOW_AMMUNITION_MODIFIER
      The scenario modifier for an enemy fighting short of ammunition.
      See Also:
    • POOR_REPAIR_MODIFIER

      public static final String POOR_REPAIR_MODIFIER
      The scenario modifier for an enemy fighting with damage it has had no chance to repair.
      See Also:
  • Constructor Details

    • MHQMorale

      public MHQMorale()
  • Method Details

    • getFormattedTitle

      public static String getFormattedTitle()
      Returns the localized title used for the morale check report UI.

      The value is loaded from RESOURCE_BUNDLE under the key MHQMorale.check.title and is intended for use in dialogs or notifications that initiate a morale check.

      Returns:
      the localized morale check title string
      Since:
      0.50.10
    • performMoraleCheck

      public static String performMoraleCheck(LocalDate today, AbstractContract contract, int decisiveVictoryModifier, int victoryModifier, int decisiveDefeatModifier, int defeatModifier)
      Performs a morale check for the given contract, using the current date and modifier values.

      Evaluates all relevant scenarios within the past month, calculates performance and morale outcomes, and returns a formatted status report.

      Parameters:
      today - The current date of the check.
      contract - The contract to check morale for.
      decisiveVictoryModifier - The modifier to apply for decisive victories.
      victoryModifier - The modifier to apply for normal victories.
      decisiveDefeatModifier - The modifier to apply for decisive defeats.
      defeatModifier - The modifier to apply for normal defeats.
      Returns:
      A formatted string containing the morale check report.
      Since:
      0.50.10
    • getMoraleOutcome

      public static MHQMorale.MoraleOutcome getMoraleOutcome(AbstractContract contract, int roll)
      Determines the morale outcome based on the contract's current morale level and roll value. Updates the morale level in the contract if it changes.

      A lower roll is better for the OpFor.

      Parameters:
      contract - The contract to check and update morale for.
      roll - The result of the morale check roll.
      Returns:
      The resulting MoraleOutcome after the check.
      Since:
      0.50.10
    • getReliabilityModifier

      public static int getReliabilityModifier(int adjustedSkillLevel)
      Calculates the reliability modifier based on the provided skill value.

      This modifier influences how likely the opposing force is to suffer morale loss or reliability degradation during campaign events. Lower skills improve reliability for the player, while extremely high skills reduce it to reflect elite forces being more difficult to destabilize.

      • If skill <= GREEN.getAdjustedValue(), the modifier is +1, improving reliability for the player.
      • If skill >= ELITE.getAdjustedValue(), the modifier is -1, making reliability checks harder for the player.
      • All values between those thresholds return 0.
      Parameters:
      adjustedSkillLevel - the skill rating to evaluate, compared against the adjusted GREEN and ELITE thresholds
      Returns:
      +1 for low-skill forces (GREEN or worse), -1 for elite forces (ELITE or better), and 0 otherwise
      Since:
      0.50.10
    • getPerformanceTally

      public static MHQMorale.PerformanceTally getPerformanceTally(LocalDate today, AbstractContract contract)
      Tallies the victory and defeat points the contract's scenarios within the last month count for in the morale check.
      • Decisive victory: 2 victory points
      • Victory: 1 victory point
      • Pyrrhic victory: 1 victory point and 1 defeat point
      • Defeat or fleet in being: 1 defeat point
      • Decisive defeat or refused engagement: 2 defeat points
      Parameters:
      today - The current date for the evaluation.
      contract - The contract to evaluate scenarios for.
      Returns:
      The victory and defeat points over the last month.
      Since:
      0.51.01
    • isScenarioOutcomeAffectingMorale

      public static boolean isScenarioOutcomeAffectingMorale(ScenarioType stratConScenarioType, @Nullable AbstractContract contract)
      Decides whether a scenario's outcome shifts the enemy's morale directly (see processMoraleChangeFromScenario(mekhq.campaign.mission.contract.AbstractContract, mekhq.campaign.mission.scenarios.ScenarioStatus, mekhq.campaign.mission.scenarios.ScenarioType)). That is up to the scenario's type, with one exception: a riot moves morale only on a Riot Duty contract, where quelling riots is the work. Riots fought elsewhere - such as a scheduled parade disrupted on a Retainer contract - leave morale to the ordinary morale check.
      Parameters:
      stratConScenarioType - the scenario's type
      contract - the contract the scenario belongs to, or null if it has none
      Returns:
      true if the scenario's outcome shifts the enemy's morale
      Since:
      0.51.01
    • processMoraleChangeFromScenario

      public static void processMoraleChangeFromScenario(AbstractContract contract, ScenarioStatus scenarioStatus, ScenarioType stratConScenarioType)
      Applies a simplified morale check as the result of a scenario whose outcome moves the enemy's morale directly (see isScenarioOutcomeAffectingMorale(mekhq.campaign.mission.scenarios.ScenarioType, mekhq.campaign.mission.contract.AbstractContract)).

      This method does not use the full morale calculation. Instead, it forces a fixed roll based on the overall outcome of the scenario:

      Parameters:
      contract - the contract whose morale is being updated
      scenarioStatus - the outcome of the scenario used to determine the forced roll
      stratConScenarioType - the type of scenario.
      Since:
      0.50.10
    • getMoraleScenarioModifierKeys

      public static List<String> getMoraleScenarioModifierKeys(ContractMoraleLevel moraleLevel)
      Returns the scenario modifiers a beaten enemy brings into battle at its morale level: a ContractMoraleLevel.SCATTERED enemy fights short of ammunition and with unrepaired damage, and a ContractMoraleLevel.CRITICAL one with one of the two, picked at random. Any other enemy brings none.
      Parameters:
      moraleLevel - the enemy's morale level
      Returns:
      the keys of the scenario modifiers to add, in no particular order; empty if none
      Since:
      0.51.01
    • checkMorale

      @Nullable public static String checkMorale(Campaign campaign, AbstractContract contract, boolean showDialog)
      Runs the monthly morale update for a contract.

      On most contracts this is the morale check (see rollMorale(mekhq.campaign.Campaign, mekhq.campaign.mission.contract.AbstractContract)). A garrison-type contract follows a raid model instead (see ContractObjectiveType.isGarrisonType()): the enemy is only tested after a month in which it raided, so between raids its morale holds where it was, and each month there is then a 1 in 4 chance of a raid (see applyRaidRoll(mekhq.campaign.Campaign, mekhq.campaign.mission.contract.AbstractContract, boolean, boolean)). Throughout an emergency extension (see isInEmergencyExtension(mekhq.campaign.mission.contract.AbstractContract, java.time.LocalDate)) the enemy raids every month.

      After the check, an enemy left Dominating or Overwhelming costs the employer a setback (see applyMonthlySetback(mekhq.campaign.mission.contract.AbstractContract, boolean, boolean)). It is shown with the check, and returned for the daily report, so the caller can place it after its own report of the morale change.

      Parameters:
      campaign - the current campaign
      contract - the contract whose morale is updated
      showDialog - whether to show the player the morale check and any raid that begins
      Returns:
      the report of the month's setback, or null if there was none
    • isSetbackDue

      public static boolean isSetbackDue(AbstractContract contract)
      Whether the next monthly morale check would bring a setback (see applyMonthlySetback(mekhq.campaign.mission.contract.AbstractContract, boolean, boolean)) if the enemy's morale stays where it is: the enemy is Dominating or Overwhelming on a contract run with StratCon.
      Parameters:
      contract - the contract
      Returns:
      true if a setback is due
      Since:
      0.51.01
    • determineStartingMorale

      public static void determineStartingMorale(AbstractContract contract, Campaign campaign)
      Sets a newly generated contract's starting morale with a morale check. The enemy never starts ContractMoraleLevel.SCATTERED, and on a Relief Duty contract it starts a level higher. A garrison-type contract also starts peaceful (see ContractObjectiveType.isGarrisonType()), so its first raid roll comes at the start of the next month.
      Parameters:
      contract - the newly generated contract
      campaign - the current campaign