The Colossus File Formats

NOTE: THIS IS COMPLETELY OUT OF DATE. WE HAVE SWITCHED TO XML.

Romain Dolbeau

Introduction

This file documents file formats for the various datafile used by Colossus. In all these files, comments start with a "#" and extend to the end-of-line.

All files, and the two subdirectory "Battlelands" and "images" should be in the same directory. Default files live in "Default", "Default/images" and "Default/Battelands".

1 The `README` file

This file describe the variant. It can be either a pure text file or a HTML file. It must be named README, README.txt (both should be pure text) or README.html (should be HTML) and live in the same directory as the VAR file (see below, section ). It's displayed in the opening dialog.

2 `MAP` file format (default file used: "Default/Default.map")

This file defines the Colossus Masterboard ; what terrain type to use for an hex and what sort of exit to which hex. It's composed first of a pair of integers represanting the map size (horizontally then vertically), and then of a succession of lines:

<case_label> <terrain_name> <exit_1_label> <exit_1_type> <exit_2_label> <exit_2_type> <exit_3_label> <exit_3_type> <X_pos> <Y_pos>

All of those should be on one line.

<case_label> is the numeric label of the Hex.
<terrain_name> is the name of the terrain type of the hex (same as in the TER file).
<exit_N_label> are numeric labels for exits 1-3, or 0 for no (second, third) exit.
<exit_N_type> is the type of exits (ARROW, ARROWS, ARCH, BLOCK) ; for exit of label '0' (no exit) any of the four value can be used, as exit type is irrelevant.
<X_pos> and <Y_pos> is the position X, of the Hex on the masterboard. They both start from 'zero', on the first line and first column. Not all lines are different (i.e. on the default master board, case 126 and 125 are on the same line number 0 and on columns 4 and 3).

