TripleA Banner

This Document Is Accurate For TripleA v0.6.0
Written by George H.


! NOTE !
This document is still incomplete and will be update soon.


Developer Documentation :: Quick Nav



1.0 Project Management With CVS

TripleA's source code is managed through the use of Source-Forge's Concurrent Versions System (CVS) server. Developers use CVS to read, write, remove, and revert files for the TripleA project.

Not all developers use the same Operating System and not all use the same development environment. For this reason, we cannot show a proper guide that would suite everyone. This section will focus on how to use the CVS from a UNIX based console. This would work on most systems such as Mac OS X, GNU/Linux, and SGI/IRIX. IDEs such as Eclipse that provides a CVS front end will not be covered. It is recommended that developers find out the capabilities of their development environment and see if there is support for CVS or not.

Sections 1.1 and 1.2 will briefly explain some basic commands that will get a developer started. It is highly recommended to read the official CVS manual on how to use the CVS, as it is very explicit and detailed.

- Top -

1.1 CVS For Developers

This section provides some basic CVS commands that would interest developers. We assume you have CVS already installed and have access to some sort of UNIX console like bash or tcsh.

1.1.1 Module Check Out

A check out will allow you to have a complete copy of the source code on your computer. It also sets up all the necesary CVS related files to keep track of various versions and revisions of each individual source file.

  1. Set the CVS_RSH environment variable to ssh
  2. Go to a suitable directory where you wish to have TripleA checked out
  3. Run the command to check out the TripleA module
info image In the example below; USERNAME would be the developer's source-forge account. That means if you are a developer, you will put your source-forge user name in place of USERNAME.

Checking out a module.
shell image   export CVS_RSH=ssh
  cvs -d:ext:USERNAME@cvs.sf.net:/cvsroot/triplea checkout triplea

When prompted to input a password; enter the appropriate password corresponding with the user name chosen for the check out command. CVS will download the current CVS source tree for TripleA to your computer in the current working directory.

- Top -

1.1.2 Commiting Items

The commit command will physically upload any changes made to the CVS copy on your computer to the CVS tree on Source-Forge. This command can be used in a few different ways:

  1. To commit a single file or directory
  2. To commit multiple files or directories
  3. 1 & 2 with a single message

Commit a single file
shell image   cvs -d:ext:USERNAME@cvs.sf.net:/cvsroot/triplea commit SourceFile.java
Commit a single file
shell image   cvs commit SourceFile.java
info image You can commit a change by issuing the the commit command alone or with all the user options and module names. Either will work. Wild cards such as * can also be used to specify multiple files and/or directories. If you just run the commit command alone without specifying a file. It will recursively scan all files and directories and commit those that have changed from the on-line CVS Tree.
Commit a single directory
shell image   cvs commit new_dir

When commiting a change in the way shown above, you will be prompted to enter a message using the system default console text editor (ie. nano or pico). Sometimes this is useful when you want type a long and detailed description. There is a way to commit changes without having an editor open after ever commit; that is to commit a change with the message in the command line.

Commit with a message.
shell image   cvs commit SourceFile.java -m "fix was aplied to lines 345"

- Top -

1.1.3 Adding Items

Adding items to the CVS tree is relatively simple. There are three most commonly faced situations when adding items to the CVS tree.

  1. Adding a source file (ie. source code)
  2. Adding a binary file (ie. images, pdfs ..etc)
  3. Adding a directory
Adding items to the CVS tree is different from commiting items. When you add a file; it is queued for addition on the CVS server. If and only if the file has been added, then you can finally commit it to the CVS tree.

Adding a source file.
shell image   cvs add MySourceFile.java
  cvs commit
info image When a binary file is committed without the -kb option it will make the file be saved in a textual format. Although this does not pose any problems to UNIX based systems, it does for developers who use Microsoft Windows.
Adding a binary file.
shell image   cvs add -kb Some_Image.png
  cvs commit

Adding a directory.
shell image   mkdir new_directory
  cvs add new_directory
  cvs commit
 

- Top -

1.1.4 Removing Items

Removing items from the CVS tree works in a similar way to adding items. The item to be removed will be removed from your local CVS copy but will remain in the on line CVS tree. Removing it will basically make it "hidden." So in other words, nothing is ever deleted from the on line tree, only hidden.

