ReadMe for Battles
------------------

Colin Frayn,
C.M.Frayn.96@cantab.net
Birmingham,
March 2004


Contents
--------

 (1) Introduction
 (2) Files Included
 (3) Designing an Army
 (4) Starting a Game
 (5) In-Game Controls
 (6) Tactics for Battle
 (7) Altering the Data Files
 (8) Projectile Theory
 (9) Acknowledgements
(10) Copyright notice



(1) Introduction
----------------

"Battles" is the result of a few weeks of hard work, and a lifetime of
daydreaming.

As a child I always loved the idea of fantasy battles between armies of elves,
dwarfs, giants and orcs.  I used to collect miniature models which I would paint
and arrange in units as a hobby.  The only problem was that it was expensive, and
took a lot of time (and space) to do.

I thought about writing a fantasy battles program when I was still at school.  In fact
I even wrote an army editor using Turbo C on my PC at home, but it never got any further
than that.

"Battles" is the game that I wanted to write for ages.  It allows you to create and
manage armies from the size of a small unit right up to an enormous horde.  It allows
you to visualise your forces in full 3D, battle against your enemies in a near-infinite
range of fractally-generated scenarios.  It includes trees, marshes, lakes and rocks.
It includes a recursive variable level of detail terrain engine for displaying your
world as you watch the action pan out.

Most importantly, you are granted an arena in which you can pit your own army against
that of a friend, an enemy, or even the computer.  A simple AI system gives the
computer the knowledge that it needs to control its forces efficiently and challenge
you to a battle to the death.

I hope you enjoy playing "Battles" as much as I have enjoyed writing it!


(2) Files Included
------------------

Included in this distribution you should find the following files;

Battles.exe - The executable file
ReadMe.txt - This file!
Data\Unit.dat - Unit definition data file
Data\Armour.dat - Armour definition file
Data\Weapon.dat - Weapon definition file
Data\Spell.dat - Spell definition file
Armies\Sample10k.arm - A sample 10,000 point army
Armies\Sample20k.arm - A sample 20,000 point army


(3) Designing an Army
---------------------

The army designer is found in the Options menu from the main game screen.
It has several main function buttons across the top which are the following;

Load  - Load a saved army
Save  - Save the current army
Reset - Reset the current army (without saving)
Exit  - Exit from the army designer (without saving)

To the left of the dialog box you will see the unit list.  This is a list
of all the units in the current army.  It will be empty initially.

On the right of the dialog box is the unit design section.  This will show
the details of the currently selected unit.  This, too, will be blank when
the dialog box initially opens.

Try creating a new unit.  Press the button marked 'new unit' at the bottom
of the unit list.  A new unit will be created at the end of the unit list.
The default unit is a tiny group of 10 human soldiers (this may vary if you
have altered the data files).  On the right hand part of the dialog box, this
unit's statistics are displayed.

At the top-right, you will see the 'unit type' tab-selection window.  This 
shows the type of this unit.  By selecting each of the tabs you can select
a different kind of units, and a different soldier type.  The choices are
'Troops', 'Artillery', 'Monsters' and 'Heroes'.  These are fairly self-
explanatory, I hope.

The base statistics for each unit type are displayed in the histogram under 
the unit type window. (White bars on a black background).  The four statistics
displayed are 'Attack', 'Defence', 'Range' and 'Speed'.  These determine the
unit's hand-to-hand attack strength, its defensive ability, it's ability with
ranged weapons and its marching speed across level ground respectively.

To the right of the statistics are the pull-down menus for armour and weapon
selection.  Depending on the unit type, different weapons and armour types will
be available.  The prices for these are also scaled by the size of each soldier
in the unit.  You can choose to carry a shield only if you are not wielding a
double-handed weapon.

The final selections are the 'elite' boxes, which allow you to choose the elite
strength of your soldiers.  This varies between +0, or normal soldiers, all the
was up to +4, or highly elite soldiers.  This value alters the number of action
points your soldiers have, and also their proficiency in combat.

Below the elite selection boxes is a large button displaying the unit's name.  The
Default is "Untitled".  Yo can click on this if you want to give your units special
names, as has been done with the example armies.

Finally, to the bottom right-hand corner of the window is a series of buttons which
allows you to alter the number of soldiers in this unit.  Each soldier type has a
maximum unit size.  Some soldiers such as heroes are always on their own.  Under these
buttons are the cost per soldier and the total unit cost, found simply by multiplying
the unit size by the cost per soldier.

Under the unit selection list are options to delete the current unit (warning - no undo!)
and to change the order of the units in the list.  At the bottom is a tally of the
total army cost.  This allows two players to choose armies which are of approximately
the same strength in order to run a fair battle.


(4) Starting a Game
-------------------


When you have designed some armies then you are ready to start a game.  Alternatively,
for a quick start you can use the armies supplied with the distribution.

To start a new game, choose the 'New' option from the 'File' menu.  The keyboard shortcut
for this is 'Alt-F' followed by 'N'.  At present I haven't implemented 'Load' or 'Save'
for the battles.

You are presented with the "New Game" dialog box, which gives you several options.

