From 1db5aa50057e2813428ee53e014cbbdb7dfd7d96 Mon Sep 17 00:00:00 2001
From: Lesh <Lesh@4f8fa57e-7814-0410-bad4-adc449f26b7c>
Date: Sun, 19 Nov 2006 15:35:22 +0000
Subject: [PATCH] - comments on army externalization (3/3)

git-svn-id: https://ja2svn.mooo.com/source/ja2_v1.13_data@589 4f8fa57e-7814-0410-bad4-adc449f26b7c
---
 .../Data/TableData/Army/ArmyComposition.xml   | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/gamedir/Data/TableData/Army/ArmyComposition.xml b/gamedir/Data/TableData/Army/ArmyComposition.xml
index 969853827..f4941d33a 100644
--- a/gamedir/Data/TableData/Army/ArmyComposition.xml
+++ b/gamedir/Data/TableData/Army/ArmyComposition.xml
@@ -1,3 +1,78 @@
+<!--
+
+This file defines army compositions in game.
+
+Fields index:
+	Index   		- it is simply composition index. Provide valid integer number.
+				  See reference on indexes in original game below.
+
+	Priority   		- it is importance of the composition to the Queen. Most important
+				  compositions are getting reinforcements first, than less important. 
+				  Nobody will get reinforcements, if Queen have no free troops.
+
+	ElitePercentage		- it is a chance to be elite for every soldier in squad, i.e. when
+				  game create a squad every soldier is rolled a chance to be elite.
+				  Provide integer from interval [0..100].
+
+	TroopPercentage		- it is like ElitePercentage, but for regular troops.
+
+	AdminPercentage		- and this is something different. This value is used to calculate
+				  number of admins in squad:
+				      NumAdmins = AdminPercentage * StartPopulation / 100
+
+	DesiredPopulation	- it is the number of soldiers the Queen want to have in this
+				  composition. Provide integer value.
+
+	StartPopulation		- it is the number of soldiers at the start of the new campagin.
+				  Provide integer value.
+
+Indexes reference in original JA2:
+
+Index	Short name		Desription
+0	QUEEN_DEFENCE,		//The most important sector, the queen's palace.
+1	MEDUNA_DEFENCE,		//The town surrounding the queen's palace.
+2	MEDUNA_SAMSITE,		//A sam site within Meduna (higher priority)
+3	LEVEL1_DEFENCE,		//The sectors immediately adjacent to Meduna (defence and spawning area)
+4	LEVEL2_DEFENCE,		//Two sectors away from Meduna (defence and spawning area)
+5	LEVEL3_DEFENCE,		//Three sectors away from Meduna (defence and spawning area)
+6	ORTA_DEFENCE,		//The top secret military base containing lots of elites
+7	EAST_GRUMM_DEFENCE,	//The most-industrial town in Arulco (more mine income)
+8	WEST_GRUMM_DEFENCE,	//The most-industrial town in Arulco (more mine income)
+9	GRUMM_MINE,
+10	OMERTA_WELCOME_WAGON,	//Small force that greets the player upon arrival in game.
+11	BALIME_DEFENCE,		//Rich town, paved roads, close to Meduna (in queen's favor)
+12	TIXA_PRISON,		//Prison, well defended, but no point in retaking
+13	TIXA_SAMSITE,		//The central-most sam site (important for queen to keep)
+14	ALMA_DEFENCE,		//The military town of Meduna.  Also very important for queen.
+15	ALMA_MINE,		//Mine income AND administrators
+16	CAMBRIA_DEFENCE,	//Medical town, large, central.
+17	CAMBRIA_MINE,
+18	CHITZENA_DEFENCE,	//Small town, small mine, far away.
+19	CHITZENA_MINE,
+20	CHITZENA_SAMSITE,	//Sam site near Chitzena.
+21	DRASSEN_AIRPORT,	//Very far away, a supply depot of little importance.
+22	DRASSEN_DEFENCE,	//Medium town, normal.
+23	DRASSEN_MINE,
+24	DRASSEN_SAMSITE,	//Sam site near Drassen (least importance to queen of all samsites)
+25	ROADBLOCK,		//General outside city roadblocks -- enhance chance of ambush?
+26	SANMONA_SMALL
+
+
+Army composition soldier count calculation:
+
+1)  game calculate number of admins (NumAdmins = AdminPercentage * StartPopulation / 100)
+2)  for the rest soldiers game makes a loop:
+2a) soldier check to be elite
+2b) soldier check to be regular troop
+2c) if both checks failed, none soldier is added
+3)  step 2 is executed until there are unchecked soldiers left
+
+
+NOTE: Maximum 60 army compositions can be used in game.
+
+Changes require starting of a new game.
+
+-->
 <COMPOSITION_INFO>
 	<COMPOSITION>
 		<Index>0</Index>