NOTE: Put at least MAXPLAYERS (see below the VAR file, section ) towers currently, as having less Towers than players is going to cause problems. The upper number is not constrained (or isn't supposed to be), and neither are the labels. For readability reasons, it's probably better to use 100 to 900 as the labels for the first 9 towers.

WARNING: The way the Hex are displayed (pointy part upside or downside) depend on the parity of the X+Y sum. It is possible to create a perfectly legit MAP where all the Hex are upside-down ! Should this happen, the only way to fix this 'feature' currently, is to move everything one column right or one row down, i.e., force the reversal of the parity. Sorry about that, the problem hasn't yet been solved.

3 `TER` file format (default file used: "Default/Default.ter")

This file define the Colossus Recruit Trees ; what can recruit and be recruited on what terrain. it's composed of a succession of line of four different kind. The first two are mandatory (at least one of each should appear), the other two are optional (default values are supplied).

The first kind is:

<terrain_color> <terrain_name> <regular_recruit> ( <recruiter_needed> <recruit>)+ <terrain_display_name >?

<terrain_color> is the color used to display this terrain type, see HTMLColor.java for the various available color.
<terrain_name> is the descriptive name of the terrain (Brush, ...) ; it is used also as the Battlelands file name. If <terrain_display_name> is not present, it is also used as the display name. Must be unique.
<regular_recruit>> is a boolean (i.e. true or false) telling if a Creature can recruit below or above its rank (usually true except for Tower).
<recruiter_needed> is the number of lower-rank creature needed to recruit the next creature.
<recruit> is the name of the recruit creature (Gargoyle, ...)
<terrain_display_name> is an optional string, used to display the name of the terrain on the MasterBoard, and as the name of the overlay file (see section "Images files" below). If absent, <terrain_name> is used instead.

The last two as a pair can be repeated any number of time. Any later creature can recruit a previous one or itself. A creature can recruit the next one only if they are numerous enough, as indicated by the <recruiter_needed> of the recruit.

Three specials names exist (pseudo-creature):

Anything, which means any creature can recruit the following creature provided they are numerous enough
AnyNonLord which is the same but excludes Immortal (Lord or DemiLord) from the possible recruiters
Lord which means a Lord (Angel, Titan, Archangel, etc., but not a Demilord) can recruit the following creature.

Note that for Lord and Titan, only one recruiter is needed, and the number before the recruits indicate how many of the creatures before Lord or Titan are needed.

When <recruiter_needed> is 0 (zero), then the creature can be recruited, but the recruiter will remain anonymous. This is useful only if the recruiter is Anything or AnyNonLord, of course. Don't use with a regular recruiter.

When <recruiter_needed> is -1 (minus one), then the creature can recruit, but cannot be recruited. Such creature, and the pseudo-creature above, are ignored for the purpose of normal recruitements. If you put Titan as a recruiter, it should always be -1, as beeing able to recruit Titan is going to cause lots of trouble.

Exemple: if you use 0 Anything 3 ogre 0 Titan 2 Gargoyle, you will be able to recruit an Ogre with any 3 creatures or with a Gargoyle, and you will be able to recruits a gargoyle with two Ogres or the Titan. You won't be able to recruit Anything or Titan, of course.

Any line that will be used as a Tower (See Battlelands below) should follow these rules: There should always be at least 3 regular creatures, recruitable with zero of Anything, at the begining. The line should be marked as "non-regular" recruitments. The 3 creatures will be used as starting creatures for the Player starting in that kind of Tower.

Both <terrain_name> and <terrain_display_name> can be either purely alphabetical, or alphanumerical plus spaces between doublequotes ""'. If a filename is involved, all spaces will be replaced by underscores "_".

The second kind is:

ACQUIRABLE <point_value> <acquirable_name> (( <terrain_name>,)* <terrain_name>)?

ACQUIRABLE is the literal string ACQUIRABLE

<point_value> is the amount of points needed to recruit the Acquirable
<acquirable_name> is the name of the Creature to consider as an Acquirable
<terrain_name> is an (optional) comma-separated list of terrain name (see above) that restrict the availability of the Acquirable. If the list is ommited, the Acquirable can be recruited everywhere.

Note that all <point_value> must be even multiple of the first <point_value> ; other values are erroneous and will be flagged as such. Also, the first acquirable creature should be a Lord, and is recruited in the starting stack (it's the 'primary' acquirable creature).

Multiple line can be present, in which case, the behavior is the same as if all the Acquirable where on one line. Order of Acquirable is not important, except for the first one, which defines the reference for <point_value> and the primary acquirable creature.

The third kind is:

TITANIMPROVE <point_value>

To give the amount of points required for the Titan to improve by one. Said differently, Titan power is equal to 6 + ( <player_points> / <above_value>). The default supplied value is 100.

The fourth kind is:

TITANTELEPORT <point_value>

To give the amount of points required for the Titan to be able to Titan Teleport. The default supplied value is 400.

4 `CRE` file format (default file used: "Default/Default.cre")

This file define the Colossus Creatures ; it's composed of a succession of lines:

<name> <power> <skill> <rangestrikes> <flies> <nativeBramble> <nativeDrift> <nativeBog > <nativeSandDune> <nativeSlope> <nativeVolcano> <nativeRiver> <nativeStone> <nativeTree> <waterDwelling> <magicMissile> <summonable> <lord > <demilord> <maxCount> <pluralName> ( <baseColorName>)?

all on one line.

<name> is the display name of the creature
<power> and <skill> are the numeric value of power and skill respectively.
<rangestrikes> <and flies> are boolean values ('true' or 'false'), defining if the creature can rangestrike or fly respectively.
<nativeXXX> are boolean values defining if the creature is native for terrain type XXX.
<waterDwelling> is a boolean value defining if the creature can live in water (i.e., Bog or Lake). Water Dweller don't like being dry, and as such take damage in Sand as other Creatures do in Drift.
<magicMissile> is a boolean value defining if the creature use magic missile, i.e. it can fires through anything (foe, obstacle, ...) toward anyone (including lord).
<summonable> is a boolean value defining if the creature can be summoned in a fight.
<lord> and <demilord> are boolean values, defining if the creature is a lord or a demilord (mutually exclusive).
<maxCount> is the max number of creature in the caretaker stack.
<pluralName> is the same as name, just plural.
<baseColorName> (optional) is the name of the color to use for the name, power and skill value of the creature (when displayed on screen). This name (is used to determine which overlay to use for name/power/skill, or which color to use for drawing them (black is the default in this case). If this field is not present, then no overlay are used: Colossus will assume a simgle image is enough to supply all informations.

Both <name> and <pluralName> can be either purely alphabetical, or alphanumerical plus spaces between doublequotes ""'. If a filename is involved, all spaces will be replaced by underscores "_".

5 Battleland file format (files used: by terrain name under "Battlelands")

These files define the Colossus Battlelands. they're composed of a succession of lines:

<X_pos> <Y_pos> <terrain_name> <terrain_elevation> ( <border_number> <border_type >)*

all on one line.

Any cas not mentioned in this file is assumed to be of type 'p', at elevation '0', and no border.

<X_pos> and <Y_pos> are the X and Y position of the modified case.
<terrain_name> is the terrain type of the case ; it's currently one of: Plains, Brambles, Sand, Tree, Bog, Volcano, Drift, Tower, Lake, Stone. Case is significant here.
<terrain_elevation> is the altitude of the terrain (between 0 and 2)

finally. between 0 and 6 pair of the form <border_number> <border_type>, where <border_number> is between 0 and 5 and <border_type> is currently one of: d, c, s, w, r (Dune, Cliff, Slope, Wall, River).

Lake, Stone and River are non-standard hazards:

Lake is impassable except by Water Dweller, and has no other effect.
Stone is impassable except by Stone Native, block rangestrike, and doesn't allow flying through (or over). A non-native attacking a Stone Native in a Stone loose one skill (both hand-to-hand and rangestrike).
River slows non-River Native non-Water Dweller crossing it.

Also, non-Tree Native attacking a Tree Native in a Tree lose one skill (but not rangestriker).

NOTE: There is a graphical tool, designed to allow easy creations of Battlelands. It doesn't handle Startlist yet (see below).

One more line exists: the startlist. It's a single line containing first the word STARTLIST, then a space-separated list of hex labels (one letter followed by one digit, displayed in each hexagon of the Battleland). This is where the Defender will enter the terrain. For instance, in the usual Titan Tower, the line used is:

STARTLIST D4 C4 E4 D3 C3 E3 D5

Also, the line imply the Attacker will enter by the bottom side. This is usually used for Tower, but can be used for other terrain as well.

Towers are denoted by the keyword TOWER by itself on a line. The terrain is then considered a Tower, i.e. you can Tower Teleport from it, and players are allowed to start in it.

6 `HINT` file format (default file used: "Default/Default.hin")

This file lists some hints to the Colossus AI on how to play the game.

The file is cut off into sections, each specifying behavior for one kind of AI. Any hints appearing before a section name is assumed to belong to section "AllAI:". A section name is a name ending in "AI:" ; known values are "AllAI:", "OffensiveAI:" and "DefensiveAI:". Any section name can be used, but if none of the AI is aware of a section, it won't be used. All AI will used hints from section "AllAI" as a last resort, after trying zero, one or more other section(s). Note that some AIs may ignore hints entirely, and some may decide to change the used sections in the middle of the game :-) A hint belongs to the last section whose name appears before the hint.

Each hint is a line of one of the forms:

RECRUIT <terrain_name> <recruiter_name> <recruiter_number> <recruitee_name> <optional_condition >

INITIALSPLIT <hex_label> <decimal_value> "(" <split_creature_name> * ")" *

RECRUITVALUE <creature_name> <value_offset>

where for RECRUIT:

<terrain_name> is the name of the terrain
<recruiter_name> is the name of the recruiting creature
<recruiter_number> is the number of recruiting creature
<recruitee_name> is the name of the suggested recruited creature

and <optional_condition> is an optional condition builded with the following <condition_node>:

( <condition_node> AND <condition_node> ) : both condition must be true.
( <condition_node> OR <condition_node> ) : one condition at least must be true.
( NOT <condition_node>) : the condition must be false.
( CANREACH <terrain_name> ) : The recruiting stack can reach at least one terrain of type <terrain_name> in the next turn.
( HASCREATURE <creature_name> ) : The stack already has one creature by the name of <creature_name>.
( OTHERSTACKHASCREATURE <creature_name>+ ) : A different stack from the same player already has at least one of each creature in the list of <creature_name>.
( RANDOM <decimal_value> ) : True (100 * <decimal_value>) % of the time ( <decimal_value> must be between 0.0 and 1.0).
( <number> <creature_name> AVAILABLE ) : At least <number> of the creature <creature_name> are available in the caretaker's stack.
( CANRECRUIT <creature_name> ) : The stack can also recruit the creature <creature_name>.
( HEIGHTIS <number> ) : The stack is exactly <number> in height.
( LABELIS <hex_label> ) : The stack is in hex <hex_label>.
( ALLATTACKERSMALLERTHAN <number> ) : The stack cannot by attacked by a stack more (strictly) than <number> in height. A value of 0 means that no enemy stack can attack.

If the recruitee's name is "nothing" or "Nothing", then the hint suggests not recruiting there.

where for INITIALSPLIT:

<hex_label> is the label of the Tower where the split occurs (should be quoted in double quote \", as most label are numbers).
<decimal_value> is the probability (between 0.0 and 1.0) of this split to occurs.
<split_creature_name> is the name of one splitted creature.

At the moment, there should be exactly two lists of exactly four creatures in the hint. The 8 creatures should be exactly one Titan, one Angel (those two in different stacks), and 2 of each of the three starting creatures of the Tower.

Each split for a given Tower is checked in order, and the first to pass the test is used, so the last one for each Tower should always use "1.0" as the probability.

where for RECRUITVALUE

The <creature_name> is the name of the affected creature, and the <value_offset> is how many points to add/retire to the normal value. This only affect the AI estimation of the recruitment value of the crature: a creature with a big positive value will be recruited before anything else, a creature with a big negative value will be recruited after anything else.

7 `VAR` file format (default file used: "Default/Default.var")

This file contains a variant definition, i.e. which MAP, CRE and TER file should be used and other informations such as which other variants are required.

Six different lines can exist, in any number and order (only the last one of each type is used):

CRE: <cre_filename>

MAP: <map_filename>

TER: <ter_filename>

HINT: <comma-separated list of hint_filenames>

DEPEND: <comma-separated list of dependecies>

MAXPLAYERS: <max number of players>

Note: if one of the first three type is missing, the Default file is implied. if DEPEND is missing, no dependencies are implied. In all case, the "Default" directory is looked-up last, so mentioning "Default" as a dependency is not required.

Note: Do not use a MAXPLAYERS value higher than the number of Tower in the MAP file, this will crash Colossus. If MAXPLAYERS isn't specified, 6 is the default value used. If MAXPLAYERS is too big for Colossus, the default maximum will be used instead to avoid crashing.

Exemple: A variant that use creatures from ExtTitan, Battlelands from Badlands and a local map could be described as:

CRE:ExtTitan.cre

MAP:MyBadlandsExtTitan.map

TER:Badlands.ter

DEPEND:ExtTitan,Badlands

8 Images files under "images"

Chit (i.e. images representing a Creature) should be non-transparent GIF file, size 60 * 60 (other size may work but won't look as nice). They should be named after the Creature they represent, with a ".gif" extension. If the file doesn't exist, troubles may occur. Also, see below for name/power/skill overlay.
Graphical Overlay for the Hexes on the Masterboard should be transparent GIF file, of size whatever-you-want (they are resized to the same size as the Hex the represent). Default supplied files are 255x255. Use them as examples of what is possible to do. If the file doesn't exist, the non-overlayed display is used instead (i.e. name of the terrain and the label in the proper corner).
Two version of the file should be supplied, one with and one without the "_i" postfix to the name (i.e 'MyTerrain.gif' and 'MyTerrain_i.gif'). The first is used when the biggest part of the hexagon is down, the second when the biggest part is up. The Display Name (see section 3 above, "TER file format") is used if present, and Name is used if not.
Graphical overlay for the Hexes on the Battlelands (aka Hazard) should be transparent GIF file, of size 216x188 for the interior of the hexes (Bog, Sand...), and size 248x220 for the hexsides (Cliff, Slope...). The filename should the name of the hazard followed by "_Hazard", followed by the extension ".gif" (for instance "MySea_Hazard.gif"). Only one version is needed.
Other sizes may work (they are resized on-the-fly), and odds are better if the aspect ratio is the same.
Skill, Power, and the name of creature are overlay added to the main Chit. If they are not available, they are created on the fly, using the color specified in the creature (see above the CRE file, section 4). You may supply none, any or all of them. Name should be respectively "Skill- <skill_factor >.gif", "Power- <power_factor>.gif", and " <creature_name>-Name.gif" for Creature which don't specify a color at all, or "Skill- <skill_factor>- <color_name>.gif", "Power- <power_factor>- <color_name>.gif", and " <creature_name>-Name- <color_name>.gif" for Creature with a color specified.

9 Miscellaneous stuff

A variant can customize the legion marker appearances and names. Legion markers are 56x56 GIF files that lives in "images" and are named with the marker short color name (see ) followed by its number (between 01 and 12), i.e. the first marker of the black set is Bk01.gif. The short name is mapped to a long name in the file "MarkersName", a java property file. A variant can supply its own "MarkersName", either fully or partially redefining the marker's names (the default mapping is used for missing entries).