Firstly, in the top left corner is a list of the competitors in this game.  They will
initially be empty, of course, though you can add in new armies by clicking on the 
army name bars and selecting a file from the dialog box.  Control for each force can also
be changed by clicking on the tab which currently displays the word "Human".  Next to the
army name is displayed that army's point value, and to the right of this set of controls is
a drop-down menu whicha llows you to alter the colour of each army.  Of course, no two armies
may use the same colour.

Secondly, to the top right of the dialog box are two buttons.  One is the "Cancel" button,
if you wish to abort the new game process.  The second is the "Accept" button, which will
only be activated when you have selected at least two competing armies.

The bottom half of the dialog box allows you to select the arena in which these two or more
armies will meet.  The dimensions are selected from the drop-down boxes, and other parameters
can be selected from the text fields below.  The fields are;

Degree of Roughness : (0-100%) Higher is rougher.  0 is flat.
Average Terrain Height : (0-100m) Approximate average height above sea level.
Forest Fraction : (0-500) Fraction of the map covered in forest in parts per thousand.

Beneath these fields you can choose to preview the current map or generate a new random
seed. Previews of the map are shown in the frame to the bottom-right corner of the dialog
box.

When you are happy with the game settings then hit "Accept" and the game will begin.
Be prepared to wait for a while for the map to generate.  It's generating everything to
1m detail precision, remember!


(5) In-Game Controls
--------------------


During the game you will need to know a few simple controls.  Almost all commands are done with
the mouse, but there are some more controls used to alter the view, move around and set up the
graphic details.

Select Unit        : Left mouse button
Select Target      : Left mouse button
Move to Target     : Left mouse button
Deselect           : ESCAPE
Direction Arrows   : I
Cast a spell       : M  (magic users only)
Next player        : N
Reset Viewpoint    : R
Change Base Detail : F1 - F4
Change Fog Level   : F5 - F8
Change Starfield   : 1 - 5
Smooth Terrain     : O
Toggle Flag Size   : L
Zoom to Unit       : C
Target Selection   : T
Move Viewpoint     : A, S, W, Z, L-mouse + scroll
Rotate Viewpoint   : Arrow Keys, R-Mouse + scroll
Move Up/Down       : Page Up, Page Down
Zoom in/out        : Mouse wheel
Speed up Movement  : SHIFT + key

During Unit Placement:
Rotate Units       : CONTROL + L/R Arrow Keys
Rotate Units 45deg : CONTROL + SHIFT + L/R Arrow Keys



(6) Tactics for Battle
----------------------

I'm not a military tactician, but I suggest the following hints might
well help you out:

(a) Put missile units on high ground - they get a longer range, and other units
have to charge uphill to get to them.  Also, enemy missile units downhill will
not be able to reach them as soon.
(b) Put fragile units in cover, i.e. in forests.
(c) Don't leave valuable units out in the open, except for mages, which can escape
using their teleport spell.
(d) Buff up your units using spells before entering combat.  If possible, also
weaken your opponents.
(e) If you don't need to use a spell then store up magic points and go for a more
powerful one, such as Maelstrom.
(f) If you are charging into battle, don't charge too far or else you'll not have 
enough action points left when you arrive to do any damage.
(g) Don't keep units too close together or else they're easy prey for missile units.

Good luck!


(7) Altering the Data Files
---------------------------

The data files provided with "Battles" reside in the "Data\" directory.  Their
formats are given here in case anyone wants to fiddle with the values in those
files.  I suggest you keep a backup of the originals too!

For each entry in the data file, the default value is given in brackets [] after
the description for any non-essential entry.  All the essential parameters MUST
be present for each entry in the datafile.  Suggested ranges are given in
parantheses () and are not usually enforced.  All numerical values must be >= 0.

:: Data\Unit.dat - Unit definition data file
   -------------

Human Accolyte   # Soldier Type
{
cost=100    # Cost per soldier (in points)
maxn=1      # Maximum unit size
minn=1      # Minimum unit size
attack=3    # Attack score (1-15)
defence=4   # Defence score (1-15)
ranged=3    # Ranged weapon attack score (1-15)
speed=7     # Movement rate (1-15)
size=2      # Size per soldier (base side length in metres)  [1]
height=2    # Height of each soldier (in metres)  [2]
noweapon    # May not use a weapon  [not set]
noarmour    # May not use armour  [not set]
magic=1     # Magic level (0-4)  [0]
body=4      # Number of hit points per soldier (1-10)  [1]
type=Hero   # Creature type (Troop, Artillery, Monster, Hero)   [TROOP]
elite=0     # Maximum elite level (0-4)   [0]
nattacks=1  # Number of attacks per soldier  (1-5)  [1]
            # Extra flags for artillery only;
ArtilleryDam=12      # Damage per artillery hit   [0]
ArtilleryRange=500   # Range for artillery fire   [0]
ArtilleryType=Bolt   # Type of artillery (bolt, arrow, rock)   [ROCK]
ArtilleryROF=1       # Rate of fire for artillery   [1]
}


:: Data\Armour.dat - Armour definition file
   ---------------

