cfed - a level compiler for Crimson Fields


SYNOPSIS

       cfed [--help] [--version] source


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.


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
       is mandatory and must appear before the map section in the
       file. Valid qualifiers are

       title  mission title (maximum length 29 characters, manda­
              tory)

       mapwidth
              [10-200] (mandatory)

              [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
              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
              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
       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  con­
       tain comments. The following symbols exist.

        . - plains
        * - forest
        % - mountains
        - - 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
        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
       ypos   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. (mandatory)

       id     unique unit identifier. (mandatory)
              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. (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).
              Default value corresponds to building type.

       mining amount of crystals produced each turn. Defaults  to
              0. If given, implies type = Mine.

       crystals
              amount of crystals in stock. Defaults to 0.

              maximum amount of crystals. 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. Defaults to 0.

       maxweight
              weight of the heaviest unit allowed  to  enter  the
              building. 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. (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.
                Can be used to create

         research
                make  a new unit type available for production in
                a factory.

         score  award points to a player.

              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­
              tination hex, respectively.

       tbuilding
              only  for  trigger havebuilding.  Identifier of the
              building to be controlled.

              new owner of the building or unit is  the  same  as
              the  player  specified  here [1|2]. For the unitde­
              stroyed 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
              path  and suffix). The event then needs to know the
              message identifier.

       success
              only event score.  Amount  of  success  points  the

       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..
       %%%%.%...**


       ### first player
       [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

       [unit]
       xpos = 6
       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...
       [event]
       type = score
       player = 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
       player = 1
       trigger = unitdestroyed
       tunit = -1
       success = 100


       # player 2 wins if he conquers
       # the enemy building at any time...
       [event]
       type = score
       player = 2
       trigger = havebuilding
       tbuilding = 0
       towner = 2
       success = 100
       message = 3
       title = 4

       # ...or destroys all enemy units as well
       [event]
       type = score
       player = 2
       trigger = unitdestroyed
       tunit = -1
       success = 100

       # display briefings on first turn
       #
       [event]
       type = message
       player = 1
       trigger = turn
       tturn = 1
       title = 5
       message = 1

       [event]
       type = message
       player = 2
       trigger = turn
       tturn = 1
       title = 5

       [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!


SEE ALSO

       crimson(6)


COPYRIGHT

       Copyright © 2000-2003 Jens Granseuer

       This software is covered by the GNU General Public License
       (GPL).


AUTHOR

       Jens Granseuer <jensgr@gmx.net>