Added the Automatic Tracking of Award Eligibility and Additional Award Enhancements

[IllianiCBT]

Introduction

autoAwards adds to mhq a new way to track Award eligibility. It does this by separating Awards into types and by utilizing the previously unused fields qty, item, size, and range. It also introduces a couple of functions to help read the TOE, something that is essential to autoAwards, but will likely be useful in other parts of the suite.

This PR covers a lot, but I will do my best to cover everything.

Note: this PR is a WIP, so some functionality may change before launch. As additions or edits are made, these will be reflected in the text.

Terminology: Mission is synonymous with Contract and AtBContract, any described functionality applies to all three. Contracts are synonymous with AtBContracts, any described functionality applies to both.. If AtBContract is specified, the functionality only applies to AtBContracts. autoAwards is the internal name for the system that automatically tracks Awards eligibility and is referred to as such throughout this PR.

Testing: this is the largest & most complicated coding project I have done to date. While I am proud of what I've accomplished, it is important to recognize my limited experience. The functionality implemented by autoAwards should be thoroughly tested before launch.

Trigger

autoAwards is triggered by the conclusion of Missions, Scenarios, and manually through the toolbar.

Documentation

A documentation pdf has been provided which replaces the previous readme. I have also moved the old Awards documentation & spreadsheet into the archive folder as functionally it is replaced by autoAwards.

Award Types

autoAwards currently offers support for 12 types of Award, with room for others to be added down the line. In each case the item field tells autoAwards what type of Award it is looking at. Awards are grouped according to their type, which ensures that we're not parsing the same Awards multiple times unnecessarily.

As mentioned above, autoAwards uses the previously unused qty, item, size, and range fields already included in the Award dataset.

Contract Awards (Contracts only)

These awards are issued at the conclusion of a contract if the contract type matches the type listed in the Award, or if the contract's duration matches qty. If the Mission is not a Contract or AtBContract, these Awards are skipped.

qty is used only with the duration sub-type. If range is set to months, then autoAwards checks to see whether the true duration (start date to current date) of the contract (in months) equals or exceeds this value.
size is ignored, with no use-case intended at this time.
range tells autoAward what type of Contract needs to be completed. This can be either the literal contract type, or raid or duty which will be true if the Contract was a raid or duty contract, respectively. Alternatively, this value can be set to 'months' to tell autoAwards to check the Contract's true duration, instead.

Faction Hunter Awards (AtBContracts Only)

These awards are issued for completing contracts against specific enemy factions. If the Mission is not an AtBContract (and AtB is enabled), these Awards are skipped.

qty is currently ignored, although I can see me adding support to allow users to specify that their Award is issued only after completing x number of Contracts against y enemy.
size is ignored, with no use-case intended at this time.
range tells autoAwards what type of enemy needs to be faced. This can either be the Faction name (for single Factions), or a super-faction, such as 'Clans' which will return true if the faction has the Clan tag. Support for checking for multiple Factions is included. So users can specify Award eligibility if any one of a list of Factions is faced.

Limitations: Garrison Contracts will trigger multiple different type of Faction opponent. autoAwards does not, currently, know how to handle that and will ignore all Factions except the last Faction faced within the Contract.

Injury Awards (Missions)

Injury Awards are issued at the end of a Scenario when a person has suffered sufficient Hits during that Scenario.

qty is how many Hits must be suffered, during the Scenario, to qualify for the Award
size is ignored, with no use-case intended at this time.
range is ignored, with no use-case intended at this time.

Limitations: autoAwards has no way to tell how a Hit was sustained, so it's entirely possible for personnel to qualify for Injury Awards by falling over a few times.

Kill Awards (Missions)

These Awards are awarded for killing x number of opposing units at the individual+ level.

qty tells autoAwards how many units need to be killed
size states what organizational tier the kills are counted at. This ranges from Individual, for personal kills, all the way up to Army. Technically, it wouldn't be difficult to add support for TOEs larger than Army, but I didn't think it was worth considering at this time. Capping at Army should cover 99% of use cases.
range tells autoAwards whether to count kills accumulated across lifetime, the last mission, or across a scenario. Scenario kills are handled separately.

This functionality is achieved through limited TOE reading (see later).

Rank Awards

These Awards are given out for reaching specific Ranks.