To remove a file from the CVS, one must follow three simple steps:

  1. Physically remove the file from the local CVS tree
  2. Issue the cvs command to remove the file from the on line CVS tree
  3. Commit the changes
Removing a file.
shell image   rm SourceFile.java
  cvs remove
  cvs commit

Removing a file with a message.
shell image   rm SourceFile.java
  cvs remove
  cvs commit -m "no longer needed"

Removing directories works in a similar way, except for one thing. The directory to be removed needs to have all of its contents removed first. Below is an example of how to remove a directory that is filled with source files.

Removing a full directory.
shell image   cd myDir
  rm *.java
  cvs remove
  cvs commit
  cd ..
  cvs remove myDir
  rm -rf myDir
  cvs commit
info image When issuing the remove command by it self, it will recurse through all the files and directories and queue for removal all files that have been manually deleted. You can specify what file you want it to queue for removal by appending the file name after the word remove.

- Top -

1.1.5 Tagging Items

Normally, before pushing out a release, we tag all the files in the CVS with a name. This tag allows us to identify what branch we're working on and for which version of TripleA it was included into. There are at least two tag names we use (please not that the upper-case Xs represent the version number of TripleA):

  1. sX-X-X-release : Stable release
  2. uX-X-X-release : Unstable release
To tag the CVS tree before a release; we run the command from the root directory of TripleA. That way every file and directory gets tagged.

Tagging the CVS Tree.
shell image   cvs tag s0-6-0-release

- Top -

1.1.6 Updating Your CVS Copy

It is very important for a developer to keep their local copy of the CVS as up-to-date as possible. One can achieve this goal by running the update command from the cvs. It will synchronize your local copy to the remote copy on the CVS server. Has the ability to download all new files and even remove files (on your local copy) that have been removed (hidden) from the CVS Tree.

In the root folder of TripleA run the command below. This will update all files and directories recursively. This will not remove un-wanted files.

Updating the local CVS copy.
shell image   cvs update

The example below will perform the update and will remove any empty folders or files that have been removed from the on-line CVS Tree. The -q switch will make the CVS only echo a status message when a file has been updated.

Updating the local CVS copy with options.
shell image   cvs -q update -dAP

- Top -

1.1.7 Viewing Changes

To keep track of the who has been changing what files, for what reason, and when is easily done with the annotate command provided by CVS. Given the file name; it will annotate every single line of the source file telling you when each line was modified and by whom. Normally this output is echoed right into the console, but with simple Shell commands you can pipe it to a text file.

Basic annotation.
shell image   cvs annotate SourceFile.java

Annotate to a file.
shell image   cvs annotate SourceFile.java > AnnotatedFile.txt

Example of an annotated file.
text image 1.34    (userOne 19-Feb-05):    if (sentinel != null)
1.29    (userTwo 11-Apr-04):        return false;
1.29    (userTwo 11-Apr-04):
1.29    (userTwo 11-Apr-04):    if (t_sec > (x+y))
1.27    (userOne 10-Apr-04):        return false;

- Top -

1.2 CVS For Non-Developers

Accessing the TripleA CVS tree is not only for developers. Non-developers have access to it. They can check out the TripleA module and keep it up-to-date with the very latest changes. They, however, cannot make changes to the CVS tree; only read access is granted to non-developers.

In this section we assume you have CVS already installed and have access to some sort of UNIX console like bash or tcsh.

1.2.1 Module Check Out

A check out will allow you to have a complete copy of the source code on your computer. It also sets up all the necesary CVS related files to keep track of various versions and revisions of each individual source file.

  1. Set the CVS_RSH environment variable to ssh
  2. Go to a suitable directory where you wish to have TripleA checked out
  3. Run the command to check out the TripleA module

Checking out a module.
shell image   export CVS_RSH=ssh
  cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/triplea checkout triplea

The above command will allow anonymous access to check out a copy of the CVS tree. Once the triplea module has been checked out and saved on your system, you can do whatever you want with it. The only restriction is that you are not allowed to add or commit changes to the CVS tree that is on line. Those actions are reserved for developers who log in to the CVS with their SourceForge accounts.

- Top -

1.2.2 Updating Your CVS Copy

Once a copy of the triplea CVS module has been checked out, it can be kept up-to-date by running the update command. It will synchronize your local copy to the remote copy on the CVS server. It Has the ability to download all new files and even remove files (on your local copy) that have been removed (hidden) from the CVS Tree.

