feat: adds CONVOY behavior setting preset and flag to ignore damage output on pathing

[Scoppio]

What is it about?

Adds CONVOY behavior setting preset, a behavior controlling flag to ignore damage output (damage that would be caused by this unit onto enemies) when calculating pathing utility score was added, also adds special case where unit will give priority to face towards its destination when fleeing but only if it has the flag ignore damage output enabled.

What it does?

This small feature adds a simple behavior control toggle

Anything else?

Alot of Javadoc was added on BasicPathRanker to better explain what is happening.

Issues:

This PR potentially resolves the following RFE's

• Closes Teach Princess to handle certain units as non-combat regardless of weapons #4308
• Closes RFE: Add Convoy Bot #3250
• Closes [RFE] Have a princess setting for "Convoys" where they only walk or try to stay away from the enemy instead of sprinting their doom. #6260

[Copilot]

Pull Request Overview

This PR adds a new CONVOY behavior preset along with a flag to ignore damage output, affecting both path ranking and behavior settings. Key changes include:

• Introduction of new clamp methods (clamp01 and clampUlp1) in MathUtility.
• Updates to BotConfigDialog and various bot components (UtilityPathRanker, BasicPathRanker, BehaviorSettings, etc.) to incorporate the ignoreDamageOutput flag.
• Enhanced Javadoc documentation and minor logging improvements.

Reviewed Changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
megamek/src/megamek/codeUtilities/MathUtility.java	Added helper clamp methods with accompanying Javadoc
megamek/src/megamek/client/ui/dialogs/BotConfigDialog.java	Added UI component and action handling for ignoreDamageOutput flag
megamek/src/megamek/client/bot/princess/UtilityPathRanker.java	Updated path ranking logic to account for ignoreDamageOutput flag
megamek/src/megamek/client/bot/princess/Princess.java	Logging improvements with parameterized messages
megamek/src/megamek/client/bot/princess/PathRanker.java	Expanded Javadoc and minor logic updates for path ranking
megamek/src/megamek/client/bot/princess/BehaviorSettingsFactory.java	Added new CONVOY preset and null-checks for behavior presets
megamek/src/megamek/client/bot/princess/BehaviorSettings.java	Added new field and XML serialization for ignoreDamageOutput flag
megamek/src/megamek/client/bot/princess/BasicPathRanker.java	Enhanced documentation and integrated ignoreDamageOutput flag in scoring

Files not reviewed (1)

• megamek/i18n/megamek/client/messages.properties: Language not supported

Comments suppressed due to low confidence (1)

megamek/src/megamek/client/bot/princess/UtilityPathRanker.java:150

• [nitpick] When the ignoreDamageOutput flag is enabled, both physicalDamage and firingDamage are set to 0. Please confirm that disabling both damage types is the intended behavior in all scenarios.

if (getOwner().getBehaviorSettings().isIgnoreDamageOutput()) {

[codecov]

Codecov Report

Attention: Patch coverage is 29.22849% with 954 lines in your changes missing coverage. Please review.

Project coverage is 30.50%. Comparing base (d6c2db5) to head (ba6b1b9).
Report is 16 commits behind head on master.

Files with missing lines	Patch %	Lines
...src/megamek/client/ui/dialogs/BotConfigDialog.java	0.00%	604 Missing ⚠️
.../megamek/client/bot/princess/BehaviorSettings.java	46.20%	210 Missing and 38 partials ⚠️
...k/client/bot/princess/BehaviorSettingsFactory.java	70.86%	67 Missing and 7 partials ⚠️
...megamek/client/bot/princess/UtilityPathRanker.java	0.00%	19 Missing ⚠️
...c/megamek/client/bot/princess/BasicPathRanker.java	14.28%	4 Missing and 2 partials ⚠️
megamek/src/megamek/codeUtilities/MathUtility.java	0.00%	2 Missing ⚠️
...amek/src/megamek/client/bot/princess/Princess.java	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #6944      +/-   ##
============================================
+ Coverage     30.48%   30.50%   +0.02%     
- Complexity    16321    16431     +110     
============================================
  Files          2896     2934      +38     
  Lines        284892   285202     +310     
  Branches      49588    49594       +6     
============================================
+ Hits          86838    87013     +175     
- Misses       191971   192105     +134     
- Partials       6083     6084       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[SuperStucco]

The clamp01() method indicates "The value if it is inside the range given by the limits (inclusive)", but it only has one input - the value to be clamped. It should include either values to clamp between as arguments, or the JavaDoc updated to show that it is clamping between 0.0 and 1.0 (or whatever values are hard coded).

[rjhancock]

Im glad to see more documentation get added in.

That being said, the nitpick CoPilot picked out is valid. :)

[Scoppio]

The clamp01() method indicates "The value if it is inside the range given by the limits (inclusive)", but it only has one input - the value to be clamped. It should include either values to clamp between as arguments, or the JavaDoc updated to show that it is clamping between 0.0 and 1.0 (or whatever values are hard coded).

Well... it is the CLAMP 0 1 method....