Home and Links
 Your PC and Security
 Server NAS
 DVD making
 Raspberry Pi
 PIC projects
 Other projects
 Next >>
[Defining Units] [Unit artwork] [The 'transparent' colour] [Compiling Units] [Linking Units to maps] [Unit definitions] [[unitset]] [name =] [icons =] [[unit]] [name =] [type =] [icon =] [terrain = {terrain 'type'}] [armour = {n >= 1}] [speed = {n}] [price = {n}] [weight = {0-99}] [power] [transslots = {n}] [transminweight = {n}] [transmaxweight = {n}] [portrait = {eg. u artillery.bmp}]
CF Unit defn.

Defining Units

The unit definition data consists of 2 files, the icons in /gfx/CFUnits.bmp (images) and the unit control parameters in /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. Both players have exactly the same unit types and unit definitions (the only difference is the 'icon').

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 'double used' (i.e. you can define multiple different Unit parameter sets, with different names, that use the same icon - for example 'Spitfire' and 'FW190' could both use the same 'fighter' icon).


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


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 :-)


Compiling Units

The bit-map sources (CFUnits.bmp & all the u_xxxx.bmp portraits) are combined with the unit control data (default.tsrc) to create the 'default.units' file. This is controlled by \tools\Makefile which invokes the 'mkunitset.exe' utility (which is built from mkunitset.cpp)

'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


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, it's the unit (English) names that are added to the text based map 'source' ('.src') files and only when the map 'source' is converted into a play level (*.lev) file that the unit name is replaced with it's ID code

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 compile 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


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



Indicates the start of the definitions set. Appears once.

name =

The 'name' of this definitions 'set' (seems to be arbitrary)

icons =

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



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 =).

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' - for example, a 'type = ground' unit can only be attacked (or counter-attacked) by other units that have a 'power(ground)' capability.

It does not determine the type of 'terrain' a unit may cross - that is defined separately (see later, theres nothing to stop you giving a 'ground' unit (eg tank) the ability to cross rivers ('shallow water')), although Units defined as 'type=aircraft' can cross any terrain

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

'trooper' = this unit can capture buildings
'slow' = this unit can not move and attack or fire in the same turn
'mine'** = this unit unit that can be 'deployed' or 'swept'
'sweeper' = this unit that can pick up other units defined as 'type=mine'
'medic' = if this is a transport*** unit (that is carrying at least 5 'crystals'****) it can 'repair' another unit it is carrying (so you can create a 'mobile repair workshop' ...)

** see at end re: The problem with mines
*** 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.

icon =

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

Bitmap 'icons' in CFUnits.bmp start from 0, so Medium Tanks 'icon = 0' and use bitmap's 0-11, Infantry has 'icon = 12' (and 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 = {terrain 'type'}

This defines one of the terrain 'types' that this unit is 'allowed' to enter**. Units will typically have multiple 'terrain =' values. If the unit is faced with terrain of a 'type' not listed, then that unit can not enter that 'type' of terrain

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

The terrain types are:- road, rails, plains, forest, mountains, swamp, water, shallowwater, deepwater, rough, trenches

In addition to a 'type', each terrain tiles has a 'move cost' associated with it = so multiple different tiles of the same basic 'type' can exist (eg 'plains' can be anything from 'grass' to 'stony ground' to 'hard sand', and 'swamp' can be anything from 'boggy ground' up to 'quicksand')
When calculating moves, the 'cost' of entering each Tile is deducted from the Units movement 'allowance'. Movement ends when the unit has insufficient allowance left to enter the next tile.
As a result, a unit will often move 'up to' a 'high cost' tile (eg barbed wire) and stop, then move across the tile on the next turn

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

For example, when I added 'shallow water' capability to APC's & medium tanks to turn them into 'amphibious vehicles' for my WW2 maps, I discovered the AI moving it's tanks 'up river' :-)
This is because river tiles are defined as 'shallowwater' that normally only ship types would be allowed to enter. So the fact that the 'cost' of moving in shallowwater was less than the 'cost' of moving on 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 tiles with one of the 3 'water' types so that movement through them cost more than moving over land. This then required I adjust the movement 'allowances' of all 'ship' units to compensate.
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 'defense strength' against all attackers, integer, 1 or above (0 will crash the game when the unit enters combat)

Note that each terrain tile can have 'combat modifiers' which adjust both attack and defense values of the unit 'in' that tile

speed = {n}

Movement allowance per turn (can be 0).

Units such as mines and pillboxes have speed 0. Units with a speed=0 can be 'deployed' from a transporter only if they are defined as 'type=mine' (and are 'allowed' to enter that terrain type)

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)

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' plus each unit carried 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).

transslots = {n}

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

Transport is one of the most flexible parts of Crimson Fields - it allows all sorts of 'clever tricks' to be pulled, from Field Repair to 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 (togther with maxweight) allows you to control what a 'transporter' is 'allowed' to carry.   For example, transminweight is used to prevent Mines (weight 1) from being carried by Troopships or Aircraft Carriers

transmaxweight = {n}

The maximum weight of an individual unit that may be carried

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.

portrait = {eg. u_artillery.bmp}

The bit-map 'cartoon' image to be shown when the 'details' option is clicked for this unit.

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, portraits up to 300x300 are supported)

Clicking "Next >>" (nav bar, bottom left) will take you to my Crimson Fields Terrain file definitions Page

Next page :- CF Terrain tiles