In the root folder of TripleA run the command below. This will update all files and directories recursively. This will not remove un-wanted files.

Updating the local CVS copy.
shell image   cvs update

The example below will perform the update and will remove any empty folders or files that have been removed from the on-line CVS Tree. The -q switch will make the CVS only echo a status message when a file has been updated.

Updating the local CVS copy with options.
shell image   cvs -q update -dAP

- Top -

1.2.3 Viewing Changes

To keep track of the who has been changing what files, for what reason, and when is easily done with the annotate command provided by CVS. Given the file name; it will annotate every single line of the source file telling you when each line was modified and by whom. Normally this output is echoed right into the console, but with simple Shell commands you can pipe it to a text file.

Basic annotation.
shell image   cvs annotate SourceFile.java

Annotate to a file.
shell image   cvs annotate SourceFile.java > AnnotatedFile.txt

Example of an annotated file.
text image 1.34    (userOne 19-Feb-05):    if (sentinel != null)
1.29    (userTwo 11-Apr-04):        return false;
1.29    (userTwo 11-Apr-04):
1.29    (userTwo 11-Apr-04):    if (t_sec > (x+y))
1.27    (userOne 10-Apr-04):        return false;

- Top -

2.0 Compiling The TripleA Source Code

This section will go through the various details on how to successfully compile the TripleA source code in order to get a runnable copy. TripleA can be compiled in many different ways and with many different IDEs. For consistency and all around compatibility; TripleA must be able to be compiled using the Java compiler by Sun Micro systems and the compilation process be controlled by Apache's ANT. All these tools are to be run from the command line.

2.1 Prerequisites

There are a few prerequisites that need to be fulfilled before attempting to start compilation process. We assume that the following packages (listed below) are fully and properly installed.

These packages can be installed on various operating systems which include GNU/Linux, SGI/IRIX, MS/Windows, Mac OS X, and others that allow for it.

- Top -

2.2 ANT Commands

These are a list of command line parameters that can be used with ANT on TripleA. Each command tells ANT to do something different with the TripleA source code.

Command Description
ant compile Compiles all TripleA source code files. Compiled classes are placed in the classes folder.
ant compileClean Removes previously compiled folders such as the classes, release, and savedGames folders. Once the removal is successful, it will compile the TripleA source files.
ant clean Removes the previously compiled copy of TripleA. This will also remove the savedGames, and release folders that may have been created with other ANT commands.
ant zip Cleans, compiles, and packages a compiled copy of TripleA in a Zip file. The zip file is placed in a folder named release.
ant zipSource Runs the clean command and then packages all TripleA source files in a Zip file. The Zip file is placed in a folder named release.
ant patch Constructs a patch.jar file with specified java class files that were indicated in the build.xml document. This patch.jar file can be used for a quick fix.
ant javadoc Generates Java Documentation HTML using source code comments.
ant test Initiates the JUnit tests.

- Top -

2.3 Compiling on Microsoft Windows Systems

A complete guide to compiling TripleA on MS/Windows has been generously written by a member of the TripleA community, ZeroPilot.

The first step is to extract the contents of the zip file into a location of your choice. Once you have extracted all the files, you will see a folder named triplea_x_x_x (where x_x_x represent the version number). Note, it has the same name as the pre-compiled package. If you are going to install both the source and the pre-compiled version, it is highly recommended that you create separate directories for them first; if not one will overwrite the other.

info image Be sure to download the Java SDK SE (Standard Edition) and not the EE (Enterprise Edition.) Most users find it difficult to get the Enterprise Edition working. On top of that you don't need it to compile TripleA.