qty tells autoAwards what rank numeric needs to be reached to be eligible for the Award. Rank Numerics are a pre-existing measurement that ranges from 0-40 and directly correlates to Rank row number. E8, for example, is rank numeric 8; while WO1 is rank numeric 21, and so on.
size is ignored, with no use-case intended at this time.
range determines whether the award should consider eligibility based on inclusive Rank, in which case the personnel just needs to met or beat the rank numeric. Or, whether it should be based on exclusive Rank, where NCOs are not eligible for WO or Officer Awards; and visa versa.

Scenario Awards

These Awards are issued for completing x number of scenarios

qty tells autoAwards how many scenarios need to be completed.
size is ignored, with no use-case intended at this time.
range is ignored, with no use-case intended at this time.

Scenario Kill Awards

These Awards are issued at the end of a Scenario if the personnel has achieved sufficient kills. These are functionally identical to normal Kill Awards.

Due to being issued after a Scenario (as opposed to after a Mission) additional code support needed to be provided, chiefly streaming a lot of the functionality from AutoAwardsController that isn't needed for Scenario Kill Awards.

Skill Awards

These Awards are given out for reaching specific Skill Levels.

qty tells autoAwards the required Skill Level.
size is ignored, with no use-case intended at this time.
range is the skill, or list of skills, needed for Award eligibility. If multiple Skills are listed all must meet the required Skill Level for the personnel to be eligible for the Award. Super-skills are included. These include groups of Skills where the personnel is only required to met the requirement for one of the listed Skills. An example of this is the 'Tech' super-skill, which tells autoAwards that the person needs to met the required Skill Level for any one of the Tech Skills. Super-Skills and single Skills can be combined, in which case autoAwards will check to see if the personnel meets the requirement for any one Skill covered by the Super-Skill and also any listed individual Skills.

Theatre of War Awards (Contracts only, extra functionality for AtBContracts)

These Awards are issued for accepting Contracts from belligerents during a time of war. If the Mission is not a Contract or AtBContract, these Awards are skipped.

qty is ignored, with no use-case intended at this time.
size is used to dictate the period of war. For example <size>3025,3026</size> would tell autoAwards that the Award is only valid during those years. It is possible to include the same year twice, such as <size>3025,3025</size> which tells autoAwards the Award is only valid during that year.
range lists the Belligerents. For Awards intended for use with Contracts only one Faction needs to be listed. In which case autoAwards will check this Faction matches the Employer. However, if the Mission was an AtBContract (and AtB is enabled) additional Belligerents can be included so long as they are followed with (1) or (2) to dictate which side each Faction falls on. So long as the employer Faction matches one of the Factions on side 1 or 2; and the enemy Faction matches a Faction on the opposing side, the employee may be eligible for this Award. Like Faction Hunter Awards super-factions are supported. Awards with multiple Factions are skipped unless the Mission is an AtBContract and AtB is enabled.

As this is a pretty complicated Award Type, I've included an example below

Time Awards

These Awards are issued for serving in a unit for a specific duration. Such as 'serve x years without disciplinary action'.

The existing value stackable tells autoAwards whether the required duration is cumulative. If true the required duration is increased by the number of times this Award has been issued. Otherwise, qty only needs to be beaten once.

qty is how many years need to be served
size is ignored, with no use-case intended at this time.
range is ignored, with no use-case intended at this time.

Training Awards

Not currently implemented

Misc Awards

These are hard coded Awards that achieve specific goals. These Awards have to be programmed individually, so their implementation is limited.

Currently, Misc Awards cover 6 different types of Award, as described in the documentation.

Ignored Awards

By setting item to ignore autoAwards will ignore that specific Award. This is useful in cases where users want to disable a single Award, instead of an entire Award Type. It's also useful for those users that create empty Awards to act as separators between groups of awards.

Campaign Options

A number of campaign options have been implemented to help users tweak their autoAwards experience.

