Provided by: crimson_0.4.8-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 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)