[Documentation] Soldier name pool weights and hiring by location

[Meridian]

This is a documentation for the two features requested here:

1. [SUGGESTION] "nationFrequency": https://openxcom.org/forum/index.php/topic,10760.0.html

2. [Suggestion] Soldier names limited to region/country: https://openxcom.org/forum/index.php/topic,10840.0.html

-----------

The existing soldier name files now have a few more optional attributes:

a/ `globalWeight` (integer from 1 to unlimited, default 100), which can be used to influence the odds of each file being used

b/ `country` and `region` (both a single string, default empty), which can be used to filter the relevant name files when hiring soldiers

Simple example for skewing the global odds:
Let's assume you have only 3 name files: American, German and Japanese. If you want to have the name distribution of 70%-25%-5%, you can define global weights using exactly those 3 numbers.
However, weights are not odds, you can use also weights 7000-2500-500 or 140-50-10 or 210-75-15... all of these have the same effect!
I also recommend not using too small numbers, it will make it easier for you to make changes later.

In the attachment, there is a small mod with this example called "Uneven Army Composition".

-----------

Hiring by Location is a bit more complicated.
First of all, unlike global weights, it does NOT apply everywhere.

It applies only in the following situations:
1. Hiring new soldiers at a base -- location = base
2. Manufacturing soldiers at a base -- location = base
3. Recovering civilians as soldiers after a mission -- location = craft landing location (or base in case of base defense mission)
4. Receiving soldiers from an event (only for region/city-specific events) -- location = chosen city (if the event is only region-based, a city is chosen anyway in the background invisibly)

It does NOT apply for:
5. when starting a new game... the first xcom base and its soldiers are generated long before the player actually chooses a location for that base, sorry
6. in the New Battle mode -- there's no location to use
7. all other places, where soldiers are created, but not hired: for example soldier transformations/cloning (if possible cloning tries to preserve nationality), craft preview feature, etc.

The global weights still DO aply even here though. Just location doesn't.

For completeness, there are also cases, where even global weights don't apply, usually error handling:
8. when a player manually edits a save and creates an invalid nationality
9. when a modder uses soldier template for manufacturing, recovery or events and specifies an invalid nationality
10. when a soldier is transformed from one type to another and the destination type doesn't support the source nationality
11. when converting original saves (hardcoded to 0)

In most of these error handling cases, a random nationality (without using global weights) is assigned.


Two new global ruleset variables are introduced:

a/ `hireByCountryOdds` (integer from 0 to 100, default 0), used to define the odds of attempting to name the soldier based on the country where it was hired

b/ `hireByRegionOdds` (integer from 0 to 100, default 0), used to define the odds of attempting to name the soldier based on the region where it was hired


The algorithm is as follows:

Code: [Select]

if (location exists AND hireByCountryOdds RNG hit)
{
  determine the country, based on the given location
  if country found, go through all name files and find the FIRST name file that matches the country... if found, use it
}

if (location exists AND hireByRegionOdds RNG hit AND we didn't already name the soldier in the previous step)
{
  determine the region, based on the given location
  go through all name files and find ALL name files that match the region (can be more than one)... if found, use this filtered set of name files and choose one of them based on global weights
}

if (we didn't succeed in previous steps)
{
  use all name files and select one based on global weights
}

Notes about the algorithm:
- we assume that each country has only one name file (or none); should you use the same country in multiple name files, only the first will be considered
- each region can have multiple name files; should you use the same region in multiple names files, all of them will be considered (and one will be chosen by global weights)
- the two RNG rolls (one for country and one for region) are independent

In the attachment, there is a small mod with an example called "Hire by Location".
`hireByCountryOdds` is set to 80%
`hireByRegionOdds` is set to 50%

Europe has enough name files to test all four use cases (hiring, manufactruing, recovery and events).
Manufacturing project is set up, event is set up to appear on day 10 or 11, and all civilians are marked to be recovered (for example from a terror mission).


Disclaimer: the standard xcom rules about not repeating existing soldier names still apply in all of this!! so when making your test mods and testing the probabilities, make sure your name pools are big enough! otherwise your test results may be completely off.