cfed — a level compiler for Crimson Fields
cfed mapsource --tiles tileset --units unitset
cfed { --help | --version }
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, 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.
Print a usage message on standard output and exit.
Use the tile definitions from tileset when compiling the map.
Use the unit definitions from unitset when compiling the map.
Print version information on standard output and exit.
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:
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
mission title (maximum length 29 characters, mandatory)
[10-200] (mandatory)
[10-200] (mandatory)
index of a message containing the name of another map (without path and file ending). After the current 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.
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.
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 passwords must have exactly seven characters. All protected maps should tell the player about the access code in the level information message.
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.
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'.
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'.
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
headquarters, neutral entrance, east
headquarters, yellow entrance, east
headquarters, blue entrance, east
depot, neutral entrance, north
depot, yellow entrance, north
depot, blue entrance, north
factory, neutral entrance, north
factory, yellow entrance, north
factory, blue entrance, north
factory, neutral entrance, east
factory, yellow entrance, east
factory, blue entrance, east
city, yellow
city, blue
city, neutral
headquarters, yellow entrance, west
headquarters, blue entrance, west
headquarters, neutral entrance, west
headquarters, yellow entrance, north
headquarters, blue entrance, north
headquarters, neutral entrance, north
headquarters, east
headquarters, west
headquarters, north
headquarters, south
road, se-nw
road, s-n
road, sw-ne
road, sw-n-ne
road, se-n-nw
road, s-se-nw-n
road, s-sw-n-ne
road, sw-nw-ne-se
road, sw-s-ne
road, s-se-nw
road, n-se
road, n-sw
road, nw-s
road, ne-s
road, sw-se
road, nw-ne
road, n-s-se
road, n-s-sw
road, n-s-ne
road, n-s-nw
bridge, n-s
bridge, sw-ne
bridge, se-nw
fence, se-nw end
fence, nw-se end
fence, ne-sw end
fence, sw-ne end
fence, n-s
fence, sw-ne
fence, nw-se
fence, nw-s
fence, ne-s
fence, sw-n
fence, se-n
fence, nw-ne
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.
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
player name. If omitted this defaults to 'Player 1' or 'Player 2', depending on the position in the file. (maximum length 15 characters)
index of the player's briefing message. The briefing can be reviewed during the game by choosing the 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.
item from the Menu. It is also recommended to create aEach of these sections creates a unit on the map. Valid qualifiers are
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)
unique unit identifier [0-10000]. (mandatory)
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)
unit controller [1|2]. (mandatory)
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.
amount of crystals the unit carries. This may only be given for transports and defaults to 0.
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.
location of the building entrance on the map. (mandatory)
unique building identifier [0-10000]. (mandatory)
building controller [1|2|0]. Units starting in unaligned buildings are automatically tagged unaligned as well. (mandatory)
type of building. Units can be repaired in buildings of type Workshop. New units can be produced in buildings of type Factory. Crystals can be mined in shops of type Mine. A building may have multiple types. Defaults to Depot, meaning no special attributes.
building name (maximum length 20 characters). Default value corresponds to building type.
amount of crystals produced each turn [0-1000]. Defaults to 0. If given, implies type = Mine.
maximum amount of crystals [0-10000]. Defaults to 1000.
amount of crystals in stock [0-capacity]. Defaults to 0.
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.
weight of the smallest unit allowed to enter the building [0-99]. Defaults to 0.
weight of the heaviest unit allowed to enter the building [0-99]. Defaults to 99.
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
create a unit in a building. The unit will only be created if the specified building is controlled by the player for whom the event is set up.
modify event internals. Currently this can be used to dynamically enable or disable an event.
display a message.
set the amount of crystals for a building.
change the setting for the next map to be played. Can be used to create dynamic campaigns.
make a new unit type available for production in a factory.
award points to a player.
Event Triggers
the event is executed when the player controls a certain building on a specified turn.
the event is executed when the player controls a certain unit on a specified turn.
the event is unconditionally executed on the specified turn.
the event is executed when a specified unit is destroyed or captured by the enemy.
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
unique event identifier [0-200]. (mandatory)
event type (mandatory, see below).
event trigger (mandatory). This describes the circumstances under which the event is executed (see below).
index of a message to be displayed when the event occurs.
title of the message window. Only useful when a message is shown.
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 are successful. Mutual, circular, and transitive dependencies are supported.
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.
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.
Identifier of the building referenced in the event.
Amount of crystals. The action flag controls how this number is actually interpreted.
Identifier of the event to be modified.
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.
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.
Amount of success points the player receives when the event occurs. Any player with a success score of 100 or more wins the game.
Name of a unit type specification to build or make available, respectively.
Identifier of the building to be controlled.
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 otherwise. You must supply this key for the other two trigger types.
Turn on which the event conditions should be checked. For turn the event will always be executed on this turn. (mandatory only for turn. If omitted for the other triggers, the condition will be checked each turn.)
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.
Coordinates of the target hex
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] 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.
### 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] 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 [unit] 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... [event] type = score 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 message = 1 [event] 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 %%
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.
crimson(6), bi2cf(6)
Copyright © 2000-2003 Jens Granseuer
This software is distributed under the terms of the GNU General Public License (GPL).