Enchanted Platemail   # Armour type
{
cost=40    # Cost per item in points
def=7      # Defence bonus versus melee weapons (0-10)   [0]
ranged=7   # Defence bonus versus ranged weapons (0-10)   [0]
special    # Is a special weapon? (Useable only by heroes)   [not set]
slow=1     # Movement penalty (0-4)  [0]
}


:: Data\Weapon.dat - Weapon definition file
   ---------------

Enchanted Longbow   # Weapon name
{ 
cost=25    # Cost per item in points
dam=12     # Damage per hit  (1-20)
bonus=2    # To-hit bonus  (0-10)
speed=10   # Weapon speed, higher is faster.  (1-20)   
range=450  # Maximum range in metres  [0]
twohand    # Two-handed weapon (may not use shields with this weapon)   [not set]
special    # Is a special weapon (useable only by heroes)  [not set]
}


:: Data\Spell.dat - Spell definition file
   --------------

Magical Bolt   # Spell name
{
Range=500      # Maximum range, in metres (0-500)   [0]
Effect=BOLT    # Effect type (see below)
Cost=1         # Magic points to cast (1-6)
Attack=20      # Attack strength  (0-20)   [0]
Damage=8       # Damage per hit  (0-10)   [0]
NHits=1        # Number of hits per casting  (1-5)   [0]
Maxtarg=200    # Maximum number of soldiers in target unit (1-300)  [200]
}

Available spell effects (effects as per the spells of the same names);

TELEPORT, LIGHTNING, ANIMATE, HASTE, SLOW, TOUGHEN, WEAKEN, BOLT, FOREST,
MARSH, ELEMENTAL.


If you don't understand what certain parameters do then feel free to play
around with them, or see how I've used them myself in the provided data
files.  Most things become obvious after a minute or two.


(8) Projectile Theory
---------------------

This is just some of the mathematics behind the projectile theory used in
the calculation of weapon ranges.  It assumes no wind and no air resistance,
just a simple ballistics calculation based on simple Newtonian mechanics.

Some elementary mathematics shows that the maximum range of a projectile
is given as;

X = v^2 sin (2 a) / g      ---- (1)
 
Where 'v' is the initial speed, 'a' is the angle of the shot from horizontal,
and 'g' is the acceleration downwards due to gravity.  (In order to calculate
this, consider the initial speeds in the y- and x-directions.  Also consider
the deceleration vertically, and solve for y=0.  Using the value of t>0 for
y=0, substitute into the formula for x.)

Further manipulation therefore gives the maximum muzzle velocity,
V_m as;

V_m = sqrt(R * g)          ---- (2)

Where 'R' here is the maximum range of a projectile.  This is specified
for each individual weapon (such as a longbow) as the range along flat ground.

For a target at a different height to the firing position, the calculation is
slightly more tricky, but gives;

X(h) = V_m cos(a) ( V_m/(g*sqrt(2)) + (1/g)sqrt(V_m^2 / 2 + 2gh) )

Substituting the maximum range as using an angle, theta of 45 degrees, as is
obvious from equation (1), and also inserting the formula for V_m, equation
(2), we end up with the following result relating the maximum range of a
projectile given its maximum range on flat ground, 'R', and the height difference
between the firing position and the target, 'h';

X(h) = R/2 + sqrt(R^2 / 4 - Rh)    ---- (3)

Clearly this reduces to the previous result for the case h = 0.  For large h, 
this rapidly decreases until h = R/4 when the range is half what it was previously.
For angles less than this, the formula breaks down beacuse the height is
unreachable at a firing angle of 45 degrees.

If we wish to presume the firing angle instead, we are left with the following
form;

X(h) = R sin(2a) / 2  +  cos(a) * sqrt(R^2 sin^2(a) - 2Rh)

which reduces to (3) when a=45 degrees is substituted in.

For this general case, the velocity required in order to fire a projectile a
distance dR to a height h is equal to;

V = dR sqrt( g / (dR - h) )



(9) Acknowledgements
--------------------

'Battles' was written by me (Colin Frayn) in March 2002, based on a terrain
engine that I wrote in Autumn/Winter 2001 for a different project.  Much of the
OpenGL code was taught to me by both the OpenGL Programming Guide (Woo, Neider,
Davis and Shreiner) and also by my housemate, Jon Harrop.  Thanks to all those
people.  Some later work was done in the winter of 2003/2004.


(10) Copyright Notice
---------------------

Battles is freely distributable freeware code.  I wrote it for fun.  You don't
need to send me any money (though I wouldn't complain if you did) and you don't
need to ask for my permission if you steal any of my ideas - I'd probably be
flattered!  However, what I ask is that you do not try to pass this code off as
your own work (unless you wrote the font rendering subsystem!) nor do you steal
large chunks of it for use in your own programs, unless I am properly referenced.
If you alter the datafiles yourself then make sure that this is explained clearly
with your distribution, and that a copy of the originals is also supplied.

Source code is available on request to C.M.Frayn.96@cantab.net

Above all, enjoy the game!
Cheers!



Colin Frayn,
C.M.Frayn.96@cantab.net
Birmingham,
March 2004