cfed - a level compiler for Crimson Fields
SYNOPSIS
cfed [--help|--version] MAPSOURCE --tileset TILESET
--units UNITSET
DESCRIPTION
cfed is the Crimson Fields level compiler.
It creates a *.lev file out of a source file *.src. You
can use any standard text editor to create the level
source files (for the syntax of those files, see FILE FOR
MAT below). cfed reads the input file and creates the
level file, which is named after the title given in the
mission description, to the current directory. You can
also have a look at the existing levels for more hints.
OPTIONS
--help Print a usage message on standard output and exit.
--version
Print version information on standard output and
exit.
--tiles
Set the name of the tile set to use (path inclu
sive). This parameter is mandatory.
--units
Set the name of the unit set to use (path inclu
sive). This parameter is mandatory.
FILE FORMAT
A level source file consists of sections. A section is
started by the section name in square brackets, i.e. the
line
[unit]
starts a unit section. Lines in a section are usually com
posed like this:
<qualifier> = <value>
The only exceptions to this are the map and messages sec
tions. Lines starting with # are considered comments. The
following sections exist:
mission
This section defines some global mission parameters like
map size or the graphics set to use. The mission section
title mission title (maximum length 29 characters, manda
tory)
mapwidth
[10-200] (mandatory)
mapheight
[10-200] (mandatory)
nextmap
index of a message containing the name of another
map (without path and file ending). After the cur
rent map has been completed, this new map will be
loaded automatically. If this tag is omitted, the
game will return to the main menu after the current
map.
info index of the information message that is to be
shown when a player requests level information.
This message can contain the level name, author,
revision, etc.
tileset
tileset file to be used. A tileset contains the map
graphics and terrain definitions. The filename must
be given without the .tiles suffix. If omitted, the
tile set defaults to 'default'.
unitset
unit set file to be used. A unit set contains the
unit graphics and definitions. The filename must be
given without the .units suffix. If omitted, the
unit set defaults to 'default'.
players
selects whether the map is intended for play
against another human being (2) or against the com
puter (1). This is for informational purposes only.
Defaults to 2.
password
A level may be protected by a password. This can be
used in campaign games to play maps in a specific
order. The password will not be checked if the map
is loaded via the nextmap flag above. Level pass
words must have exactly seven characters. All pro
tected maps should tell the player about the access
code in the level information message.
map
The map section defines the actual map layout. It is a
tile type. The map section is mandatory and may not con
tain comments. The following symbols exist.
. - plains
* - forest
% - mountains
= - shallow water
~ - water
- - deep water
# - swamp
" - cliff
0 - headquarters, neutral entrance, east
1 - headquarters, yellow entrance, east
2 - headquarters, blue entrance, east
3 - depot, neutral entrance, north
4 - depot, yellow entrance, north
5 - depot, blue entrance, north
6 - factory, neutral entrance, north
7 - factory, yellow entrance, north
8 - factory, blue entrance, north
9 - factory, neutral entrance, east
J - factory, yellow entrance, east
L - factory, blue entrance, east
A - city, yellow
B - city, blue
C - city, neutral
D - headquarters, yellow entrance, west
E - headquarters, blue entrance, west
F - headquarters, neutral entrance, west
G - headquarters, yellow entrance, north
H - headquarters, blue entrance, north
I - headquarters, neutral entrance, north
> - headquarters, east
< - headquarters, west
^ - headquarters, north
v - headquarters, south
\ - road, se-nw
| - road, s-n
/ - road, sw-ne
y - road, sw-n-ne
Y - road, se-n-nw
X - road, s-se-nw-n
x - road, s-sw-n-ne
o - road, sw-nw-ne-se
k - road, sw-s-ne
K - road, s-se-nw
( - road, n-se
) - road, n-sw
] - road, nw-s
[ - road, ne-s
n - road, sw-se
u - road, nw-ne
V - road, n-s-ne
W - road, n-s-nw
! - bridge, n-s
` - bridge, sw-ne
' - bridge, se-nw
a - fence, se-nw end
b - fence, nw-se end
c - fence, ne-sw end
d - fence, sw-ne end
e - fence, n-s
f - fence, sw-ne
g - fence, nw-se
h - fence, nw-s
i - fence, ne-s
j - fence, sw-n
l - fence, se-n
m - fence, nw-ne
p - fence, sw-se
There is also an alternative format. If the section is
called map-raw instead, the map is defined by giving the
hexagon identifiers directly, using the comma as a tile
separator. This approach requires intimate knowledge of
the tileset used and may break the map if the tileset
changes. The format has been created because there are now
more tiles than can be represented with single ASCII char
acters.
player
This can be used to set some player definitions. There may
be a maximum of two player sections in a file. The first
section encountered corresponds to the first player, the
next to the second. Valid qualifiers are
name player name. If omitted this defaults to 'Player 1'
or 'Player 2', depending on the position in the
file. (maximum length 15 characters)
briefing
index of the player's briefing message. The brief
ing can be reviewed during the game by choosing the
'Briefing' item from the Game Menu. It is also rec
ommended to create a message event to tell the
players about their objectives on the first turn
(see event and messages sections below). If omit
ted defaults to -1, meaning that no briefing is
available.
unit
Each of these sections creates a unit on the map. Valid
qualifiers are
xpos
put in. It is also possible to let units begin
inside a transport. In that case you have to make
sure, however, that in the level file the transport
is declared before the carried unit. (mandatory)
id unique unit identifier [0-10000]. (mandatory)
type unit type definition to use for this unit. Known
definitions for the default unit set are Infantry,
Medium Tanks, Heavy Tanks, Anti-Aircraft Tanks,
Anti-Aircraft Guns, Artillery, Mines, Patrol Boats,
Fighter Squadron, Personnel Carriers, Troopships,
Transport Planes, Scouts, Interceptors, Bunkers,
Torpedo Boats, Bomber Wing, Hovercraft, Gunships,
Troop Train, Rail Guns, Armoured Train,
Submarines, and Aircraft Carriers. (mandatory)
player unit controller [1|2]. (mandatory)
face direction the unit is heading [0-5]. Directions are
numbered clockwise from North (0) to Northwest (5).
Defaults are North (0) for units controlled by
player 1, and South (3) for the second player.
crystals
amount of crystals the unit carries. This may only
be given for transports and defaults to 0.
building
A building section is required to actually create a build
ing on the map that units can enter. This is not automati
cally done by placing the symbol for a building entrance
in the map section.
xpos
ypos location of the building entrance on the map.
(mandatory)
id unique building identifier [0-10000]. (mandatory)
player building controller [1|2|0]. Units starting in
unaligned buildings are automatically tagged
unaligned as well. (mandatory)
type type of building. Units can be repaired in build
ings of type 'Workshop'. New units can be produced
in buildings of type 'Factory'. Crystals can be
mined in units of type 'Mine'. A building may have
multiple types. Defaults to 'Depot', meaning no
special attributes.
name building name (maximum length 20 characters).
Defaults to 0. If given, implies type = Mine.
crystals
amount of crystals in stock [0-capacity]. Defaults
to 0.
capacity
maximum amount of crystals [0-10000]. Defaults to
1000.
factory
name of a unit type definition that can be built
here. If given, implies type = factory. Multiple
factory lines may be given for a building.
minweight
weight of the smallest unit allowed to enter the
building [0-99]. Defaults to 0.
maxweight
weight of the heaviest unit allowed to enter the
building [0-99]. Defaults to 99.
event
Events provide a way to interact with players during a
game. They can cause actions like points being awarded or
messages being displayed under certain conditions. Valid
qualifiers for all events are
id unique event identifier [0-200]. (mandatory)
player player the event belongs to [1|2]. (mandatory)
type event type (mandatory). Existing event types are
createunit
create a unit in a building. The unit will only
be created if the specified building is con
trolled by the player for whom the event is set
up.
manipulateevent
modify event internals. Currently this can be
used to dynamically enable or disable an event.
message
display a message.
mining set the amount of crystals for a building.
nextmap
change the setting for the next map to be played.
make a new unit type available for production in
a factory.
score award points to a player.
trigger
event trigger (mandatory). This describes the cir
cumstances under which the event is executed. Pos
sible triggers are
havebuilding
the event is executed when the player controls a
certain building on a specified turn.
haveunit
the event is executed when the player controls a
certain unit on a specified turn.
turn the event is executed on the specified turn.
unitdestroyed
the event is executed when a specified unit is
destroyed or captured by the enemy.
unitposition
the event is executed when a specified unit ends
its move on a certain target hex.
message
index of a message to be displayed when the event
occurs.
title title of the message window. Only useful when a
message is shown.
Apart from those there are qualifiers which are only valid
in conjunction with one or more of the above options. All
of these are mandatory if nothing else is stated.
tturn only for triggers turn, havebuilding, and haveunit.
Turn on which the event conditions should be
checked. For turn the event will always be executed
on this turn. (this is mandatory only for turn. If
it is omitted for the other triggers, the condition
will be checked each turn.)
tunit only for triggers haveunit, unitdestroyed, and
unitposition. Identifier of the unit to be tar
geted. For unitdestroyed and unitposition this may
take a value of -1 which will activate the event
when all enemy units have been destroyed or any
unit controlled by this player has reached the des
only for trigger havebuilding. Identifier of the
building to be controlled.
towner only for triggers havebuilding, haveunit, and unit
destroyed. The event will only occur if the new
owner of the building or unit is the same as the
player specified here [1|2]. For the unitdestroyed
trigger it is only supported if tunit is -1. In
this case you can select the player whose units
have to be destroyed to activate the event. This
setting may be omitted and defaults to the player
not owning the event. You must supply this key for
the other two trigger types, however.
txpos only for trigger unitposition. First coordinate of
the target hex.
typos only for trigger unitposition. Second coordinate
of the target hex.
action only events manipulateevent and mining. For manip
ulateevent this defines how to handle the specified
flags. A value of 0 will set, 1 will clear, and 2
will toggle the flags. For mining 0 will set the
crystal storage to an absolute amount, 1 will mod
ify the current amount by the given number, 2 will
set the mining rate, i.e. the amount mined each
turn, and 3 will change the current mining rate by
the given value. Minimum mining rate is 0, maximum
is 200.
building
only for createunit, mining, and research events.
Identifier of the building in which production
occurs.
crystals
only event mining. Amount of crystals. The action
flag controls how this number is actually used.
event only event manipulateevent. Identifier of the
event to be modified.
flags only event manipulateevent. Event flags to be mod
ified. Currently the only legal value for this is
1, the disable flag, which can be used to deacti
vate an event. Disabled events won't be triggered
even if their trigger conditions are met.
map only event nextmap. For this event you must create
a message in the messages section which contains
the name of the map to be loaded (excluding file
success
only event score. Amount of success points the
player receives when the event occurs. Any player
with a success score of 100 or more wins the game.
unit only events createunit and production(unit). Name
of a unit type specification to build or make
available, respectively.
messages
The messages section contains all text messages that may
possibly be displayed in the course of a mission. The for
mat of this section differs from that of the other sec
tions. Here is an excerpt from an imaginary level file.
[messages]
This is a message.
% this line separates messages
This is the second message.
% separator lines can be used for comments
This is the third message,
containing a line break.
%% this marks the end of the messages section
A single message may be up to 1800 characters long.
EXAMPLE
### This is a simple example mission file
[mission]
title = Example
mapwidth = 11
mapheight = 10
# the first message in the [messages] section
# will be used as level information
info = 0
# we use the default tileset and unit set so we could
# omit the next two lines
tileset = default
unitset = default
[map]
***...***..
**...****.=
*<^1n]*..==
**v..(..==~
***...].=~~
#=#.==!====
======(]...
%*.=...E^>.
%%..%...v..
[player]
name = The Good
# second message is briefing for this player
briefing = 1
### second player
[player]
name = The Bad
# third message is briefing for this player
briefing = 2
### units for player 1
[unit]
# this unit will start in the building
xpos = 3
ypos = 2
player = 1
id = 0
type = infantry
[unit]
xpos = 5
ypos = 4
player = 1
id = 1
type = medium tanks
[unit]
xpos = 6
ypos = 3
player = 1
id = 2
type = medium tanks
[unit]
xpos = 3
ypos = 2
player = 1
id = 3
type = scouts
### units for player 2
[unit]
xpos = 7
ypos = 7
player = 2
id = 10
type = anti-aircraft tanks
xpos = 6
ypos = 6
player = 2
id = 11
type = personnel carriers
[unit]
xpos = 7
ypos = 6
player = 2
id = 12
type = infantry
[unit]
xpos = 7
ypos = 7
player = 2
id = 13
type = heavy tanks
### buildings
[building]
name = HQ of the Good
xpos = 3
ypos = 2
id = 0
player = 1
# can repair units here
type = workshop
crystals = 25
[building]
name = HQ of the Bad
xpos = 7
ypos = 7
id = 1
player = 2
# can repair and build units
type = workshop
type = factory
# the following units can be built
factory = personnel carriers
factory = anti-aircraft guns
factory = bomber wing
crystals = 25
### events
# player 1 wins if he conquers
# the enemy building at any time...
id = 0
player = 1
trigger = havebuilding
tbuilding = 1
towner = 1
# the next line could be left out
tturn = -1
success = 100
message = 3
title = 4
# ...or destroys all enemy units
[event]
type = score
id = 1
player = 1
trigger = unitdestroyed
tunit = -1
success = 100
# player 2 wins if he conquers
# the enemy building at any time...
[event]
type = score
id = 2
player = 2
trigger = havebuilding
tbuilding = 0
towner = 2
success = 100
message = 3
title = 4
# ...or destroys all enemy units as well
[event]
type = score
id = 3
player = 2
trigger = unitdestroyed
tunit = -1
success = 100
# display briefings on first turn
#
[event]
type = message
id = 4
player = 1
trigger = turn
tturn = 1
title = 5
type = message
id = 5
player = 2
trigger = turn
tturn = 1
title = 5
message = 2
### messages
[messages]
The Great Example
Revision 3 (27-09-2002)
by Jens Granseuer <jensgr@gmx.net>
%
This is a nice introductory message, so that player 1 knows what he is expected to do. Word wraps are done automatically, so don't include line breaks if you don't want them. So, Player 1, let's take them apart:
Either conquer the enemy headquarters or destroy all their troops.
%
This should present the situation to player 2.
You are being attacked. Defend yourself. The attack is considered repelled if you gain control of the enemy headquarters or the entire attacking army is no more.
%
This is the success message for conquering the enemy headquarters.
Congratulations!
%
Hip! Hip! Hurrah!
%
The Great Example
%%
NOTES
The file format of level files (source and data) is sub
ject to change without notice. If you get an error 'File
not of the required type', it mostly should be sufficient
to feed the appropriate source file to cfed to create a
valid level file. However, no promises are being made.
You have been warned!
cfed will eventually be phased out in favour of CoMET, the
graphical map editor for crimson.
SEE ALSO
crimson(6)
COPYRIGHT
Copyright © 2000-2003 Jens Granseuer <jensgr@gmx.net>
This software is covered by the GNU General Public License
(GPL).