We assume you have ANT installed, as well as a suitable Java JDK whose version is 1.4.x or higher, and Junit installed (you only need to download the Junit package and unzip it somewhere on your system. The .ant.properties file, (if not included in the source package, you will have to make your own) from which it will reference the Junit installation directory.

Go into the directory where you extracted the TripleA source code. There should be a file named .ant.properties. Open it using MS Wordpad not notepad. If the source package you downloaded somehow did not come with that file, then create one. You can do this by creating an ordinary text file and then renaming it to .ant.properties exactly. This property file includes two peices of information:

  1. The absolute path of Junit
  2. The version number of TripleA
Open the .ant.properties file and edit it to include the information below:

Info For The .ant.properties File
text image   junit.jar=PATH TO THE JUNIT JAR FILE
  triplea.version=X_X_X

For completness sake; this is how my .ant.properties file would look like:

Example Of The .ant.properties File
text image   junit.jar=C:junit3.8.1\junit.jar
  triplea.version=0_6_0

You should consider installing both the Java SDK and ANT at the root level of the C: drive. It is known that ANT in particular sometimes does not like spaces in the path name (nor for the path to be extremely long). You will notice that the typical Windows installation location of Program Files will have a space in its path (the space between Program and Files. It is not known how often this truly causes a problem (if ever), but the "pros" say they install their compiling tools in their root C: directory to avoid pitfalls. Thus it is recommended that we do the same. The last thing we need is "extra" problems.

For simplicity's sake, we shall install both the Java SDK SE and Ant at the root or C: Drive as well as TripleA and JUnit. JUnit is easily installed, you just need to extract the contents of it into its own folder. TripleA just needs to use a single JAR file that comes with JUnit.

Once we have installed the Java SDK SE, JUnit and ANT on your PC, start the Command Prompt (terminal) program. In Windows XP it can be found by navigating through the Start menu:

Location Of The Command Prompt
text image   Start -> All Programs -> Accessories -> Command Prompt

In Command Prompt, enter this command and hit the Enter key:

Java Command
shell image   java -version

The results of that command should show an informational message about the new Java SDK SE that we have just installed. If you see a message about the default Windows Java version then that means that Windows is not recognizing the newly installed Java. If you get an error message saying that the command cannot be found; that means Windows cannot see the Java executable.

Now in Command Prompt enter this ANT command and hit the Enter key:

Ant Command
shell image   ant -version

You will probably see a message as such:

"Ant is not recognized as a internal or external command, operable program or batch file."
Even though the Java SDK SE and ANT have been installed properly, there are instances where they are inaccessible through the command prompt. This can be fixed by modifying the Windows Environment Variables. Find the Environment Variables options in Windows by following the menus below:

Location Of Windows Environment Variables
text image   Start -> Control Panel -> System -> Advanced (tab) -> Environmental Variables (button)

Here we will add information for Windows to recognize both programs so it will pass your Command Prompt calls to the right place. You will want to make the following additions to the "User Variables" section at the top and NOT the System Variables.

There is no good reason to make these additions as System Variables unless you absolutely need all user accounts on your PC to be able to run these command line programs. Messing around with System Variables is risky because (unlike the User Variables) it has the potential to really mess up the system if you enter something wrong. So let's take the safe road and simply enter the following as User Variables.

The Variable Name should be entered exactly as indicated. The Variable Value will be your exact path to the Java SDK SE folder. This may vary depending on where Java was installed. In this document we will go by the example that Java and ANT are installed in the Root level of C: Drive. Under "User Variables", (not system variables) click on the "New" button and enter the following information:

Java User Variable
text image   Variable name: JAVA_HOME
  Variable value: C:\j2sdk1.4.2_04
info image The easiest way to get this path exactly correct is to open the Java SDK SE folder and select a subfolder inside (bin folder, for example) then view the properties on it. The "Location" shown in the properties window will be the path you need to enter here, and you can simply select it and copy/paste it in to avoid any typos.
ANT User Variable
text image   Variable name: ANT_HOME
  Variable value: C:\apache-ant-1.6.2

The next step is to add both Java SDK SE and ANT's paths into the User Variables. The Variable Name field should be entered exactly as shown. The Variable Value field will display the exact paths to the BIN folders located inside both the Java SDK and Ant folders. The two entries separated by a semi-colon ";" and no spaces between them. Be sure to include the trailing slash "\" after bin in the path names.

Path Variable
text image   Variable name: PATH
  Variable value: C:\j2sdk1.4.2_04\bin\;C:\apache-ant-1.6.2\bin\

Click OK on all the Windows to save the new settings. In order for these changes to take effect you must either log out then back in, or restart your computer.

Once you have done that, then fire up the Command Prompt program once again. Enter "java -version" again and hit the Enter key. This time we should see something similar below. Likewise, enter "ant -version" afterwards:

Output of "java -version" Command
shell image   Java version "1.4.2_04"
  Java (TM) 2 Runtime Environment, Standard Edition (build 1.4.2_04-b05)
  Java HotSpot(TM) Client VM (build 1.4.2_04-b05, mixed mode)

Output of "ant -version" Command
shell image   Apache Ant version 1.6.2 compiled on July 16 2004

If you get an error, please recheck your Environmental Variables entries and proofread your paths very carefully. Did you copy/paste the paths to avoid typos? Check if you restarted the computer or logged out/in. Review the instructions again and double check everything. If all goes well you should get the proper returns from your Command Prompt version check.

Now that everything is set up, we can finally compile TripleA! Open the command prompt and go inside the directory where TripleA was installed. For simplicity sake we will pretend that we have installed TripleA at the root level of C: Drive. So going into the TripleA directory would be as shown below:

Entering The TripleA Directory
shell image   [Step 1]  C:>
  [Step 2]  C:>cd triplea_0_6_0
  [Step 3]  C:\triplea_0_6_0>

Once we are inside the TripleA directory (when the command prompt looks like C:\triplea_0_6_0>) we are ready to issue our ANT commands. Type "ant compile" and the results should yield something similar to what's below:

Results of "ant compile" Command
shell image   Buildfile: build.xml

  init:

  compile:
       [echo] looking for junit.jar, edit .ant.properties to set junit location
       [mkdir] Created dir: C:\triplea_0_6_0\classes
       [copy] Copying 1083 files to C:\triplea_0_6_0\classes
       [javac] Compiling 325 source files to C:\triplea_0_6_0\classes

  BUILD SUCCESSFUL
  Total time: 34 seconds

TripleA is now ready to be run!

- Top -

2.4 Compiling on GNU/Linux, Mac OS X, and UNIX Style Systems

Compiling TripleA on UNIX or GNU styled operating systems such as GNU/Linux, SGI/IRIX, and Apple/MAC OS X (just to name a few), is straight forward. As always we assume that you have ANT, JUnit, and a suitable Java SDK installed as mentioned in section 2.1.

There are four main steps that need to be take to successfully compile TripleA.

  1. Download TripleA
  2. Unzip TripleA in a suitable directory
  3. Edit the .ant.properties file
  4. Execute the ant compile command

Step 1

We can safely assume that you have downloaded the TripleA zip file that contains the source code. The file name should have the word "source" in it; like so triplea_source_0_6_0.zip.

Step 2

Unzip the TripleA source zip file into a suitable directory of your choice. You can use your favorite extraction utility to do this. We have found that most UNIX styled systems tend to have the unzip command available.

shell image   unzip -L triplea_source_x_x_x.zip

Step 3

Using your favorite text editor open and modify the .ant.properties file that is located in the TripleA root directory (ie. /home/george/triplea_0_6_0). If this file is missing then please create one with the same name. Make sure that it begins with a dot as it is supposed to be a hidden file.

It is not necessary to have a .ant.properties file to compile TripleA, but it is needed when making zip releases and using JUnit.

These are the values that .ant.properties keeps track of:

  • The absolute path of JUnit
  • Version number of TripleA

Info For The .ant.properties File
text image   junit.jar=PATH TO THE JUNIT JAR FILE
  triplea.version=X_X_X

As always, for completness sake; this is an example of how a .ant.properties file would look like:

Example Of The .ant.properties File
text image   /usr/junit3.8.1/junit.jar
  triplea.version=0_6_0

Step 4

Open up your favorite terminal and go inside the root of the TripleA directory. Once there, execute the ANT command below to compile TripleA:

text image   ant compile


This should yeild some successful ANT compile messages as shown below:

Results of "ant compile" Command
shell image   Buildfile: build.xml

  init:

  compile:
       [echo] looking for junit.jar, edit .ant.properties to set junit location
       [mkdir] Created dir: /home/george/triplea_0_6_0/classes
       [copy] Copying 1083 files to /home/george/triplea_0_6_0/classes
       [javac] Compiling 325 source files to /home/george/triplea_0_6_0/classes

  BUILD SUCCESSFUL
  Total time: 34 seconds

TripleA is now ready to be run!

- Top -

3.0 Running TripleA

Getting TripleA to run is a little bit different depending which operating system it is running from. Further more, different variants of a similar operating system have their own little way of doing things. For example, various GNU/Linux distributions like to organize their programs in different directories. Such as having games in /usr/share/games and their respective binaries or start-up scripts in /usr/bin/games, or perhaps in /usr/bin, or maybe have the game in /opt and the binaries in /usr/bin.

As we can see, there are many different ways of installing and running programs on different variants of an operating system (let alone different operating systems.) This section will attempt to go over the basics of how to get TripleA running on on various operating systems and provide some useful details on how to customize TripleA's start-up routine.

- Top -

3.1 Microsoft Windows Systems

For TripleA to run on a Windows Operating System it would need to execute the triplea_windows.bat file. This file will run the appropriate java command that will start-up TripleA.

A word of caution: The actual java command is rather lengthy and won't fit in a standard 1024x768 screen size web-browser. Thus the command is really one large line and not two separate lines. It may appear as so if the browser window is not large enough.

Contents of triplea_windows.bat
shell image   @echo off
  java -classpath lib/patch.jar;classes;lib/looks-1.3.1.jar;lib/backport-util-concurrent.jar games.strategy.engine.framework.GameRunner
  pause

Steps can be taken to create a Windows short-cut file and have it point to the triplea_windows.bat file. It can also use a TripleA icon image that can be found in the icons folder inside the TripleA folder.

- Top -

3.2 GNU/Linux, Mac OS X, and UNIX Style Systems

TripleA provides two start-up shell scripts for these operating systems:

Both of the shell scripts above contain identical start up commands. The reason why the decision was made to provide two was mainly for Mac OS X users. Since Mac OS X is UNIX based they use the same start-up script as you would use for GNU/Linux or SGI/IRIX. It would seem weird for the average Mac user to be using a script labeled as "Unix".

A member of the TripleA community (DMan) has generously provided an improved shell script for TripleA. The flow of execution of the script is as follows:

  1. Check if Java is installed
  2. Get the relative directory of TripleA
  3. Enter the relative directory of TripleA
  4. Execute the Java command

Contents of triplea_unix.sh & triplea_mac_os_x.sh
shell image   #!/bin/sh

  if ! java -version >& /dev/null
  then
         echo "Could not find Java."
         echo "You must have Java installed and in your path."
         exit
  fi

  relativePathToGame=`dirname $0`
  cd $relativePathToGame

  java -cp lib/patch.jar:classes:lib/looks-1.3.1.jar:lib/backport-util-concurrent.jar games.strategy.engine.framework.GameRunner

- Top -

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

info image
File Name GameRunner.java
Package games.strategy.engine.framework
Method Header public static File getRootFolder()
java image
public static File getRootFolder()
{
	// This will fail if we are in a jar file.
	// What we are doing is looking up the URL of GameRunner.class
	// We are guaranteed to find it because we are in it.
	// 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
	{
		fileName  = URLDecoder.decode(fileName, "UTF-8");
							
	} catch (UnsupportedEncodingException e)
	{
		e.printStackTrace();
	}
									
	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;
}

- Top -

4.0 Network Configuration

TripleA is capable of working through a network and thus some users may need to do some extra configuration. This is intended for users who have firewalls , routers, and other similar items that filter or re-route network traffic.

Sometimes some users may experience difficulties getting TripleA to act as a game server in order to host games. This is usually due to one of these three circumstances:

Most users have difficulties with the above and will usually not find a problem getting TripleA to act as a client. Normally firewalls will allow applications to make outbound connections, and disallow un-authorized inbound connections to ports not specified in their rules list (or allow list.)

- Top -

4.1 Acquiring the IP Address

In the past TripleA had some problems trying to acquire the IP address on machines that had aDSL and Cable modems as well as a regular dial-up modem. Sometimes it would only get the loop-back address (127.0.0.1). However this has been fixed in later versions of TripleA.

However, there still remains a slight problem with the detection of IP addresses. TripleA is currently (as of version 0.6.0 and below) fitted to acquire its IP address from a network interface located on the local machine it is running off from. It has been known that when a machine is behind a router, TripleA would always select the local LAN IP address of the machine instead of the actual internet address that has been assigned to the router.

A router will have the "real" IP address that others will see on-line. The router communicates with the local machines it is connected to, those machines have locally assigned IP address such as 192.168.0.2 for example. TripleA will, more often than not, acquire that IP address and display it when the user starts a server game. Though, this does not mean that all is lost. If the router is properly configured to forward packets to the local machine running TripleA then all is fine. TripleA uses port 3300 when acting as a server. If the router is forwarding packets going to port 3300 to 192.168.0.2 then the user has a successful server. Leaving aside that TripleA is displaying the wrong IP address, TripleA is attaching itself to the correct network interface.

In essence, one can say that this is just a matter of TripleA finding out what IP address the router is using, in order to display it in the game so the user can advertize it.

router diagram
Fig 4.1.0

TripleA uses an IP Finding algorithm that collects all network interfaces on the computer it is running from and itterates through them to find a suitable IP address. The source code below will demonstrate this.

info image
File Name IPFinder.java
Package games.strategy.net
Method Header public static InetAddress findInetAddress()
java image
/**
   We iterate through an enumeration of network interfaces on the machine
   and pick the first IP that is not a loopback and not a link local.
   In the case of IRIX computers connected on a LAN through a central
   gateway running java off a telnet session will result in a null
   network interface (patched below).

   @exception java.net.SocketException       required by InetAddress
   @exception java.net.UnknownHostException  required for getLocalHost()

   @return    java.net.InetAddress           the ip address to use
*/
public static InetAddress findInetAddress() throws SocketException, UnknownHostException
{
	Enumeration enum1 = NetworkInterface.getNetworkInterfaces();

	if(enum1 == null)  //irix patch
	{
		InetAddress ip1 = InetAddress.getLocalHost();
		return ip1;
	}
	else
	{
		while (enum1.hasMoreElements()) 
		{
			NetworkInterface netface = (NetworkInterface)enum1.nextElement();
			Enumeration enum2 = netface.getInetAddresses();
				
			while (enum2.hasMoreElements())
			{
				InetAddress ip2 = (InetAddress) enum2.nextElement();
				if(! ip2.isLoopbackAddress())
				{
					if(! ip2.isLinkLocalAddress())
					{
						return ip2;
					}
				}
			}
		}

		//If all else fails we return the localhost
			
		InetAddress ip3 = InetAddress.getLocalHost();
		return ip3;
	}
}

TripleA could detect the router's IP if it establishes a socket connection to some computer on the Internet. It has been decided not to use this method as it yields suspicious activity. A user wondering why TripleA is making a connection to www.sourceforge.net (for example) every time they start a server.

- Top -

4.2 Firewall Configuration

A firewall could be the reason why TripleA is not being able to successfully connect to another computer. Many systems now have firewalls acting as a security barrier that filters network traffic to and from the computer. It is sometimes needed that the user running TripleA needs to configure their firewall to allow TripleA to communicate to the Internet.

TripleA can be set to use any port, but the default port it uses is 3300. The user will need to configure their firewall to allow outbound and inbound connections originating on port 3300 only. If asked to describe what protocol to allow, choose TCP/IP & UDP.

Some operating systems such as Microsoft Windows might be running two firewalls at the same time. This is mainly due to Service Pack 2 enabling the internal Windows firewall by default. Users must be aware of this and either disable the internal firewall (only if they have another firewall also running) or configure it so that it allows TripleA to connect to the Internet via port 3300.

- Top -

4.3 Routers and Port-Forwarding

A router needs its port-forwarding configured to forwards all TCP/IP & UDP packets coming on port 3300 to whatever computer the user is using to run TripleA on. Please see Section 4.1 for more information and a diagram.

It may not be needed to make these configuration changes for TripleA to connect as a Client, but is definitely needed when TripleA is acting as a server.

- Top -

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, A&A Pact of Steel and BigWorld 1942 uses customized images, maps, and XML files but are still bound to the game logic of Axis And Allies 4th Edition 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.

- Top -

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.

The entire TripleA package needs to be compiled for the utilities to work.

- Top -

5.1.1 Center Picker

Run the center picker from the classes directory.

How to run Center Picker
shell image   cd classes
  java util/images/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.

- Top -

5.1.2 Polygon Grabber

Run the polygon grabber from the classes directory.

How to run Polygon Grabber
shell image   cd classes
  java util/images/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.

- Top -

5.1.3 Placement Picker

Run the placement picker from the classes directory.

How to run Placement Picker
shell image   cd classes
  java util/images/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.

- Top -

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 classes 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/classes/games/strategy/triplea/image/images/maps/revised

How to run Auto-Placement Finder
shell image   cd classes
  java util/images/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.

- Top -

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
shell image   cd classes
  java util/images/TileImageBreaker

tile image breaker
Fig 5.1.5.0

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.

- Top -

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
shell image   cd classes
  java util/images/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
(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.

- Top -

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
shell image   cd classes
  java util/images/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

- Top -

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/classes/games/strategy/triplea/image/images/maps

  2. Name of the map directory must be same as the "mapName" field in the XML game file for that game. For example; AA4th_edition.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)

  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 No. User Action
(1) Go into directory: triplea_0_6_0/classes/games/strategy/triplea/image/images/maps
(2) Create new directory called viper
(3) Go back to the base of classes Save 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 !

- Top -

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:

- Top -

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 (true/false) Sets relief images on or off by default
map.showCapitolMarkers Boolean (true/false) Display capital markers images
map.scrollWrapX= Boolean (true/false) Lock X-Axis scrolling
map.scrollWrapY= Boolean (true/false) Lock Y-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
text image   #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

- Top -

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
text image   triplea_0_6_0/classes/games/strategy/triplea/image/images/flags

Below is a list of TripleA's captial markers that are used for Axis & Allies 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
text image <option name="capital" value="Germans"/>

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

Capital XML Option
text image <attatchment name="territoryAttatchment" attatchTo="Germany" javaClass="games.strategy.triplea.attatchments.TerritoryAttatchment" type="territory"> <option name="production" value="10"/> <option name="capital" value="Germans"/> </attatchment>

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
text image   United Kingdom (709,292)
  Germany (981, 532)
  Russia (1723,337)
  Japan (2711,686)
  Eastern United States (33,616)

- Top -

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
text image   triplea_0_6_0/classes/games/strategy/triplea/image/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
text image <option name="victoryCity" value="true"/>

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

Victory City XML Option
text image <attatchment name="territoryAttatchment" attatchTo="Karelia" javaClass="games.strategy.triplea.attatchments.TerritoryAttatchment" type="territory"> <option name="production" value="10"/> <option name="victoryCity" value="true"/> </attatchment>

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
text image   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)

- Top -

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 Axis and Allies games, so the following sections shall use those as examples.

- Top -

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
text image <?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/data/games/strategy/engine/xml directory.

Definition Sheet
text image <!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 Axis And Allies 4th Edition 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
text image <info name="4th Edition" version="1.2"/> <loader javaClass="games.strategy.triplea.TripleA"/>

- Top -

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
name="   " String Name of the territory
water="   " boolean (true/false) True if this territory is a sea zone

Two qualified examples:

Territory Example
text image <territory name="Argentina"/>

Territory Example
text image <territory name="Atlantic Ocean" water="true"/>

- Top -

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 territory
t2="   " String Name of the destination territory

Connection Example
text image <connection t1="Venezuala" t2="Brazil"/>

- Top -

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
name="   " String Name of the resource

Resource Example
text image <resourceList> <resource name="IPCs"/> </resourceList>

- Top -

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
name="   " String Name of the player
optional="   " boolean (true/false) 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
text image <playerList> <player name="Japanese" optional="false"/> <player name="Germans" optional="false"/> <player name="British" optional="false"/> <player name="Americans" optional="false"/> <player name="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>

- Top -

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
name="   " String Name of the unit

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

- Top -

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 an Axis And Allies 4th Edtion 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
name="   " 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
text image <delegate name="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 Axis And Allies 4th Edition XML file:

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

- Top -

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
name="   " String Name of the step
delegate="   " String Delegate name
player="   " String Player name
maxRunCount="   " Integer Number of maximum occurances
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
text image <step name="russianBid" delegate="bid" player="Russians" maxRunCount="1"/> <step name="russianBidPlace" delegate="placeBid" player="Russians" maxRunCount="1"/>

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

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

- Top -

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&quto;. 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
name="   " 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
text image <productionRule name="buyTanks"> <cost resource="IPCs" 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 Axis And Allies 4th Edition, 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
name="   " 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
name="   " String Name of frontier rule

A practical example:

Production Frontier Example
text image <productionFrontier name="production"> <frontierRules name="buyInfantry"/> <frontierRules name="buyArtillery"/> <frontierRules name="buyArmour"/> </productionFrontier> <productionFrontier name="productionIndustrialTechnology"> <frontierRules name="buyInfantryIndustrialTechnology"/> <frontierRules name="buyArtilleryIndustrialTechnology"/> <frontierRules name="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
text image <playerProduction player="British" frontier="production"/>

- Top -

11.0 Credits & Acknowledgements

- Top -


sf logo
support