Provided by: crimson_0.5.2-1_i386 bug

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 the section called “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.

       destroyunit
           destroy a unit and remove it from 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.

       havecrystals
           the event is executed when the player owns a certain amount of
           crystals.

       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)

       owner (destroyunit)
           Only destroy the unit if it is controlled by this player [1,2,-1].
           Optional, default is any player (-1).

       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 (destroyunit)
           hex to destroy the unit on [x/y]. The pos parameter can only be
           used if unit is -1.

       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.

       unit (destroyunit)
           Identifier of the unit to be destroyed. Set to -1 and configure the
           pos parameter to destroy a unit in a specified location instead.

       tbuilding (havebuilding, havecrystals)
           Identifier of the building to be controlled. For havecrystals this
           parameter may be set to -1 to check all shops a player controls, or
           to -2 to check all shops and all transporters anywhere on the map.

       tcrystals (havecrystals)
           Amount of crystals needed to trigger the event [-5000-5000]. If the
           amount given is greater than 0 the player needs at least that many
           crystals. If it is negative, the event occurs when the player’s
           resources drop below the absolute number.

       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, havecrystals, haveunit, unitdestroyed,
       unitposition)
           The event will only occur if the 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 havecrystals and 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-2007 Jens Granseuer

       This software is distributed under the terms of the GNU General Public
       License[1] (GPL).

AUTHOR

       Jens Granseuer <jensgr@gmx.net>
           Author.

REFERENCES

        1. GNU General Public License
           http://www.gnu.org/copyleft/gpl.html

                                January 18 2007                        CFED(6)