How to Use the Auto-Balancer
The autobalancer uses comma separated value file (.csv) to create battles between different groups of units automatically. By creating lists of units and resource amounts you can generate hundreds or thousands of battles to check on the cost effectiveness of different units. The CSV files are simple text files with commas separating columns of values, that are best and most often generated using Microsoft Excel. For best results this file should be viewed in a fixed font such as Courier.
Setup
You will need an "AutoBalance" directory/folder in the same location as your EE2 executable (typically C:\Program Files\Sierra\Empire Earth II\) but this depends on where you installed the game. In this directory (referred to as the "run directory") create a directory called "AutoBalance" as mentioned.
Within the "AutoBalance" directory create two more directories called "RunInfo" and "UnitLists". The autobalance logs are generated within a directory called "ABLogs". This folder will be created in the C:\My Documents\Empire Earth II\ directory by default. If you wish them to be created in the run directory, you can place the following line in your myconfig.cfg file:
s_generateUserDataInRun = 1
Setting this value to 0 will default the location of ALL log creation to the C:\My Documents\Empire Earth II\ folder. This may effect MP compatibility, so please use at your own peril.
CSV Files
The basic file type of all the files used in the EE2 autobalancer are comma separated valye files, with the .csv suffix. Each line of these files is separated by a linefeed/return, and each item on each line is separated by a comma from the other values around it. You can exit these files with a standard text editor, but we found that Microsoft Excel worked pretty well, displaying each value in it's own cell.
Any line that begins with "//" (a double back slash) is ignored by the parser/autobalancer. These lines are used as formatting breaks or to add comments to the files.
Important: Many bugs are caused by badly formed files (ie. lacking commas or returns in the right places) Most other bugs are caused by having duplicated Name ietms in the files. (See the next section of file structure).
-------------------------------------------------------------
File Structure
The files in the "AutoBalance" folder are the ones that you see when you open the "AutoBalance" menu in the EE2 Map Editor. Each line of an Autobalance file has the following format:
Name, UnitListA, UnitListB, RunInfo
- Name is a unique identifier. It must be different then every other entry in the current CSV file.
- UnitListA is a unitlist.csv file (described below), and specifies the list of "A" units in the battle.
- UnitListB is a unitlist.csv file and specifies the "B" units in the battle.
- RunInfo is a runinfo.csv file (described below), and specifies resource costs and epochs to create the battle. Which we will refer to as the runfile.
Once all the lines in the runfile are finished, the autobalancer starts with the second unit in list B. Once the first unit in list A has fought every unit in list B the second unit in list A begins to battle. This process repeats until all units in List A has fought every unit in List B under every condition specified in the runfile. Once all units in B have fought against all units in A the autobalance run ends.
Here is a typical autobalance file:
Code: Select all
// NAME, Unit List A, Unit List B, Run Info
// , , ,
Epoch2v3, Land_Epoch2.csv, Land_Epoch3.csv, Run_Epoch2vs3.csv
Unit List Files
The unitlist.csv files must be placed in the "unitlist" directort un the "AutoBalance" directory. Each line of the unitlist files as the following format:
Code: Select all
Name, UnitType, ImprovementUpgrade
UnitType is an RPS family entry. This is found either in:
The .ddf for the unit under properties (rps = ?????) or
Column B ("UNIT") of upgrade_unittypes.csv in db/techtree
ImprovementUpgrade can have one of three values/states:
""
"Veteran"
"Elite"
Note that if no upgrade is chosen there must still be two empty quotation marks in the entry.
Here is what a typical unit list file looks like:
Code: Select all
// NAME, Unit Types, Improvement Upgrade
// , ,
ut_1, HeavyInfantry2, ""
ut_2, HeavyArtillery, ""
ut_3, HeavyArtillery, "Elite"
ut_4, LightMounted1, ""
ut_5, HeavyMounted1, ""
The runinfo.csv file must be place in the "RunInfo" directory in the "AutoBalance" directory. Each line of the runinfo file has the following format:
Code: Select all
Name, ResAmtA, CivA, EpochA, FormA, ResAmtB, CivB, EpochB, FormB, Month, Timeout, NumTests, DamageMod, EpochMod
- Name is a unique identifier. It must be different than every other entry in the current CSV file.
- ResAmtA is how much to spend to create units for team A, for each group on the battle map (recall for land battles 12 group of units are create). All resources are summeed together and are figured as equilvalent when computing unit costs. The autobalancer will create as many units as possible without going over the total resources specified.
- CivA is the civilization to use when creating the A units.
- FormA is the formation to use when going into battle for A units.
- Month specifies the month of the year when creating the battle map. Typically 0 and unused during testing at Mad Doc.
- Timeout value is how long (in seconds) to wait until the map unloads, even if all units aren't dead. Typically set to 120 seconds.
- NumTest is how many of these tests to run. Typically set to 1.
- DamageMod is a global increase to damage dealt. Typically set to 1 and unused during testing at Mad Doc.
- EpochMod is a damage multiplier per epoch difference between the teams. Typically set to 1 and unused during testing at Mad Doc.
Code: Select all
// NAME, Res AMT A, Civ A, Epoch A, Formation A,
Res AMT B, Civ B, Epoch B, Formation B,
Month, Timeout Value, Num Tests, Damage Mod, Epoch Mod
epoch2vs3_a, 500, Greek, 2, Phalanx,
500, Greek, 3, Phalanx,
0, 120, 1, 1 1,
epoch2vs3_b, 1000, Greek, 2, Phalanx,
1000, Greek, 3, Phalanx,
0, 120, 1, 1 1,
epoch2vs3_c, 2000, Greek, 2, Phalanx,
2000, Greek, 3, Phalanx,
0, 120, 1, 1 1,
The Results
During a run, as each battle is finished, a line is written to a logfile describing the results. The files appear in a directopry called "ABlogs" either in your run directory or C:\My Documents\Empire Earth II\ folder. The format of these files is as follows:
Code: Select all
Name, TypeA, TypeB, NumA, SpentA, SurvivedA, LostA, RatioA,
NumB, SpentB, SurvivedB, LostB, RatioB....
- Name is the name of the runfile line being tested.
- TypeA are the units in the battle.
- NumA is how many units were created total.
- SpentA is the total spent (note that because of rounding this will probably be lower than 12x resources specified in the runfile).
- SurvivedA is the number of A units that survived.
- LostA is the number of A units that were lost.
- RatioA is the most important value. This number respresents the cost of units killed divided by the costs of the units lost. A number higher then 1 means that the unit is more cost effective. A number less then 1 means that the unit is less cost effective.
The meaning for the corresponding fields for group B is exactly the same as for A, except that it will reflect an inverse relationship in cost effectiveness. That is RatioB will generally be the inverse of 1/x relationship of RatioA since it simply is the costs of units killed by group B divided by the costs of units lost by B. Sometimes a unit that is very expensive yet kills a lot of units, will be proven to be more cost effective, as the weaker but cheap units didn't manage to kill anything.
Testing Methodology
We always tried to use a generic civilization at Mad Doc when testing units, so that civ bonuses wouldn't color the results. This was done by editing "db\techtree\upgrade_factorset.csv" and removing the greek light infantry bonus. Search for CivUpgrade_Greek02, then change the value in column H to 0.
In general we at Mad Doc tried to balance the units in 2 ways. One was to balance within an epoch according to the RPS, then pit that epoch against the epochs around it, adjusting as necessary. The second method was to balance by unit type. For example Light Infantry against itself though the epochs, that is epoch 4 vs epoch 2, epoch 6 vs epoch 4 and so on, then use those units as benchmarks for balancing the other epochs. In the end both techniques had to be used at the same time. A resource value of 4000 per group (or about 48000 per battle) gave fairly good results, but you need a pretty powerful machine to run the tests.
You can put wall towers, outposts, fortresses and anti-air on the unit lists just as easily as regular units, and the battle will run just fine, but since the placement of these static defences are somewhat artificial our experience at Mad Doc, was that the data gathered from these tests were less reliable then plain old play testing.
Finally, there is a known bug that you should be aware of in using the autobalancer. On some machinese the autobalancer may crash the machine at the end of a test run, due to improper release of sprite memory. So if it happens to you try to use the autobalancer on another machine.