TripleA User Manual v1.3

By: NeKromancer


A: Installing TripleA


There are two methods of installing TripleA, one is by downloading and installing the pre-compiled version, while the other is downloading the source code and compiling it your self. This section will go over both methods and outline important points.

1.0 Installing the pre-compiled version

We will assume that you have already downloaded the pre-compiled version and that you now have a file on your system called "triplea_x_x_x.zip" The x's represent the current version number.

Once you have decided where on your system you would like to install TripleA, it is now time to extract (or unzip) the contents of the downloaded file. If your running a Windows operating system you extract the file by using WinZip or WinRAR software. If you have those installed on your computer, the file should have the WinZip or WinRAR icon. You can double click on the file and the extraction program will guide you to where you wish to unzip its contents.

Alternatively if you use Unix or a variant (such as Linux) you can unzip the file using a GUI front end called ARK, or using command line tools such as unzip (ie. unzip -L triplea_x_x_x.zip) that will extract all of the contents into the current directory you are in. Commands may vary from different flavors of *nix.

By now you should have been able to extract the TripleA zip file into a directory. You will notice that you now have a folder called triplea_x_x_x where TripleA's game files are. Thats basically it on installing TripleA. You only need to extract all the files into a directory or folder. From there on you just run the game.

2.0 Installing From Source

Why compile from source? There are actually many reasons, one being the type of Java Virtual Machine you have installed. Some JVMs run differently and compile java source code differently and may act strange on other JVMs. An example is running java byte code that has been compiled using Sun's JVM on a JVM done by IBM for example.

Some JVMs have different optimization features and other features that is beyond the scope of this document. Though if you feel you need to compile from source because you use a different JVM than SUN or maybe because you just like compiling everything from source, then go right ahead. No one is stopping you :)

To install TripleA from source you will need the source package which you can download from the TripleA website. We shall assume you already have this file downloaded and are ready to extract it's contents.

The first step is to extract the contents of the zip file into a location of your choice. Steps on how to extract the file can be found in Section A 1.0 of this document. Once you have extracted all the files, you will see a folder named "triplea_x_x_x". Note that it has the same name as the pre-compiled package so 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.

Before you even begin compiling, you need:

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. Create a text file and name it exactly like so ".ant.properties" Open this file and add the following information:

unit.jar=PATH TO THE JUNIT JAR FILE
junit.home=PATH TO THE JUNIT DIRECTORY
triplea.version=X_X_X

For a more suitable example let me show you my ".ant.properties" file. It is on my Linux system where I have Junit installed in my home directory.

junit.jar=/home/necro/junit3.8.1/junit3.8.1.jar
junit.home=/home/necro/junit3.8.1/
triplea.version=0_4_2

These fields point to the location where Junit is installed so that ANT can use them while you compile.

After you get a suitable ".ant.properties" file created, it is time to actually compile TripleA. You will need to be in a DOS prompt, or some form of terminal/console/command prompt where you can type in commands. In the base directory of TripleA, issue the command:

ant compile

If everything has been set up properly it should compile TripleA and yield a similar output as below. The output below is what shows up when I run the command to compile my copy of TripleA:

Buildfile: build.xml
init:
compile:

[echo] looking for junit.jar in:/home/necro/junit3.8.1/junit.jar, edit ant.properties to set junit location
[javac] Compiling 321 source files to /home/necro/programs/triplea_src_4.1/classes

BUILD SUCCESSFUL
Total time: 8 seconds

A small note on using the "ant" you can issue one of the following commands to "ant". Each will yield a different result.

There are more commands that can be used and you can find them in the "build.xml" file. You can even make your own if you wish.

After a successful compile, TripleA is now ready to be run.


B: Running TripleA


Now that TripleA has been installed, either from the pre-compiled version or from source, it is now time to actually run the game. This section will go over how to run the game on various operating systems.

1.0 Running TripleA on Windows

Simply open Windows Explorer, or whatever program you use to browse files around your computer. Find your TripleA folder and go inside the "bin" folder. Inside there you should find a file called "triplea.bat"This is the file that Windows users are expected to double click on (or run through a DOS prompt) to get the game started.

2.0 Running TripleA on Unix/Linux/Irix/Mac OS X

Go into the directory in which you installed TripleA. From there enter the "bin" directory. You should see a file called "triplea.sh" You will need to change the permissions on that file in order to make it executable. Running the command:

chmod +x triplea.sh

will give the file executable permissions. Once that is done you can run the actual file by issuing the command:

./triplea.sh

This will cause the game to be run. Though the "triplea.sh" file is not exactly a proper shell script it helps us to distinguish the windows files from the others. The file itself contains the command:

java -cp ../lib/patch.jar:../classes:../lib/plastic-1.2.0.jar games.strategy.engine.framework.GameRunner

This command can be run manually in the "bin" directory from a command prompt but it is quite lengthy and tedious to write all the time. That Java command has proved to work on most Unix, Linux, Irix 6.5, and Mac OS X systems. If you encounter problems with this command please log on to the TripleA message board and request further assistance.


