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).