Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1999 lines (1993 sloc) 61.6 KB

Map XML and Custom Maps Documentation :: Quick Nav



3.1 How TripleA Locates its Root Directory

It may be of some interest to some developers to know exactly how TripleA locates where its own root directory is. This will help those who like to put the start-up scripts in different directories.

The search algorithm works from the inside out and is located in the GameRunner.java source file. It will start from the package location of GameRunner.class and move up one level until it has reached the root package. Once there, that will be TripleA's root directory. It then checks to make sure that the root directory it found actually exists, if not then return the current user's home directory and display an error message.

This way the root directory doesn't have to be hard coded.

File Name GameRunner.java
Package games.strategy.engine.framework
Method Header public static File getRootFolder()
/**
 * Get the root folder for the application
 */
public static File getRootFolder(){
	//we know that the class file is in a directory one above the games root folder
	//so navigate up from the class file, and we have root.
	//find the url of our class
	URL url = GameRunner.class.getResource("GameRunner.class");
	//we want to move up 1 directory for each package
	int moveUpCount = GameRunner.class.getName().split("\\.").length + 1;
	String fileName = url.getFile();
	try {
		//deal with spaces in the file name which would be url encoded
		fileName  = URLDecoder.decode(fileName, "UTF-8");
	} catch (UnsupportedEncodingException e){
		e.printStackTrace();
	}
	//we are in a jar file
	if(fileName.indexOf("triplea.jar!") != -1){
		String subString = fileName.substring("file:/".length()  - ( isWindows() ? 0 : 1)  , fileName.indexOf("triplea.jar!") -1);
		File f = new File(subString).getParentFile();
		if(!f.exists()){
			throw new IllegalStateException("File not found:" + f);
		}
		return f;
	} else{
		File f = new File(fileName);
		for(int i = 0; i < moveUpCount; i++){
			f = f.getParentFile();
		}
		if(!f.exists()) {
			System.err.println("Could not find root folder, does  not exist:" + f);
			return new File(System.getProperties().getProperty("user.dir"));
		}
		return f;
	}
}

5.0 Creating Custom Games

There are three different ways of creating custom games in TripleA.

  1. Customizing in game values only
  2. Customizing values, map, but use an existing rules base
  3. Customize the values, map, and the rules base

1: Customizing in game values only

This refers to making changes to the game only through the XML game file. It is a quick and easy way to modify an existing game without the hassle of modifying code or re-compiling. However, the game logic, images, and maps cannot be modified through XML changes alone. The user will be bound to using the same game logic, images, and maps of the XML game file they are editing.

2: Customizing values, map, but use an existing rules base