C: Starting a Local Game


This section goes over what a local game is and how to get one up and running.

1.0 What is a local game?

A local game is one where TripleA is played on a single computer with no other human opponents. You are basically playing the all the nations on your own since there is not current AI implementation.

2.0 Starting a local game

When you run TripleA you should see a start up window with a given list of options, as described in Fig 2.1

Fig 2.1

As can be seen, the "Local Game" option is chosen by default when the game is first run. You can see it in the first box labeled "Game Type" that has two buttons. The button that has the label "Local Game" once clicked will drop down more options to choose from.

A local game can be of any type, by default the classic A&A game is chosen. You can of course change this by clicking on the "File ..." button located in the second box labeled "File." This will show you a window where you can select from various game types.

You can, as well, load a saved game. You do so by clicking on the "New" button that is located next to the text "Start a New Game or Load a Saved?" By clicking on the button next to the text it will drop down more options. You want to click on the "Saved" option that is presented once the button is clicked. Only after that do you click on the "File ..." button and select the saved game you wish to load.

Once you have made up your mind on what kind of game you would like to play. It is time to actually start the game. You hit the mighty "Play" button and wait while the game loads. You could always hit "Exit" and go over to your kitchen and get a refreshing drink.


D: Starting a Multi-player Game


To start any multi-player game you need one person to host a server and the other persons to connect to the server as clients. Who gets to be the server is up to you and your opponents. Normally you would want the server to be someone with a fast Internet connection that can handle multiple connections though this does not have to be the case.

1.0 Starting a Server

To start a server you simple run TripleA as normal. When you see the start up window, select "Server" as your game type like so in Fig 1.1

Fig 1.1

The moment you click on "Server" you will get a smaller window popping up that asks for two extra types of input: Name and Port (Fig 1.2)

Fig 1.2

In the "Name" field you enter the name of the server. It does not have to be "Server," it can be your name or practically anything. It will be that name you choose that will identify you in the chat room. That is merely the purpose of it.

In the "Port" field you have to enter at what port number TripleA will listen to for connections. This will also be the port number that the clients will have to connect to. The default port number TripleA sets is 3300. This number can be changed to your heart's desire but note that on many Unix like systems any port number below 1024 is reserved and needs root (administrator) privileges to access. So it is always a good idea to have a port number greater than 1024.

If you have a firewall running or a router, you will need to choose the port number carefully. If you just run a firewall on your local machine, then make sure you choose a port that allows incoming and outgoing connections on that specified port. If you have a router that requires you to use port forwarding or your on a LAN going through a gateway, then it is your responsibility to set up your router, port forwarding, firewall ...etc properly so that this works.

Once you have selected an appropriate name (maybe something intimidating) and a port number you are sure will work. It is time to hit the "OK" button and move on to the next stage. A chat window will appear that will look like so in Fig 1.3

Fig 1.3

Some interesting things to note about the chat window. For every message being typed, the window will automatically be brought to the front. This avoids you missing out on important messages if the window gets lost behind other windows. For every message being sent a sound will play (you can disable this once the game starts). Lastly, you can right click on a person's name and have the option to "Slap" them. This will show a message that you "Slapped" them and the person being slapped with hear the sound of a machine gun being played. You can use this to alter someone or something.

Aside from the chat window, you will notice that the same start-up window is still there. What you need to do is click on the "Server Tab" from which you can see some editable server properties. By default the server is selected to play all countries, so your going to have to change that. You also get to see what IP address TripleA is using for the multi-player game, see Fig 1.4.

Fig 1.4

This has become and increasingly troubling issue when you do not see the IP address that you use to log on to the Internet but rather see your Ethernet address, LAN, address of local host address. You should not be able to see your local host (127.0.0.1) address since TripleA automatically discards the loopback address. It has been seen that on some strange network setups, that it detects the LAN address, and on some proper setups it detects the gateway's Internet address (which is what we want) instead of the LAN address of the current computer. For more information on how TripleA detects the IP addresses please refer to programmer comments in the IPFinder.java source code file.

Assuming everything is going as planned, you can give out your IP address to your friends so that they can connect to you. Then you wait for them to connect, chat a bit, edit some of the options...etc. Clicking on the "Properties Tab" will allow you to change some game rules as seen in Fig 1.5.

Fig 1.5

Only the Server can start the game by hitting the "Play" button.

2.0 Connecting to a server as a client

When there is already one person acting as a server and you have their IP address and their port number, then your ready to connect as a client. First off you need TripleA running (yes it is obvious), where the "Game Type" labeled box is select "Client" like so in Fig 2.1.

Fig 2.1

The moment you click on "Client" you will be presented with a smaller window that will give you three options: Name, Server Port, and Server Address, see Fig 2.2.

Fig 2.2

In the "Name" field you simply enter in any name you want to use. This will identify your self in the chat room. In the "Server Port" field you will enter the port number that the person hosting the server decided to choose. This goes the same for the "Server Address" field. Whoever is the server will have to give you those two piece of information for you to fill in. Once you filled in the appropriate fields you can safely click on the "Connect" button.

