Provided by:
crimson_0.4.8-1_i386 
NAME
cfed - a level compiler for Crimson Fields
SYNOPSIS
cfed mapsource --tiles tileset --units unitset [-o outfile]
cfed {--help | --version}
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 Format below). cfed reads the input file and
creates the level file. If the name of the ouput file is not given on
the command line, it is created in the same location as the source file
with the .src suffix substituted by .lev.
OPTIONS
--help Print a usage message on standard output and exit.
--tiles tileset
Use the tile definitions from tileset when compiling the map.
--units unitset
Use the unit definitions from unitset when compiling the map.
--version
Print version information on standard output and exit.
-o Set the name and path of the converted level file.
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 composed like
this:
qualifier = value
The only exceptions to this are the map and messages sections. 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 is mandatory and must
appear before the map section in the file. Valid qualifiers are
name index of a message containing the mission title. This name will
be used when presenting the list of available maps to the
player. (maximum length 30 characters, mandatory)
mapwidth
[10-200] (mandatory)
mapheight
[10-200] (mandatory)
nextmap
the name of another map (without path and file ending). After
the current map has been completed, this new map will be loaded
automatically. This tag is only valid for campaign maps.
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.
campaign
indicates whether the map is part of a campaign [0|1]. Default
is 0 (not part of a campaign). See also campaignname and
campaigninfo.
campaignname
index of the campaign name. It should be set only when the map
actually is the first of a campaign. See also campaign and
campaigninfo. (mandatory and valid only for the introductory map
of a campaign)
campaigninfo
index of the information message for the campaign. This info is
displayed when starting a new campaign and should contain a
short outline of the background story. It is useful only when
the map actually is the first of a campaign. See also campaign
and campaignname.
skirmish
indicates whether the map can be played in skirmish mode [0|1].
Default is 1 (true).
players
selects whether the map is intended for play against another
human being (2) or against the computer (1). This is for
informational purposes only and defaults to 2.
music name of a soundtrack (either MIDI or Ogg Vorbis) excluding the
file type suffix to be played during this map. If the setting is
missing, the default track for Crimson Fields will be played.
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’.
map
The map section defines the actual map layout. It is a rectangle of the
size specified in the mission section, consisting of various symbols
which describe a certain map tile type. The map section is mandatory
and may not contain 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
T road, n-s-se
U road, n-s-sw
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 characters.
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 index of a message containing the player name (mandatory,
maximum length 20 characters)
briefing
index of the player’s briefing message. The briefing can be
reviewed during the game by choosing the Briefing item from the
Game Menu. It is also recommended to create a message event to
tell the players about their objectives on the first turn (see
event and messages sections below). If omitted defaults to -1,
meaning that no briefing is available.
fcolor foreground color to use for this player in the format r,g,b,
e.g. 255,0,0 for red. The default player colors match the
default unit set, but different sets may use different color
schemes (also see bcolor).
bcolor background color to use for this player in the format r,g,b,
e.g. 0,0,255 for blue. The default player colors match the
default unit set, but different sets may use different color
schemes (also see fcolor).
unit
Each of these sections creates a unit on the map. Loaded transporter
units must be specified before any units they carry. Valid qualifiers
for units are
pos location of the unit on the map. If there is a building at the
given location, the unit will be 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 [x/y]. (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)
size number of vehicles for this unit [1-6]. Defaults to 6
(undamaged).
xp experience level this unit starts at [0-6]. Defaults to 0
(Rookie, no experience).
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 building (sometimes
also called a shop) on the map that units can enter. This is not
automatically done by placing the symbol for a building entrance in the
map section.
pos location of the building entrance on the map [x/y]. (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 buildings of type
Workshop. New units can be produced in buildings of type
Factory. A building may have multiple types. Defaults to Depot,
meaning no special attributes. In addition to these attributes,
a shop which produces crystals is (automatically) called a Mine.
name index of a message containing the shop name (mandatory, maximum
length 30 characters)
mining amount of crystals produced each turn [0-1000]. Defaults to 0.
If given, implies type Mine.
capacity
maximum amount of crystals [0-10000]. Defaults to 1000.
crystals
amount of crystals in stock [0-capacity]. Defaults to 0.
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 shop.
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. The event type defines what happens, the
event trigger controls when (or if) the event is executed.
Event Types
configure
dynamically change the setting for various internal strings
during the course of a game, e.g. the players’ mission
briefings.
createunit
create a unit somewhere on the map.
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.
research
make a new unit type available for production in a factory, or
remove it from the list of available units.
score award points to a player.
sethex change a tile on the map.
settimer
dynamically adjust the timer trigger of another event.
Event Triggers
handicap
the event is executed if the set handicap matches the current
game settings. Usually such an event is triggered immediately on
the first turn or not at all. You can, however, combine multiple
events (e.g. a handicap and a timer trigger) to change the
default behaviour.
havebuilding
the event is executed when the player controls a certain
building at a specified time.
haveunit
the event is executed when the player controls a certain unit at
a specified time.
timer the event is unconditionally executed at the specified time.
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.
The following list contains generic qualifiers which are valid for all
event types.
Qualifiers
id unique event identifier [0-200]. (mandatory)
type event type (mandatory, see below).
trigger
event trigger (mandatory). This describes the circumstances
under which the event is executed (see below).
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.
depend identifier of another event. This makes the current event depend
on the given event. Prior to event execution, the trigger
conditions for both events are checked, and the event is
activated only if both checks are successful. Mutual, circular,
and transitive dependencies are supported.
discard
identifier of another event. When the current event is executed,
the given event is discarded from the event stack and removed
from the mission.
flags event flags. Currently, the only available flag is 1 (disable).
A disabled event will never execute, regardless of the trigger
conditions.
In addition there are special qualifiers which can only be used with
certain event types or triggers. All of these are mandatory if nothing
else is stated.
action (manipulateevent, mining, research)
For manipulateevent 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 modify 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.
For research 0 allows and 1 disallows producing the specified
unit type. Default is 0.
building (mining, research)
Identifier of the building referenced in the event.
crystals (mining)
Amount of crystals. The action flag controls how this number is
actually interpreted.
eflags (manipulateevent)
Event flags to be modified. Currently the only legal value for
this is 1, the disable flag, which can be used to deactivate an
event. Disabled events won’t be triggered even if their trigger
conditions are met.
event (manipulateevent, settimer)
Identifier of the event to be modified.
face (createunit)
Direction the created unit faces [0-5]. Directions are numbered
clockwise from North (0) to Northwest (5). Optional, defaults to
0.
offset (settimer)
Offset to use when adjusting the timer. 0 means absolute, i.e.
set the trigger ttime to the value of time. 1 means execution
time, i.e. set it to the value of time plus the current time
index when executing the event. 2 means current trigger
configuration, i.e. add the time to the trigger ttime. Note that
if the target event is disabled, settimer will automatically
enable it.
othermsg (score)
For score events, one often wants to show a message not only to
the player who benefits from the event but also to his opponent.
Instead of creating a separate message event with inverted
trigger conditions you can use this qualifier and othertitle to
do just that (optional).
othertitle (score)
Index of the message title for the other player (optional, see
othermsg)
pos (createunit)
hex to create the unit on. The unit will only be created if the
target hex is empty at creation time or there is a shop or a
valid transporter which is controlled by the player for whom the
event is set up [x/y].
pos (message)
hex to focus the display on when showing the message [x/y]
(optional). If this parameter is absent the game will try to
guess a suitable hex from the trigger data, e.g. a havebuilding
trigger will cause it to use the shop location.
pos (sethex)
hex to change. If the hex is occupied by a unit at the time the
event is executed it may end up on terrain it would not normally
be able to enter [x/y].
setting (configure)
Name of the setting you wish to change. Valid names are
briefing1 for the briefing for the first player, briefing2 for
the objectives for the second player, and nextmap for the next
mission in a campaign.
size (createunit)
Unit group size [1-6]. Optional, defaults to 6.
success (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 (createunit, research)
Name of a unit type specification to build or make available,
respectively.
tbuilding (havebuilding)
Identifier of the building to be controlled.
thandicap (handicap)
Handicap setting to trigger the event [1 (none)|2 (player 1
handicapped)|4 (player 2 handicapped)]. You can add up the
numbers to trigger on more than one setting.
tile (sethex)
Identifier of the terrain the target hex will be changed to.
time (settimer)
Time index. The offset flag controls in what way this number is
used to adjust the targetted trigger.
towner (havebuilding, haveunit, unitdestroyed, unitposition)
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 required 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, while for
unitposition the default is the player owning the event. You
must supply this key for the other two trigger types.
ttime (havebuilding, haveunit, timer)
Time at which the event conditions should be checked. For timer
the event will always be executed at this time. Time calculation
starts with 0 at the start of a mission and increases by 1 each
time the players change. The movement phase of player 2 on turn
10 is at time index 19 ((turn - 1) * 2 + (player - 1)), for
example. (mandatory only for timer. If omitted for the other
triggers, the condition will be checked each turn.)
tunit (haveunit, unitdestroyed, unitposition)
Identifier of the unit to be targeted. 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 destination hex,
respectively. For these two triggers you can also use a unit
type, e.g. Infantry to target an entire unit class.
tpos (unitposition)
Coordinates of the target hex [x/y]
value (configure)
Index of the message to use as the new briefing when changing a
briefing, file name of the next mission (excluding the suffix)
when setting the next map.
xp (createunit)
Initial experience level [0-6]. Optional, defaults to 0.
messages
The messages section contains all text messages that may possibly be
displayed in the course of a mission. The format of this section
differs from that of the other sections. Here is an excerpt from an
imaginary level file.
[messages(en)]
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.
[/messages] this marks the end of the messages section
The two characters in brackets identify the language messages in this
section are written in. There is one messages section for each language
the mission supports. The (en) in the section title shows that this
section contains English messages. All messages must be encoded in
UTF-8.
EXAMPLE
### This is a simple example mission file
[mission]
# mission title is "The Great Example"
name = 5
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..
%%%%.%...**
### first player - The Good
[player]
name = 6
# second message is briefing for this player
briefing = 1
### second player - The Bad
[player]
name = 7
# third message is briefing for this player
briefing = 2
### units for player 1
[unit]
# this unit will start in the building
pos = 3/2
player = 1
id = 0
type = Infantry
[unit]
pos = 5/4
player = 1
id = 1
type = Medium Tanks
[unit]
pos = 6/3
player = 1
id = 2
type = Medium Tanks
[unit]
pos = 3/2
player = 1
id = 3
type = Scouts
### units for player 2
[unit]
pos = 7/7
player = 2
id = 10
type = Anti-Aircraft Tanks
[unit]
pos = 6/6
player = 2
id = 11
type = Personnel Carriers
[unit]
pos = 7/6
player = 2
id = 12
type = Infantry
[unit]
pos = 7/7
player = 2
id = 13
type = Heavy Tanks
### buildings
# HQ of the Good
[building]
name = 8
pos = 3/2
id = 0
player = 1
# can repair units here
type = workshop
crystals = 25
# HQ of the Bad
[building]
name = 9
pos = 7/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...
[event]
type = score
id = 0
player = 1
trigger = havebuilding
tbuilding = 1
towner = 1
# the next line could be left out
ttime = -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 = timer
ttime = 0
title = 5
message = 1
# Even though time index 0 is during player 1’s phase
# we want to trigger the message for player 2 as well.
# This way it gets queued for display during the turn
# replay. Otherwise player 2 would only see the briefing
# after his replay.
[event]
type = message
id = 5
player = 2
trigger = timer
ttime = 0
title = 5
message = 2
# we want to support difficulty levels (handicaps)
#
# if player 1 is handicapped we allocate some more
# crystals to players 2’s factory
[event]
type = mining
id = 6
player = 2
trigger = handicap
# 1 is no handicap, 2 is player 1, 4 is player 2
thandicap = 2
building = 1
action = 1
crystals = 35
# if player 2 is handicapped player 1 gets another tank
[event]
type = createunit
id = 7
player = 1
trigger = handicap
thandicap = 4
unit = Medium Tanks
pos = 3/2
### english messages
[messages(en)]
The Great Example
Revision 6 (16-08-2004)
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
%
The Good
%
The Bad
%
HQ of the Good
%
HQ of the Bad
[/messages]
NOTES
The file format of level files (source and data) is subject 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
again 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), bi2cf(6)
COPYRIGHT
Copyright © 2000-2005 Jens Granseuer
This software is distributed under the terms of the GNU General Public
License: http://www.gnu.org/copyleft/gpl.html (GPL).
AUTHOR
Jens Granseuer.
May 28 2005 CFED(6)