Award Bonuses allows users to remove the Edge & XP bonuses given from certain Awards (those set up in the .xml to give bonuses). This can be set to one of four options: Both Awards can give both XP and Edge bonuses; XP Awards can only give XP bonuses, any Edge bonuses in the .xml are ignored; Edge Awards can only give Edge bonuses, any XP bonuses in the .xml are ignored; None Awards do not give bonuses, any XP or Edge bonuses in the .xml are ignored
Award Tier Size tells mhq how many times an award needs to be issues to a single person, before Person View will start displaying the next available image for that award.
Track award eligibility turns autoAwards on & off. Below this are individual checkboxes for each type of Award currently implemented. This allows users to disable entire groups of Awards, should they wish. This option, and all sub-options are enabled by default. If Track award eligibility is disabled all sub-options (and the three remaining options, described below) are all disabled.
Issue posthumous awards toggles whether autoAwards should consider dead people eligible for Awards. Disabled by default
Only issue the best award tells autoAwards whether it should ignore Award eligibility for an Award, if the person is also eligible for a better Award of the same type. This functionality is enabled for Contract Awards (duration sub-type only), Kill Awards (Scenario and General), Injury Awards, Scenario Awards, and Time Awards. For Non-Scenario Kill Awards each formation tier is considered to be a different Award Type, for the purposes of finding the 'best' Award. So multiple Lance Awards are compared against each other, but Lance and Company Awards are not.
Ignore Standard Set tells autoAwards to ignore the default Award Set provided by mhq. This is to discourage people from overwriting the Standard Set with their own Custom Sets, potentially creating a troubleshooting nightmare.

GUI Support

autoAwards has full GUI support, presenting users with a dialog that allows them to dictate which Awards are issued to whom. All columns are sortable, and there is a personnel filter provided that uses the same code as the filter used on the personnel mhq tab. This ensures any code updates will be reflected in autoAwards.

As seen above, the dialog is currently using AI generated placeholder art. Due to the large amounts of data displayed, autoAwards will automatically expand to full screen size. This removes any annoying resizing that would need to be done on a page-by-page basis.

Speaking of pages, each Award Type is presented separately, to avoid having too much information on display at any one time. The GUI features the ability to Skip the current Award Type (without issuing Awards) or to Skip All, which skips the current Award Type and all remaining Award Types. Issue Awards does what it says on the box.

Logging

Currently autoAwards is very verbose, over-posting to the mhq log. This is a deliberate design choice intended for the testing period only. Once initial testing has concluded, the majority of log entries will be moved to debug.

Load

autoAwards is very lightweight and has been stress tested with multiple battalions of units, with supporting staff and hangers on. Testing was performed both with real and constructed data, on a very old laptop. autoAwards completed all required tasks in less than a second.

Actual numbers for the real data were 51 Awards across a total of 458 personnel, for a total of 23,358 Awards processed.

Reading the TOE

I have added two new functions to Force.java that allow for limited reading of a user's TOE.

getMaximumDepth()

This function uses a recursive search to find the depth of the force furthest from the origin force. It then returns that value (depth) as an integer.

getDepth()

This function finds the distance (depth) of the Force from the origin Force.

How is this useful?

By finding the depth of the Force furthest from the Origin Force we can make a couple of assumptions. First, we can assume that any Force at that depth is a Lance (or regional equivalent). If that depth == Lances, then the level above must be a Company (or regional equivalent) and so on, all the way up to (and beyond) Army.

If integrated into other systems, this will allow for improved TOE reading for things like StratCon or AtB scenario generation. Potentially bringing an end to the issue of adding units to company+ forces results in all child forces (and units) being considered for BV balancing.

Awards from the Standard Set

As I've worked on this project I have been updating the Awards from the Standard (default) set to ensure they're supported by autoAwards.

Furthermore, I went ahead and reorganized the Standard Set so that Awards that have to be manually issued are at the top. I also added fancy group Awards that allow mhq to use sub-menus.

[

Finally, I removed any unnecessary tags that are no longer being used.

These changes will have no negative impact on already issued Awards in pre-existing campaigns.

Award Images

Previously, Award Images (such as medal images) were reduced to 30x60 pixels. This meant that neither landscape nor square Award Images were supported. mhq now supports portrait, landscape, and square Award Images for Medals and Misc Awards (the type of award, not the autoAward type described above).

Furthermore, I have added documentation for multiple Award Images to be assigned to the same Award. This has already been described under the Campaign Options section.

Closes

closes #851
closes #871
closes #2429 (or, at least, makes it no longer relevant)
closes #2433
closes #2772
closes #2773
closes #3495
closes #3623
closes #4024

[IllianiCBT]

autoAwards is now in its' final form (barring edits required during the review phase).

All requested additions have been made, except Unit Tests. I gave them an earnest effort, but right now writing Unit Tests is beyond me.