Once you see a chat window appear then you know you have successfully connected to the server. The server is responsible for choosing what countries they will play and each client is responsible for picking what country they will play. This can be done by looking at the TripleA start-up window and at the top clicking on the "Client" tab. You will see a list of countries and check boxes adjacent to them.

Once everyone has decided what country to play, it is up to the server to start the game. If the server is taking a while, feel free to slap them in the chat room. Right click on their name and "Slap"


E: Play By Email (PBEM)

TripleA's PBEM mode allows multiple players to play a turn each and send each other the saved game file. This allows them to play the game with each other with out being connected to the internet for long periods of time. The dice rolls done in a PBEM game are rolled by a 3rd party who emails each player the dice rolls and each email is PGP signed and can be verified from their website. The server being used to roll the dice is located at http://www.irony.com/mailroll.html

IMPORTANT NOTE Although PBEM does work in TripleA there is one problem you will have to face. When engaing in a battle, your opponent cannot select their own casualties! You have to select their casualty for them! This may not be a big deal for some but it is for most.

To start playing a PBEM game you have to load up TripleA. At the startup window you select the "PBEM" option from the "Game Type" list. After that is done you will notice a "PBEM" tab show up next to the "Properties" tab, you will click on that.

There are multiple email address fields. You fill them out approprietly with your email address and your opponent's email address. This means that when you play the game all dice rolls will be emailed to those addresses you specified. To verify that those email addresses work and to verify that the dice rolling server is also working, you click on the "Test Mail" button. You should see a small window appear showing the results of the tests. It is also wise to check your email to see if the mail arrived and what it says in there.

Fig 1.0

Once the test succeeds then you can begin the game by hitting the "Play"button. You play your turn and (as mentioned in the first paragraph above) during battle you have to select your opponent's casualties because you cannot save the game in the middle of a battle. Once you finished your turn, you save your game and send the saved game file to your opponent.

The steps your opponent have to take to load the PBEM game are as follows. They load up TripleA as normal. Select "PBEM" from the "Game Type" options list. Then, in the same place they choose to load a "Saved" game. They browse their computer and select the PBEM saved game file that their opponent sent them. Once they have selected the PBEM saved game file, they are now ready to click on the "PBEM" tab located at the top of the window. Once they are in that section, they have to fill out the email addresses approprietly as done above (can also opt to hit "Test Mail"). When that is done they can hit the "Play" button. They will see that they are now at the last place their opponent left off at (obviously). They do their turn and save it when they are done and send it to their opponent. And the cycle continues.

Possible PBEM Workarounds

Since opponents cannot select their own casualties, you can have a general consensus with your opponents on what casualties should be selected at what kinds of battle scenarios. These actions can be double checked by checking the emails that the dice server sends. So if someone cheats and kills off 5 tanks instead of 5 infantry, it will be painfully obvious of the foul play.

Players can engage in what is called a "Hot-Potato" game. This is when around a minimum of 2 or a maximum of 5 players wish to play a game with each other. What happens is that one person plays a local game on their computer being allies, conducts their turn, plays the battles, and at the end of their turn they save the game. Once the game is saved they e-mail it to the next person to play their turn. This goes on being saved and sent to each player until the game is over.

Some rules need to be agreed on before doing such a game. One of them will be to agree on what casualties to select when conducting a battle. Since a battle will be done by 1 person and that person has to select the casualties of their opponents and whether or not to submerge their submarines. Come to a general consensus about what to do. This is not a bad idea since you actually can double check what each player did, thanks to TripleA's history mode. You can look back and see exactly what happened, and what dice were rolled. This way you can verify if there was foul play. Of course if you notice that someone has been cheating and killed off your fighters instead of your infantry for example... then you can opt to stop the game and never play with that person again. Choosing opponents will be of utmost importance here. Make sure you play with people who won't cheat on you.

One down side would that anyone could re-play their turn over and over until they get suitable dice. You cannot do much about this but as mentioned above.. you should play with people who you can trust will not do that. Even if this is done, in the end strategy wins over dice rolls.


F: Seeking Help and Opponents


1.0 Message Board

The best place to seek help is at the TripleA message board. http://maddlinks.com/triplea/index.php (Thanks to Felix Alicea)

2.0 Finding Opponents

The best place to find an opponent is on the message board. There is a special section dedicated for scheduling games in advanced. This is especially useful for those players who have busy lives and can't pop in the IRC chat room five times a day to check if someone just happens to be there and just happens to have at least 3 hours set aside for a game.

The message board allows you some time to schedule a game and get opponents that are willing to play with you at a specific time. They can later meet up in the TripleA IRC chat room (more info on at http://triplea.sourceforge.net/finding_oponents_irc.html) It is not mandatory to meet in the IRC chat room to start a game, but it is there if anyone needs a place to meet or chat with some of the developers. Sometimes we go in there and chat a bit.

The chat room can also be accessed through the message board's Chat button at the top of the page. It is a Java IRC applet so make sure you have a Java enabled browser.