In addition to making changes through the XML file, this also requires one to make changes to the images and maps that the game will use. This is where a user can add their own customized map, and perhaps some customized units. However, even though this allows one more customization it still leaves the user bound to some existing game logic. (ie, Pact of Steel and BigWorld 1942 uses customized images, maps, and XML files but are still bound to the game logic of TripleA's standard rules.)

3: Customize the values, map, and the rules base

This method encompasses changing XML values, images, maps, and game logic. It requires the user to modify images and create new (or modify existing) Java classes to handle different, more, or new types of game logic for the engine to interpret.

5.1 Map Utilities

TripleA comes with several utilities for editing maps. In brief, these utilities will allow the user to create center points and names for each territory, and break the map up into 256x256 sized tiles.

There are seven utilities that can be used:

  1. Center Picker : Picks center points for each territory
  2. Polygon Grabber : Grabs the (x,y) polygonal values of each territory
  3. Placement Picker : Picks placement for units (manually)
  4. Auto-Placement Finder : Picks placement for units (automatic)
  5. Tile Image Breaker : Breaks the map into 256x256 tiles
  6. Relief Image Breaker : Creates relief 256x256 tiles
  7. Image Shrinker : Creates a mini-sized map image

All images are in PNG format except for the mini-map image produced by the Image Shrinker utility, it is in JPEG format.

Pre-requisite !

A pre-made map needs to be created for the utilities to work. The map needs to have black borders separating each territory. This needs to be completely black as in #000000 or R=0 G=0 B=0. The insides of the territories should be white and the oceans or water values need to be colored.

You should run the map utilities using a binary (not source) distribution of TripleA.

5.1.1 Center Picker

Run the center picker from the bin directory.


How to run Center Picker
cd bin
java -Xmx512m -classpath triplea.jar util/image/CenterPicker

center picker
Fig 5.1.1.0

Execution flow of the Center Picker is listed below.


Program Action User Action
1 Show a "Select Map File" dialog 2 Select a map image file
3 Show a "Select Polygons File" dialog 4 Select a polygons.txt file or cancel and run without.
5 Show map image 6 Left or Right click on any territory to create a center point
7 Show a dialog box with a default territory name 8 Put a new territory name and press "OK"
9 Show confirmation dialog 10 Confirm with "Yes", or cancel with "No" or "Cancel"
11 Show red dot on territory    

After creating center points for all the territories, proceed to save them. The center picker will ask for a directory to save the center points. These center points will be needed for other map utilities later on, and for TripleA it self to run the game.

5.1.2 Polygon Grabber

Run the polygon grabber from the bin directory.

How to run Polygon Grabber
cd bin
java -Xmx512m -classpath triplea.jar util/image/PolygonGrabber

polygon grabber
Fig 5.1.2.0

Execution flow of the Polygon Grabber is listed below.


Program Action User Action
1 Show a "Select Map File" dialog 2 Select a map image file
3 Show a "Select Centers File" dialog 4 Select a centers.txt file
5 Show map image 6 Left click on any territory to select it
7 Selected territory is highlighted in red 8 Right click on highlighted territory (hold shift for more)
9 Show name option dialog 10 Confirm if territory name is correct
11 Highlight selected territory in yellow 12 Go to next territory

The polygon grabber utility comes with a special "Island Mode" feature. It has been known that when dealing with many islands in one sea zone causes a visual problem. Doing the sea zone first will cover up any islands inside. This will leave the user unaware if the islands have been selected or not. The "Island Mode" feature helps over come this by out-lining selected territories in red and not filling them in with yellow, as is the default. Look at figures 5.1.2.1 and 5.1.2.2 for examples of "Island Mode" at work.

island mode 1
Fig 5.1.2.1

island mode 2
Fig 5.1.2.2

Notice how in figure 5.1.2.1 one of Sardinia's islands was covered up when the sea zone was done first. Island mode helped show the covered up island and allowed us to select it.

When done, save the polygon points to disk.

5.1.3 Placement Picker

Run the placement picker from the bin directory.



How to run Placement Picker
cd bin
java -Xmx512m -classpath triplea.jar util/image/PlacementPicker

Placement Picker commands are as follows:

Command Result
Left Mouse Button Start in this territory
CTRL + Left Mouse Button Add a placement point to the list
Right Mouse Button Remove last placement point
CTRL + Right Mouse Button Save placement points for that territory

Figure 5.1.3.0 shows an example of U.K. with its placements done.

placement picker
Fig 5.1.3.0

When done save the placement points to disk.

5.1.4 Auto-Placement Finder

The auto-placement finder can be used instead of the placement picker. It automates the placement picking procedure and picks what it chooses to be the optimal placement points.

There are some pre-requisites that need to be fulfilled before running the auto-placement finder:

  1. The centers.txt and polygons.txt files exist
  2. The place.txt file exists, even if it is empty. It will crash without one
  3. The above text files need to be in their finalized map directory

Step No.3 is a bit confusing to explain explicitly in this section. This will be covered in Section 5.1.8 (Making a Map).

Run the placement picker from the bin directory. When run it will ask for the map name, this relates to the name of the folder it is in. For example, revised would be entered if we wanted it to find placements for the A&A Revised map, which in turn would have all the text files inside triplea_0_6_0_1/maps/revised



How to run Auto-Placement Finder
cd bin
java -Xmx512m -classpath triplea.jar util/image/AutoPlacementFinder

auto-placement finder
Fig 5.1.4.0

When the auto-placement finder is done creating the placement points, it will prompt a dialog in order to save the placement points to disk.

5.1.5 Tile Image Breaker

This utility will break up the original large map into tiles of size 256x256 so that it can be used by TripleA. There are not any special prerequisites to use this utility other than running it and choosing the correct map for it to break up.

How to run Tile Image Breaker
cd bin
java -Xmx512m -classpath triplea.jar util/image/TileImageBreaker

Program Action User Action
1 Show a "Folder Save Location" dialog 2 Select a directory to save the tiles
3 Show a "Select Map File" dialog 4 Select a map image
5 Process map and break into tiles 6 Wait until finished

Once the Tile Image Breaker is done, all the tiles will be saved in the directory that has been selected at the start.

5.1.6 Relief Image Breaker

The relief image breaker is an optional utility that can be used when creating custom maps. Normally, the tile image breaker is enough to make a working map. It will be a very plain map with solid colors. To make a map with relief images allows for more eye-candy features. Relief images can be toggled ON and OFF from inside TripleA, this means that if there needs to be two identical maps: one plain, the other with some eye-candy feature (ie. textured terrain.)

Some prerequisites before using the relief image breaker:

  1. A plain map
  2. Another map with eye-candy features
  3. The centers.txt, polygons.txt, and place.txt in their finalized map directory

More about the "finalized map directory" will be covered in Section 5.1.8 (Making a Map).

How to run Relief Image Breaker
cd bin
java -Xmx512m -classpath triplea.jar util/image/ReliefImageBreaker

Program Action User Action
1 Show a "Folder Save Location" dialog 2 Select a directory to save the relief tiles
3 Show a "Select Map File" dialog 4 Select a relief map image
5 Ask if it should process Sea Zones only 6 Choose Y for Sea Zones only, or N for all
7 Process map and break into tiles 8 Wait until finished

Once the Tile Image Breaker is done, all the tiles will be saved in the directory that has been selected at the start.

5.1.7 Image Shrinker

This utility will create a copy of the original map, but shrunk down to a custom scale. TripleA uses this small scale map as a "mini-map".

How to run Image Shrinker
cd bin
java -Xmx512m -classpath triplea.jar util/image/ImageShrinker

Program Action User Action
1 Show a "Select Map File" dialog 2 Select a map
3 Show a "Scale Input" dialog 4 Enter a floating point scale value (ie. 0.1)
5 Image saved as smallMap.jpeg in current directory    

5.1.8 Making a Map

This section will go through all the steps needed to be taken in order to create a custom map. Before we go any further, lets take the time to explain how the "finalized map directory" works and what this document means by it.

TripleA has a special directory where it stores its maps and their respective configuration files. It is that directory that we refer to as the "finalized map directory". The directory itself has some special conditions that needs to be met:

  1. Located in triplea_0_6_0_1/maps
  2. Name of the map directory must be same as the "mapName" field in the XML game file for that game. For example; revised.xml has the mapName field showing a value of revised thus the folder where TripleA will find the map is also revised
  3. All map configuration files must be located inside:
    • centers.txt
    • polygons.txt
    • place.txt
    • map.properties
    • capitols.txt (optional for victory capitols)
    • vc.txt (optional for victory markers)
    • pu_place.txt(optional, if it exists this is where PU markers will be placed)

  4. A folder named baseTiles with the broken up 256x256 tile images
  5. A folder name reliefTiles (optional if there is a relief map)
  6. The smallMap.jpeg image of the larger original map used

Let us assume that a custom map we want to make will be called viper. Let us also assume that we have a nice large image of our map with black borders separating the territories. Our image can either be a GIF or PNG image.

These are the steps we would take to integrate it into TripleA.

Step User Action
1 Go into directory: triplea_0_6_0_1/maps
2 Create new directory called viper
3 Go back to the base of classesSave the center points in our viper directory we made in Step No. 1
4 Run the PolygonGrabber and save the polygons file in our viper directory we made in Step No. 1
5 Run the PlacementPicker and save the place.txt file in our viper directory.

OR

Create an empty place.txt file in the viper directory and then run AutoPlacementFinder Enter "viper" when asked for a map name.
6 Run the TileImageBreaker and save all the tiles in baseTiles inside viper
7 If we have a relief map, then run the ReliefImageBreaker and save all the tiles in reliefTiles inside viper; say "N" to do Only Sea Zones
8 Run the ImageShrinker and copy the smallMap.jpeg to the viper directory
9 Create a map.properties file with map properties See Section 5.2 for more information
10 Make sure our XML game file shows viper as the value for the "mapName" property option
11 All Done !

5.2 Map Configuration

Each map has its own configuration options. These are found in the map's directory where there tile images and centers, polygons, and place text files are. These map options can be configured at any time and does not require that TripleA be re-compiled for the settings to take effect.

This section and the following sub-sections will cover the following:

  • Changing territory colors
  • Pre-set releif map settings
  • Pre-set unit scales
  • Scroll Locking
  • Capital marker toggles
  • Victory Cities
  • Capital Cities
  • Victory Markers

5.2.1 Map Properties

Specific map properties are found in a file named map.properties. This file can be editted at will by the user. It allows for the following changes:

Option Value Description
color.Americans= HEX Number Color Color of all American Territories
units.scale= Floating Point; One of :
  • 1.25
  • 1.00
  • 0.875
  • 0.8333
  • 0.75
  • 0.6666
  • 0.5625
  • 0.50
Starting scale size of image units
map.hasRelief= Boolean Sets relief images on or off by default
map.showCapitolMarkers Boolean Display capital markers images
map.scrollWrapX= Boolean Lock X-Axis scrolling
map.width= Non-Zero Integer Width of map image
map.height= Non-Zero Integer Height of map image
# Any Printable Character In file comments, these get ignored by TripleA

For completeness, below is an example of a map.properties file. This way we can see how the above options and values are used in a practical setting.



Example of A map.properties File
#Color settings for the map
#values must be a 6 digit hex number
color.British=996600
color.Americans=666600
color.Russians=993300
color.Germans=777777
color.Japanese=FF9900
color.Italians=5A5A5A
color.Neutral=dd5500
color.Impassible=cc9933
color.Chinese=442244

#default unit scale
#value must be one of the menu options
units.scale=0.5625

#does the map have relief images
map.hasRelief=false

#show capitol markers
map.showCapitolMarkers=false

map.width=4000
map.height=2000

#lock horizontal scrolling
map.scrollWrapX=false

5.2.2 Capital Cities

TripleA is also able to mark certain territories as capitals. Along with that, TripleA can draw an image on the territory to mark it as a capital. These images are called "Captial Markers".

The default TripleA capital markers can be found in the directory listed below; note that capital markers end with the word "large":


Location of Capital Markers
triplea_0_6_0_1/images/flags

If you want to add custom capitol markers to your game (or override the defaults), add a put your flags in maps/mapName/images/flags/

Below is a list of TripleA's captial markers that are used for World War II games and other variants:


TripleA Capital Markers
U.S.A Australia U.K China E.U Germany
Italy Japan Mid-East China U.S.S.R U.K Union Jack

Capital cities can be added in a game's XML file. An extra option has to be added to a territory attachment tag.


Capital XML Option
<option id="capital" value="Germans"/>

A full example of a territory attachment with the capital option:

Capital XML Option
<attachment id="territoryAttachment" attatchTo="Germany" javaClass="games.strategy.triplea.attachments.TerritoryAttachment" type="territory">
         <option id="production" value="10"/>
         <option id="capital" value="Germans"/>
</attachment>

For TripleA to draw capital markers more appropriately, it uses a capitols.txt file located in the maps directory. This file lists all the capitals and the starting (X,Y) coordinates from where to draw the capital markers. If this file is missing, then TripleA will use a default location on where to draw the images.

An example of a capitols.txt file is listed below. Note that the names of the territories need to match the names in the other text files (centers, place, polygons).

Capitols.txt File Example
United Kingdom (709,292)
Germany (981, 532)
Russia (1723,337)
Japan (2711,686)
Eastern United States (33,616)

5.2.3 Victory Cities

TripleA has the ability to keep track of territories that are considered to be an objective to capture and hold; otherwise known as "victory cities". The owner of these territories are tracked and displayed in TripleA's stats window.

Victory Cities, just like capitals, have their own image markers as well. TripleA comes with a very simple victory marker which can be replaced by the user at any time. The victory marker can be found below:

Capital XML Option
triplea_0_6_0_1/images/vc.png

TripleA's Default VC Image
vc image

Victory cities can be added in a game's XML file. An extra option has to be added to a territory attachment tag.

Victory City XML Option
<option id="victoryCity" value="true"/>

A full example of a territory attachment with the capital option:

Victory City XML Option
<attachment id="territoryAttachment" attatchTo="Karelia" javaClass="games.strategy.triplea.attachments.TerritoryAttachment" type="territory">
 <option id="production" value="10"/>
 <option id="victoryCity" value="true"/>
</attachment>

Capitals can also be victory cities.

For TripleA to draw victory city markers more appropriately, it uses a vc.txt file located in the maps directory. This file lists all the victory cities and the starting (X,Y) coordinates from where to draw the victory markers. If this file is missing, then TripleA will use a default location on where to draw the images.

An example of a vc.txt file is listed below. Note that the names of the territories need to match the names in the other text files (centers, place, polygons).

vc.txt File Example
Karelia S.S.R. (1243,276)
Russia (1863,214)
Western Europe (807,527)
Germany (1090,518)
Southern Europe (980,880)
United Kingdom (760,390)
Eastern United States (205,630)
Western United States (3343,735)
Philipine Islands (2435,1250)
India (1939,997)
Japan (2680,750)
Kwangtung (2427, 790)

5.3 Customizing The XML Game File

XML files are used to set-up and initialize games in TripleA. These XML files are found in the games directory in the root of TripleA. They can edited and used to create new kinds of games or variants of existing games. XML files can usually be edited by using any simple text editor, though it may be wise to use some sort of special editor that can color code the XML. It makes it easier to edit.

The sections below will mainly go over how to edit and change values in some of the XML game files that come with TripleA. TripleA currently has game logic code for use with standard war games, so the following sections shall use those as examples.

5.3.1 Game Information Header

Every game that comes with TripleA normally has four XML tags that gives us some information about it.

  • XML Version
  • XML Game Sheet Definition
  • Name and Version of Game
  • Java Class Loader

At the top of every XML file it must include a tag specifying what version of XML is being used.


XML Version
<?xml version="1.0" ?>

The game definition sheet must always be specified. In the example below we use the "game.dtd" definition. It can be located in the triplea_0_6_0_1/data/games/strategy/engine/xml directory.

Definition Sheet
<!DOCTYPE game SYSTEM "game.dtd">

The "info" tag contains the game name and version number. This normally can be edited by any one and will not affect the game much. It is just for display on the main TripleA window when the game is loaded.

The "loader" tag defines what class file is used to load this game. As we can see below; the class used to load this World War II type game is a class called TripleA.class but we do not include the ".class" but we do include the full package path.

Info & Loader Tags
<info id="4th Edition" version="1.2"/>
<loader javaClass="games.strategy.triplea.TripleA"/>

5.3.2 Territories

Territory definitions occur in the map tags along with their respective connections. Territories can be added or removed by editing these territory tags. These tags come with two values "Name" and "water"

Option Value Description
id="   " String Name of the territory
water="   " Boolean True if this territory is a sea zone

Two qualified examples:

Territory Example
<territory id="Argentina"/>

Territory Example
<territory id="Atlantic Ocean" water="true"/>

5.3.3 Territory Connections

Each territory must have some kind of relation to the territory next to it. When two territories are connected together, that means that a movement action can occur between those two territories. These connections are defined using connection tags located inside the map tag where you also find territory tags.

A connection tag consists of only two options; source and destination. When a connection tag is made, there is no need to do the same connection in reverse. When territory A is connected to territory B, this also implies that territory B is connected to territory A.

Option Value Description
t1="   " String Name of the source
t2="   " String Name of the destination
Resource Example
<connection t1="Venezuala" t2="Brazil"/>

5.3.4 Resources

The resources for the game needs to have some sort of name. Maybe it is Dollars, or maybe it is gold bars. Either way modifying this is very simple. We change the the name option of the resource tag which is enclosed between a resourceList tag.

Option Value Description
id="   " String Name of the resource

Resource Example
<resourceList>
 <resource id="PUs"/>
</resourceList>

5.3.5 Players & Alliances

Players and alliances can be defined using the player and alliance tags which are to be enclosed inside the playerList tag. Defining player names and alliance are pretty straight forward.

Player tag options and values

Option Value Description
id="   " String Name of the player
optional="   " Boolean Is this player mandatory

Alliance tag options and values

Option Value Description
player="   " String Name of the player
alliance="   " String Name of the alliance

Player & Alliance Example
<playerList>
  <player id="Japanese" optional="false"/>
  <player id="Germans" optional="false"/>
  <player id="British" optional="false"/>
  <player id="Americans" optional="false"/>
  <player id="Russians" optional="false"/>

<alliance player="Germans" alliance="Axis"/> <alliance player="Japanese" alliance="Axis"/> <alliance player="British" alliance="Allies"/> <alliance player="Russians" alliance="Allies"/> <alliance player="Americans" alliance="Allies"/> </playerList>

5.3.6 Units

Units are defined in unit tags enclosed inside unitList tags. These too are simple tags that define the names of units only. The properties of units can be modified later on using the attachment tags (which will be discussed later in Section 5.3.10.

Option Value Description
id="   " String Name of the unit

Unit Example
<unitList>
   <unit id="infantry"/>
   <unit id="armour"/>
   <unit id="fighter"/>
   <unit id="bomber"/>
   <unit id="transport"/>
   <unit id="battleship"/>
   <unit id="carrier"/>
   <unit id="submarine"/>
   <unit id="factory"/>
   <unit id="aaGun"/>
   <unit id="artillery"/>
   <unit id="destroyer"/>
</unitList>

5.3.7 Game-play Delegates

Delegate tags are found inside the gamePlay tags (along with other tags). What these tags basically do is identify a certain Java class with a delegate name so that it can be used later on in other tags. These Java classes are delegates themselves that handel game logic. These delegate tags serve as a kind of "macro" that binds the Java class with a specified name.

For example; all the game logic for conducting battles in a World War II v2 Revised game are in the BattleDelegate.java class located in games.strategy.triplea.delegate class path. When we want to reference that delegate in the XML we have to make a delegate tag and bind it to a name. A name as "battle" would be fine.

Option Value Description
id="   " String Name of the delegate
javaClass="   " String Name and Package location of the delegate class
display="   " String What TripleA will display when the delegate is in use

Delegate Example
<delegate id="battle" javaClass="games.strategy.triplea.delegate.BattleDelegate" display="Combat"/>

Of course there will be many delegates that TripleA can use for handeling game logic. And thus would need numerous delegate tags defined in the XML to set-up a game properly. For the sake of completenes and practicallity, below is an example of all the delegate tags used in the World War II v2 Revised XML file:

Delegate Example
<delegate id="initDelegate"
      javaClass="games.strategy.triplea.delegate.InitializationDelegate"
      display="Initializing Delegates"/>
<delegate id="tech"
      javaClass="games.strategy.triplea.delegate.TechnologyDelegate"
      display="Research Technology"/>
<delegate id="tech_activation"
      javaClass="games.strategy.triplea.delegate.TechActivationDelegate"
      display="Activate Technology"/>
<delegate id="battle"
      javaClass="games.strategy.triplea.delegate.BattleDelegate"
      display="Combat"/>
<delegate id="move"
      javaClass="games.strategy.triplea.delegate.MoveDelegate"
      display="Combat Move"/>
<delegate id="place"
      javaClass="games.strategy.triplea.delegate.PlaceDelegate"
      display="Place Units"/>
<delegate id="purchase"
      javaClass="games.strategy.triplea.delegate.PurchaseDelegate"
      display="Purchase Units"/>
<delegate id="endTurn"
      javaClass="games.strategy.triplea.delegate.EndTurnDelegate"
      display="Turn Complete"/>
<delegate id="endRound"
      javaClass="games.strategy.triplea.delegate.EndRoundDelegate"
      display="Round Complete"/>
<delegate id="placeBid"
      javaClass="games.strategy.triplea.delegate.BidPlaceDelegate"
      display="Bid Placement"/>
<delegate id="bid"
      javaClass="games.strategy.triplea.delegate.BidPurchaseDelegate"
      display="Bid Purchase"/>

5.3.8 Game-play Sequence & Steps

Every game has a certain repeatable sequence that needs to be followed for the game to run properly. Such a sequence needs to be defined in the XML file as well. The sequence is broken down in to individual steps, and it is these steps that need to be defined. We have several step tags encapsulated by one sequence tag. The step tags define the sequence of the game.

Step tags are quite versitile and simple to implement. All step tags must have a name and must be bound to a delegate. The delegate it is bound to is a delegate name that has been predefined in a delegate tag. Then after that there are several different options that can be added depending what kind of a step is being made. The specifications are listed below as well as a few examples.

Option Value Description
id="   " String Name of the step
delegate="   " String Delegate name
player="   " String Player name
maxRunCount="   " Integer Number of times the delegate will run.
display="   " String What TripleA will display when the delegate is in use

Bid placements can only occur once in this game, so we make bidding happen first and limit it to one occurance.

Step Example
<step id="russianBid" delegate="bid" player="Russians" maxRunCount="1"/>
<step id="russianBidPlace" delegate="placeBid" player="Russians" maxRunCount="1"/>

We define a the full turn sequence of a player through multiple steps:

Step Example
<step id="japaneseTech" delegate="tech" player="Japanese"/>
<step id="japaneseTechActivation" delegate="tech_activation" player="Japanese"/>
<step id="japanesePurchase" delegate="purchase" player="Japanese"/>
<step id="japaneseCombatMove" delegate="move" player="Japanese"/>
<step id="japaneseBattle" delegate="battle" player="Japanese"/>
<step id="japaneseNonCombatMove" delegate="move" player="Japanese" display="Non Combat Move"/>
<step id="japanesePlace" delegate="place" player="Japanese"/>
<step id="japaneseEndTurn" delegate="endTurn" player="Japanese"/>

5.3.9 Production Rules

Production rules define how the game handels the production of units and resources. Production rules consist of three main tags which get encapsulated inside production tags:

  • productionRule : Defines the name of the item, its cost, quantity, and result
  • productionFrontier : Defines a group of production
  • playerProduction : What players are eligable for production

A productionRule tag consists of several options and sub-tags that will define the production method and cost of an item or unit. Normally a production rule has a name that defines what it is producing, such as "buyTanks". Then a cost tag specifies the quantity of resources that is needed to make a purchase. Lastly, a result tag is used to explain what the result of the purchase will yeild and the quantity.

Options and Values for productionRule tag:

Option Value Description
id="   " String Name of the productionRule

Options and Values for cost tag:

Option Value Description
resource="   " String Name of the resource
quantity="   " Integer Amount needed for purchase

Options and Values for result tag:

Option Value Description
resourceOrUnit="   " String Name of the resource or unit that is being produced
quantity="   " Integer Quantity of that product to give out

A practical example:

Production Rule Example
<productionRule id="buyTanks">
	<cost resource="PUs" quantity="4" />
	<result resourceOrUnit="armour" quantity="1"/>
</productionRule>

A productionFrontier tag groups different types of production rules. There can be more than one production frontier. For example in World War II v2 Revised, there is regular production of units and production of technologically advanced units. Both are in different frontiers beacuse they deal with the same kind of units, but with different values. Such as a standard airplane vs a jet powered airplane.

Option Value Description
id="   " String Name of production frontier

frontierRules tags are sub-tags of productionFrontier. These sub-tags define what productionRule is grouped with that frontier.

Option Value Description
id="   " String Name of frontier rule

A practical example:

Production Frontier Example
<productionFrontier id="production">
<frontierRules id="buyInfantry"/>
    <frontierRules id="buyArtillery"/>
    <frontierRules id="buyArmour"/>
</productionFrontier>
<productionFrontier id="productionIndustrialTechnology">
    <frontierRules id="buyInfantryIndustrialTechnology"/>
    <frontierRules id="buyArtilleryIndustrialTechnology"/>
    <frontierRules id="buyArmourIndustrialTechnology"/>
</productionFrontier>

Last but not least, playerProduction tags specify which players are eligable to which production forntier.

Option Value Description
player="   " String Player name
frontier="   " String Production frontier name

Player Production Example
<playerProduction player="British" frontier="production"/>

5.3.10 Unit Attachment

Unit definition rules are mainly handled in the unitAttachment tag. This is the place where we can define what specific options to be "attached" to which unit. The tag compositions is relatively quite simple. The header tag defines what kind of attachment is to be defined, the name of the item it should be attached to, which java class to use, and of what type is it.

Options and Values for attachment tag:

Option Value Description
id="   " String The name of the attachment. This must end with the word "Attachment"
attachTo="   " String The name of the item to attach it to
javaClass="   " String The java class name and its fully qualified package location
type="   " String The type

Within the attachment tag will be an arbitrary amount of option tags which will define the type of properties the attachment will have. It can have very few or many. Below is a list of options that can be used:

List of option tags that can be used :

Option Value Description
movement="   " Integer The allowed movement points
transportCost="   " Integer The cost for being loaded onto a transport ship
carrierCost="   " Integer The cost for being loaded onto an air-craft carrier
transportCapacity="   " Integer The maximum number of items a transport ship can load
carrierCapacity="   " Integer The maximum number of items an air-craft carrier can load
canBlitz="   " Boolean Allows a unit to capture an undefended territory while moving on to the next
canBombard="   " Boolean Allows an air unit to have bombardment capabilities
isAir="   " Boolean Specifies if this unit can fly in the air or not
isSea="   " Boolean Specifies of this unit can go in water or not
isFactory="   " Boolean Specifies if this unit is a factory
isDestroyer="   " Boolean Specifies if this unit is a destroyer
isAA="   " Boolean Specifies if this unit is an anti-aircraft gun
isSub="   " Boolean Specifies if this is a submersible unit
isTwoHit="   " Boolean Allows a unit to absorb one extra attack hits before being destroyed
isStrategicBomber="   " Boolean Specifies if an air-craft can perform strategic bombing
artillerySupportable="   " Boolean Specifies if this unit can be supported by artillery or not
artillery="   " Boolean Specifies if this is an artillery unit or not
attack="   " Integer The attack value
defense="   " Integer The defense value

A practical example:

Unit Attachment Example
<attachment id="unitAttachment" attatchTo="battleship" javaClass="games.strategy.triplea.attachments.UnitAttachment" type="unitType">
	<option id="movement" value="2"/>
	<option id="isSea" value="true"/>
	<option id="attack" value="4"/>
	<option id="defense" value="4"/>
	<option id="canBombard" value="true"/>
	<option id="isTwoHit" value="false"/>
</attachment>
<attachment id="unitAttachment" attatchTo="infantry" javaClass="games.strategy.triplea.attachments.UnitAttachment" type="unitType">
    <option id="movement" value="1"/>
    <option id="transportCost" value="2"/>
    <option id="attack" value="1"/>
    <option id="defense" value="2"/>
    <option id="artillerySupportable" value="true"/>
</attachment>
<attachment id="unitAttachment" attatchTo="factory" javaClass="games.strategy.triplea.attachments.UnitAttachment" type="unitType">
    <option id="isFactory" value="true"/>
</attachment>

5.3.11 Tech Attachment

Technology definition rules are mainly handled in the techAttachment tag. This is the place where we can define what specific types of technological advancements are allowed for this particular player. The tag compositions is relatively quite simple. The header tag defines what kind of attachment is to be defined, the name of the player it should be attached to, which java class to use, and of what type is it.

Options and Values for attachment tag:


Option Value Description
id="   " String The name of the attachment. This must end with the word "Attachment"
attachTo="   " String The name of the player to attach it to
javaClass="   " String The java class name and its fully qualified package location
type="   " String The type

Within the attachment tag will be an arbitrary amount of option tags which will define the type of properties the attachment will have. It can have very few or many. Below is a list of options that can be used:

List of option tags that can be used :


Option Value Description
heavyBomber="   " Boolean Allows for a player to acquire heavy bombers
jetPower="   " Boolean Allows for a player to acquire jet propulsion technology
industrialTechnology="   " Boolean Allows for a player to acquire industrial technology
superSubs="   " Boolean Allows for a player to acquire advanced submarine units
rocket="   " Boolean Allows for a player to acquire rocket technology
longRangeAir="   " Boolean Allows for a player to acquire long range air units

These options can all be initialized to "false" unless we want a player to start off with a technology advancement.

A practical example:


Tech Attachment Example
<attachment id="techAttachment" attatchTo="British" javaClass="games.strategy.triplea.attachments.TechAttachment" type="player">
	<option id="heavyBomber" value="false"/>
	<option id="jetPower" value="false"/>
	<option id="industrialTechnology" value="false"/>
	<option id="superSub" value="false"/>
	<option id="rocket" value="false"/>
	<option id="longRangeAir" value="false"/>
</attachment>

6.5 Game Play Sequence

The game sequence is definied in the XML file (game-gamePlay-sequence). Each step entry defined here basically creates a delegate for a certain player which then handles the current step. The end of a round is defined by a step for the endRound delegate and leads to a loop back to the first step.

6.6 Delegates

Delegates are the class which are responsible for a certain game step. They are supposed to be the only place where game data is actually changed.

You can’t perform that action at this time.