This manual is for gamemasters. If you just want to play, please ask your gamemaster for more information.
This manual describes how to setup a game and how to host turns. For a quick start, check the example files provided together with the source code.
ambush_host definition-file map-file game-file orders-file
The distribution should contain sample files for all of the above.
Before running a game, you must do some preparation: You will need a to prepare some of the files needed when invoking the programm: The definition file which names the languages used in your game, defines weapons map symbols. The map file contains the map for the game. The game file contains changing data for the game: the number of soldiers, their attributes, their positions, their equipment. You will need a copy of each of these files to start playing. Start with the examples provided with the distribution.
A file describing the languages, weapons, map symbols, etc. of the game.
Comments start with a number sign '#'. Each line starts with the element class being defined. All elements are separated by commas.
Example:
LANGUAGE, Deutsch LANGUAGE, English
GUN, 1.00, 0.10, Gewehr, rifle GUN, 0.75, 0.10, Sturmgewehr, autorifle GUN, 0.70, 0.03, Maschinengewehr, machine gun
EDGE, W, -1, 0.00, 0.00, Wand, wall EDGE, F, 0.5, 1.00, 0.25, Fenster, window EDGE, T, 0.5, 1.00, 0.50, Türe, door EDGE, H, 0.5, 1.00, 0.50, Hecke, hedge
TIME, 60, 0.5
LANGUAGE: a language (one word).
These languages determine the number of names given to other elements. This will allow clients to produce reports in different languages.
GUN: accuracy (between 0.00 and 1.00), chances of jamming (between 0.00 and 1.00), names in all defined languages.
These define a weapon to shoot with. Chances of hitting are affected by visibility, not by distance.
EDGE: symbol on the map (one character), delay when crossing the edge (in seconds) or -1 for unpassable edges, visibility into neighboring square (between 0.00 and 1.00), visibility in all other cases (between 0.00 and 1.00), followed by possible names (ignored).
These define the symbols used in the map file. The map file syntax reserves symbols which you cannot use: A space (' ') is used to indicate 0 delay and 1.00 visibility. A plus ('+') is used to indicate the position of squares (the stuff between the edges). A number sign ('#') is used a comment character.
The two different visibility multiplicators allow the window-effect: right at the window your visibilty is not reduced when looking out; visibility is reduced when looking through windows farther away.
TIME: steps per turn (an integer), seconds per step (a number).
Both of these values are optional. If they are not given, a default of 60 steps per turn each taking 0.5 seconds is used. Therefore, players must provide their soldiers with orders for a total of 30 seconds each turn.
$language{$langname}: number of language
$gun{$no}{accuracy}
$gun{$no}{jamming}
$gun{$no}{name}{$langno}: weapon name for each language
$weapon_regexp{$langno}: regexp for weapons
$edge{$symbol}{delay}
$edge{$symbol}{visnigh}
$edge{$symbol}{visfar}
$steps_per_turn: how many steps to execute per turn $step_time: the time elapsed between each step (in seconds) $step_count: the number of steps executed this turn
A file describing a map to be used for the game. Soldiers are placed inside squares on the map. The file describes the edges of the squares. The edges determine line-of-sight and movement costs from any square to another.
The first line of the map indicates the dimensions of the map: first the width (east-west), then the height (north-south). The (1,1) square is in the bottom left corner (south-west corner).
A square is designated by a plus '+' on the map. They are all separated by one character which is either a space or a symbol defined in the definition file. Note that you cannot define the edges of squares that are also edges of the map.
Comments start with a number sign '#'. The map file may contain comments and empty lines before and after the map itself. The map consists of the line indicating the dimensions and all the lines needed to describe the entire map.
Example map based on the example definition file give elsewhere in this manual:
10 6
+ +W+ + +W+ +F+ + +
F W T
+ + + + + + +W+ + +
W W W T W
+ + + +F+ +W+ + + +
W T H H H
+ +W+ +W+ +W+H+ + +
W T W
+ +F+ + + + +H+ +W+
W W T
+ +W+F+ + +F+H+ +W+
$map{maxx}: size of map, X coordinate
$map{maxy}: size of map, Y coordinate
$map{$curx}{$cury}{east} : map symbol
$map{$curx}{$cury}{south} : map symbol
(not implemented yet)
A file describing the special areas on the map, the winning conditions for the teams and the number of turns the games has.
Comments start with a number sign '#'. Each line starts with the element class being defined. All elements are separated by commas.
Example teams based on the example game file give elsewhere in this manual:
DEFAULT, 10, 1 GOAL, 1, 4, 2, 6, 2 DESTROY, 9, 5, 1 START, 1, 4, 2, 6, 1 START, 8, 5, 10, 6, 2
DEFAULT: turn (a positive integer), and optionally a team number (a positive integer)
This defines the number of turns in the game. At the end of the turn indicated, the team give wins, if it still exists. If a team is given but all it's soldiers are eliminated, the game does not end. If no team number is given, the game does end.
GOAL: x1, y1, x2, and y2 coordinates of a goal area on the map, and optionally a team number (a positive integer).
This is a goal area for a team or for any single team. If all soldiers in the team are within the area at the end of a turn, that team wins. This is intended for patrol scenarios where one team has to cross the map and reach a goal area while the other teams try to intercept the patrol.
DESTROY: x and y coordinates of a square on the map, and optionally a team number (a positive integer).
If the specified team (or anybody, if no team was indicated) detonates an explosive in the exact square, the team wins. This is intended for sabotage missions where one team has to destroy a building while the other teams try to intercept it.
START: x1, y1, x2, and y2 coordinates of a start area on the map, and optionally a team number (a positive integer).
The specified team (or all teams, if no team was indicated) have to place their soldiers in the start area using the STARTAT command.
A file describing the teams and the soldiers on the map.
Comments start with a number sign '#'. Each line starts with the element class being defined. All elements are separated by commas.
Example weapons based on the example definition file give elsewhere in this manual:
TEAM, 1, a.schroeder@bsiag.ch, English, Cry Freedom, gg6543b TEAM, 2, sektat@bluewin.ch, Deutsch, Kondor, 976kj8
SOLDIER, 1, 0.7, 0.8, 2, 5, 100, 0, autorifle, Padooka SOLDIER, 1, 0.8, 0.5, 2, 2, 100, 0, rifle, Richfield SOLDIER, 1, 0.6, 0.8, 2, 3, 100, 0, autorifle, Bastinelli
SOLDIER, 2, 0.9, 0.6, 8, 6, 100, 0, Gewehr, Dumke SOLDIER, 2, 0.6, 0.8, 9, 5, 100, 0, Sturmgewehr, Reich SOLDIER, 2, 0.5, 0.7, 7, 5, 100, 0, Sturmgewehr, Kleindorf
TEAM: team number (a positive integer), language for reports and orders (as defined in the definition file), name of the team, password (a string) (all items are comma separated).
This defines a team.
SOLDIER: team number (of a defined team), accuracy when shooting guns of all types (between 0.00 and 1.00), endurance for the recovery of energy points (between 0.00 and 1.00), the X and Y coordinates on the map (both integers), energy points (an integer), wounds (an integer), a list of weapons, and the name of the soldier (the weapons and the name are comma separated).
These define a soldier in of teams, their position on the map and their current state.
The name of the game file should end in a number, such as game.0, turn.13, etc. This number will be incremented by one and used as the game file suffix the next turn is saved in.
$team{$no}{email}
$team{$no}{language}: language text
$team{$no}{name}
$team{$no}{passwd}
$teamid{name} = $no: Reverse lookup
$soldier{$no}{team}: team number
$soldier{$no}{accuracy}
$soldier{$no}{endurance}
$soldier{$no}{curx}: position, X coordinate
$soldier{$no}{cury}: position, Y coordinate
$soldier{$no}{energy}: energy points
$soldier{$no}{hits}: how many hits/wounds
$soldier{$no}{weapon}{$kind}: how many weapons of each kind
$soldier{$no}{name}
$soldierid{name} = $no: Reverse lookup
These are the two parts of the game file name. $turn is
incremented when the next turn is saved.
At the beginning of the turn, the visibilty from each square to each other square is calculated. This algorithm is currently very inefficient, but since it only has to run once per turn, that seems to be acceptable. The inefficieny of this algorithm both in terms of speed and storage requirements will limit the size of any maps used for the game.
Possible optimization strategies: When calculating the LOS between two squares, take advantage of similar lines of sight that coincide partially. Do this by calculating long lines of sight first, setting all other visibilities on the way.
$vision{$x1}{$y1}{$x2}{$y2} = 1.00
This hash is filled whenever new lines of sight have to be calculated. This
hash works like a cash for filling the %has_seen hash.
If the map changes, the %vision hash must be emptied!
This hash indicates, at which positions a team has detected enemy soldiers.
The following will pop one soldier after another from the list of soldiers
that $teamno_2 has seen.
$has_seen{$teamno}{$step_count}{$soldierno} = [ $curx, $cury ]
When this hash is filled, the value from the %vision hash is
used, if the looked-for value is defined, or the line of sight is
calculated anew and stored in the %vision hash.
In order to determine the visibility from square A to square B, draw a line from the middle of the square A to the middle of square B. This is the line of sight (LOS). All the edges this line crosses affect the visibility. If the LOS crosses a node, ie. a point where several edges meet, the edge with reduces visibility the most will affect visibility.
The first edge on the LOS is special: it will not affect visibility, as long as it does not block sight completely. This allows somebody standing behind a window to look through the window without being affected, while still reducing visibility for people far from the window looking in.
Orders arrive in emails. All the incoming orders are concatenated into one big file using a filter software such as procmail. This is the order file.
Each team must start writing orders using the TEAM keyword:
TEAM, name, password
This is followed by orders. These are written as follows:
COMMAND, name, command, comma-separated parameters...
The commands will all be appended to the command-stack of each man, unless the CLEAR command is given, in which case the command-stack is cleared. If the command-stack is not exhausted at the end of the turn, the command-stack will be saved and restored at the beginning of the next turn. This allows players to enter commands for as far ahead as they like.
Clears the command stack for the soldier.
COMMAND, Padooka, CLEAR
Fires a gun into the specified square for the numbers of seconds indicated.
A gun fires one shot per step, this is equivalent to 1 /
$step_time shots per second. After each shot the gun is
checked to see wether it unloads/jamms. If it does, 10 seconds are wasted
reloading/unjamming the gun.
COMMAND, Padooka, FIRE, 7, 5, 15
COMMAND, Padooka, RUN, s, 1
push @{$order{$soldierno}}, ['RUN', 3, 4];
You can define new commands for soldiers by adding keywords and subroutine
names to the global %order_function hash. Also, give your new
subrouting a priority in the %order_priority hash. Then, add
the subroutine to the source. These new subroutines will receive all the
parameters to the command in @_.
%order_function = ( RUN => 'cmd_run',
CLEAR => 'cmd_clear',
FIRE => 'cmd_fire' );
This determines the name of the subroutine, that will be called in order to
execute the command. If the command is done, it should be removed from the
%order hash (using pop). If one of the commands parameters is
a duration, such as ``wait for x seconds'' or ``fire at that spot for x seconds'',
this parameter should be updated for ongoing commands after spending a
timestep executing the command. This must be done in the subroutine
executing the command code.
%order_priority = ( RUN => 20,
CLEAR => 0,
FIRE => 60 );
This determines the priority of the command during one timestep. In the above example, all CLEAR commands will be executed. Then, all soldiers with a RUN command, will run a timestep. Those soldiers that had FIRE command, will fire afterwards. This is repeated until the turn is over. The orders of a given soldier may vary within one turn and within one timestep: A soldier given the commands CLEAR and RUN,7,3 will clear his commands when all CLEAR commands are executed. The command will be popped of his stack of orders. Then, as all RUN commands are executed, the soldier will run.
All messages are stored per team in the global %error hash.
push @{$error_msg{$team}}, "Another error!"
The reports are sent via mail. Players should also get a copy of the definition file and the mission file. Since these two files don't change in the course of game, they can be distributed together with the map. The files will help their clients to adapt to specific scenarios (eg. new edge types, new weapons, new languages).
All files will be created in the reports/ subdirectory.
send-reports: This is a shell script that will send the reports via email on UNIX-like systems. It is also created in the reports/ subdirectory.
report-X: report for faction X, also created in the reports/ subdirectory.
This is a version string for the reports. This allows clients to recognize when they have been outdated.