Defining Units

The unit definition data consists of the icons in /gfx/CFUnits.bmp (images) and the unit control parameters in the definition /tools/default.usrc (source text). These two files are combined using the mkunitset.exe (which is invoked when you build CF from it's source (during the 'make' sequence) to generate the run-time 'compiled' default.units file. You can't 'unmake' the compiled file - so to make changes you must have access to the two 'source' files, CFUnits.bmp and default.usrc along with the 'make' tool, mkunitset.exe

Note that the units parameters include it's translated names, which makes 'drastic' modifications a bit of a pain (even with the help of Google translate :-) ) if you want to maintain the translations.
 
Fortunately, the translations are only required if you choose that language (so stick to English and CF will never notice you didn't bother to include any translated names for your new Units)

Units are defined only once. In CoMET, exactly the same unit types and unit definitions can be deployed for either player . The only difference is the 'icon', one brown, one blue.

If you want players to have, for example, different types of 'Heavy Tank' you have to define two different Heavy Tank units (Tank player 1, Tank player 2) and pre-deploy them accordingly (and restrict what a player can build in their factories)
 
To avoid giving the 'other plater' the 'wrong' tank (when laying out the forces in CoMET), the other players icon can be set to a red 'X' (or even left blank == which opens the door to 'stealth' units (or even submerged submarines))
 
Note that, just like Terrain Tile icons, the Unit icons can be 'reused'. For example, you could define two units, 'Spitfire' and 'Me109' with different parameters (move, armour attack) that both use the same 'fighter' icon.
 
In my own new Units (see later pages), I reuse the 'Depth Charge' as a 'Supply Container' and the 'Landing Craft' as a 'Transport Truck' :-)

[top]

Unit artwork

Unit icons are defined in a single CFUnits.bmp file. Each unit has 6 'facings' (N, NE, SE, S, SW, NW) and 2 'colours' (brown & blue) so has 12 images. The .bmp file is arranged 24 icons (2 units) wide by 12 rows for a total of 24 units. There is nothing to stop you adding as many extra units as you wish** (icons, left, show some of my new units)

Some units have 'portraits' - these are higher resolution (300x168 or 168x300) 'splash screen' images held in separate files (eg \gfx\u_infantry.bmp) which are 'referenced from the .usrc file (and displayed when the player selects the units details)

**As we see later, the CoMET tool organises units into rows of 4. This means you should add new units in 'sub-sets' of 4 at a time (i.e. two rows, each of 24 icons defining a pair of Units).

[top]

The 'transparent' colour

When unit icons are 'painted' over the background (terrain tile) hex's, the terrain tile 'shows through' those parts of the unit icon that are 'transparent'. This is achieved (in CFUnits.bmp) by using the 'pink' colour RGB=212,0,254 (.bmp palette no. 0) as 'transparent'.

Most image edit software will allow you to choose this colour (or any other) as 'transparent' when creating your own .bmp unit icon artwork. Of course, it's a lot simpler to just 'edit' (add to) the existing CFUnits.bmp file :-)
 
Because Units are 'painted' over Tiles, it's quite possible to create an 'invisible' Unit (one with an icon = completely transparent)

[top]

Building the .units file

The bit-map sources (CFUnits.bmp & all the u_xxxx.bmp portraits) are combined with the unit definitions (default.usrc) to create the 'default.units' file. When crimson.exe is built by \tools\Makefile the 'mkunitset.exe' utility (which is built from mkunitset.cpp) is invoked automatically. If you edit the Unit definitions and icons later, you can launch mkunitset.exe from the command line

'mkunitset' checks the unit definitions in the .usrc file and creates (& saves) a complete definition 'set' for each unit (filling in with defaults as needed). It also adds the name of the 'movement sound' (.wav) file to be used for that unit.
 
It then saves the 'icons' .bmp file as a single image 'block' and finally adds the unit portraits (if any).
 
Note that it appears that SDL is used to parse and load the .bmp files into memory and then used again to 'write' the whole 'set' at the same time to the 'output' file. The image data is simply 'raw' (8bit palette .bmp = 1 byte per pixel) with no attempt to 'separate' the icons

[top]

Linking Units to maps

The compiled maps (*.lev) use Unit ID code, whilst the map source (*.src) use the units (English) name.

Unit ID codes are created automatically (sequentially) when the default.units file is 'compiled' from the definitions (default.usrc file) and icons (CFUnits.bmp) files.
 
So, when you use CoMET, the unit (English) names are looked up and added to the text based map 'source' ('.src') files. When cfed.exe converts the map 'source' into a playable level (*.lev) file, the unit names are replaced with their ID code
 
CoMET displays the Units in the order in which they are defined (in .usrc)

What this MEANS is, the unit 'name' is only 'significant' in the map source (.src) file. If you replace the default.units file with a new one containing new unit definitions (& new names), the existing .lev maps will 'pick up' not only the new name but any other changes, such as new combat definitions or icon .bmp without complaining

If you change the names, then opening a '.lev' in CoMET will pick up the new names (and saving as .src will change the old names to the new ones). Of course, trying to rebuild from an old .src into a .lev will result in 'unit name not found'.
 
It also means that if you change the order of Units in the definitions file (eg by adding a new unit at a logical place, instead of at the end), and then recompile into a new default.units, the ALL the existing maps must be recompiled (otherwise the existing .lev will 'pick up' the 'wrong' Unit ID as they get out of step after the newly inserted unit)
 
This problem can be avoided it you ONLY ever add new units to the END of the file (which means they are shown in CoMET's Unit selection frame at the bottom)

[top]

Unit definitions (.usrc)

Note that a # (hash) symbol at the start of any line in the definitions file indicates a 'comment' and results in the whole line being ignored by the 'mkunitset.exe' utility compiler

[top]

[unitset]

Indicates the start of the definitions set. Appears once.

name =

The 'name' of this definitions 'set' (you should set this to the file name)

icons =

The name of the file where the unit 'bitmaps' (hex icon images) can be found (eg CFUnits.bmp)

[top]

[unit]

Indicates the start of an individual unit definition. There will be as many [unit] definitions as there are units. Units do not have to be defined 'sequentially' - the icon number to be used is part of the definition. However, the Unit ID, which is created automatically when the definitions are complied, is assigned sequentially. So (unless you want to recompile all the existing maps) any new new units must be added to the end of the definitions file.

Saved games and complied map (.lev) files use the Unit ID codes. If you change the Unit definition order, the units in your saved games and complied maps will pick up incorrect Unit parameters

name(lang) =

The name of this unit (in each language =). eg :-

The name is used to identify the unit in the battle maps definition (.src) files, however the compiled maps and saved games (.lev files) use the Unit ID code (which is created automatically when the definitions are complied).

This means you can change unit 'names' without needing to recompile the maps, HOWEVER if you do change the (English) name, unless you also change it in the map .src files, those maps won't compile ..

type =

This units' basic 'type', one of 'ground', 'ship' or 'aircraft'. This defines the unit's 'vulnerability', not the terrain it can enter (see 'terrain =' below). For example, a 'type = ground' unit can only be attacked (or counter-attacked) by other units that have a 'power(ground)' capability.

type= does not determine the type of 'terrain' a unit may cross. So you can give a 'ground' unit (eg tank) the ability to cross rivers ('shallow water').
 
Note that units defined as 'type=aircraft' still require terrain 'permissions' (but count all terrain cost to enter as '1')

A unit can be of more than one 'type' (mines, for example, are both 'type=ground' and 'type=ship', which means they can be attacked by units with power(ground) or power(ship)). A Unit can also be assigned as one or more special 'type' which limits (or adds) to a units abilities. The types are :-

** see later re:  How mines work
*** sweepers can pick up any unit of type mine, including enemy mine units (which are then 'converted'). Note that 'sweeping' is performed at the end of the turn (if you do it 'first' you don't get to move).
**** there is no special 'type=' for transport units. A transport unit is any unit that has a 'transslots' parameter value (see later).
***** 'repair' uses 5 'crystals', which have to be 'on-board' the transport at the same time as the unit being repaired. Repair always costs 5 'crystals' and always takes 1 turn, no matter how damaged a unit is.

Note that (other than 'trooper', which allows terrain=shop) the 'type=' does NOT define the 'terrain' the Unit is allowed to enter. This is set by the 'terrain=' parameter(s), see below.

icon =

The bit-map to be displayed (from the CFUnits.bmp) for this unit when 'north facing'. There are actually 12 (sequential) bitmap icons for each unit, two sets (one in each players color) of 6 (one for each possible facing).

The order shown in CoMET is the order of definitions - which starts with Infantry and then Medium Tanks.
 
The  icon bitmaps file CFUnits.bmp start at 0 with Medium Tanks 'icon = 0' (which uses bitmap's 0-11), then comes the Infantry at 'icon = 12' (which uses 12-23) and so on. The standard set ends with 'Aircraft Carriers' at 'icon=276' (using 276-287).
 
Icons can be 're-used' - you can use a single icon (eg for a fighter aircraft icon) for multiple different Units (eg Spitfire, ME109) each of which has their own definitions. Of course having the same icon for multiple units on the same side (eg Spitfire, Hurricane) can make things a bit confusing for the players :-).

terrain = {a terrain 'type'}
terrain = {a terrain 'type'}
...

Each entry defines one terrain 'type' that this unit is 'allowed' to enter**. Units will typically have multiple 'terrain =' values. If the unit is faced with a Tile of terrain 'type' not listed for that Unit, then it can not enter that tile. NOTE that this applies to all Units, including aircraft (so aircraft have a 'full set' of 'terrain=' settings). eg :-

**units can be 'pre-deployed' (using CoMET) onto terrain of a 'type' they are 'not allowed' to enter = you will get a 'warning' ('unit N walking on invalid terrain') when you 'validate', however the cfed.exe tool will still 'compile' the map (to a .lev file) OK.

The terrain types are:-

In the Tiles definitions, a Tile that can be entered must be assigned one or more of these 'terrain =' types. To move into that tile, the Unit must be assigned a matching type. The special Tile terrain=shop indicates a building entrance. To enter the building (terrain=shop), the instead or terrain=, the Unit needs to be of 'type=trooper' (special setting, see above).
 
Just as each Unit has it's own 'speed =' (see below), each individual terrain tiles has a 'move =', which is the cost of moving into that specific Tile
 
Tiles of the same 'terrain =' usually have different 'move =' cost. This allows (for example) 'terrain= forest' to cover anything from a few trees, to sparse, medium and dense woods, and dense forest. Tiles of terrain=mountains covers (steep) hills to rocky peaks.

Note that adjusting the terrain= settings for a Unit can have unexpected side effects

For example, when I added 'shallow water' capability to APC's & Tanks to turn them into 'amphibious vehicles' for my WW2 maps, I discovered the AI moving it's tanks 'up river' :-)
 
This was because river tiles are defined as 'shallowwater' that normally only Ship units would be allowed to enter. So the fact that the 'cost' of moving in shallowwater was less than the 'cost' of moving on the nearby land tiles didn't matter .... until I allowed a land unit into water !
 
To prevent the AI choosing to move it's tanks 'up river', I had to adjust all 3 'water' terrain= Tiles so that their move= was higher than 'rough'. To compensate, I then adjusted the movement 'allowances' of all 'ship' units.
 
When I did this, some ship Units ended up with movement allowances exceeding 16 = which I then discovered would allow them to move over other units - and even 'stop on top of' them which could cause crimson.exe to crash == see later

armour = {n >= 1}

This units 'defence strength' against all attackers, integer, 1 or above. Setting 'armour = 0' will crash crimson.exe when that unit enters combat

Note that most terrain tiles have 'combat modifiers', which adjust both the attack and defence values of any unit 'in' that tile

speed = {n}

Movement allowance per turn (can be 0). On a ground or ship units turn, the tiles it can enter are calculated by deducting each tile move= from the Units speed= until the remainder is insufficient to enter the next tile. Units of type=aircraft count all tiles as move=1. If the tile contains a Transporter (which can carry the Unit), the 'cost to enter' is 1 (but the Unit must still have terrain= permission for the terrain in which the transporter is positioned).

Units such as mines and my new Pillboxes and Bunkers (immobile transports with high armour= that allows other units to shelter inside = see later) have speed 0.
 
Note the difference between a unit with 'type = mine' and 'speed = 0'. A mine can be deployed into any of the 'terrain= ' defined for it (i.e. the mine)**. A unit of speed=0 can never move at all. Should a speed=0 unit be loaded into a transporter (eg pre-deployed using CoMET or during the game on leaving a building eg. Factory), it can not be 'unloaded' except at a building.
 
**A 'sweeper' is only allowed to sweep (pick up) a mine from a Tile that the sweeper is allowed to enter. If the Mine is 'owned' by the enemy, it can only be 'swept' if there are no enemy units 'in contact' with it. When swept, the mine becomes the property of the sweeper (even if that means it has to 'change side'), which works well for 'Supply Containers' dropped (deployed) from the air.

price = {n}

Initial build cost (in resource point "crystals")

Note that the initial cost has no effect on the 'repair' cost, which is 5 'crystals', no matter what the damage or the original 'cost'.
 
This has quite a drastic effect on game play. There are very few 'crystals' to be had on most maps, so players will only bother to 'repair' their most expensive units. Since 'Factories' (with repair capability) are typically located to the rear, multiple moves away from the front, the only unit that gets repaired is aircraft. All other units end up 'fighting to the death' (which is OK as far as Stalin and Hitler are concerned but unrealistic when it comes to the Allied forces)
 
The '5 cost' nonsense needs reworking (the easy way is to leave the current rule that you 'must have 5 crystals before you can repair anything' but modify the 'deduction' based on the Units original build cost and how 'damaged' the unit now is). Yes, this could result in a negative balance (it will be interesting to see what crashes)

weight = {0-99}

This units 'weight', used only to determine the ability of a Transport to carry this unit (the weight of a unit is constant, irrespective of loss or 'damage')

Transports are limited to a total sum weight of 'transslots' (each individual unit carried also has to be within the 'max' & 'min' weight limits of that Transport = see below)

power(ground | ship | air) = {n} (range, {eg 1-2})

This units 'attack' capability against each of the 3 main unit 'types'. When no (range) is given, the range defaults to 1. If no 'power() =' is defined against a 'type', the unit can't attack (or counter attack) that type (mkunitset.cpp sets range=0). For example (Artillery) :-

transslots = {n}

Defines this unit as a transporter type and sets the total 'weight' of units (or number of 'crystals') that can be carried by this unit.

Transport is one of the most flexible elements of Crimson Fields. It allows all sorts of 'clever tricks' to be pulled, from Pill Boxes and Bunkers, to Field Repair and Demolition Engineer units and Missile Batteries to Pontoon Bridge layers.

transminweight = {n}

The 'minimum' weight of a unit that can be carried by this Transporter.

Of course in 'real life' Transports would have no 'minimum' limits, so it's a bit unrealistic, however this (together with maxweight) allows you to control what a 'transporter' is 'allowed' to carry.
 
For example, transminweight = 2 is used to prevent Mines (weight 1) from being carried by Troopships or Aircraft Carriers
 
Each 'crystal' counts as weight = 1, but (since they are not units) the min. weight limit does not apply (i.e. all transports can carry up to transslots worth of crystals).

This prevents Boats, Transport Planes and APC's which can carry 'transslots' worth of 'low weight' units (so multiple Infantry) from carrying a single Heavy Tank or Artillery piece etc.

Only 4 units (artillery, fighter, infantry and rail-gun) currently have a 'portrait', however I guess there is no reason why they couldn't all have one (size = 300 x 168 pixels (except infantry = 168 x 300), so, at a guess, BMP portraits up to 300 x 300 pixels are supported)