Agents on Mars Tutorial

This page provides a description of how to start writing an agent program for the 2013 Agents on Mars scenario for the purposes of CSE 431 students at Lehigh University. This is a work in progress!

Setting up the IDE

The folowing instructions assume that you are using Eclipse. Users of other IDE's will have to modify to fit their environment as appropriate.

Download the full package from https://multiagentcontest.org/2013/massim-2013-1.4-bin.zip
Unzip on your harddrive
Create a new Java project from the directory. Note, there are subdirectories documents, eismassim, javaagents, massim and webapp. Some of these have a scripts and target subdirectory. The scripts contain bash scripts and a conf subdirectory with configuration options. The target usually contain three jar files: one with classes, one labeled javadoc, and one labeled sources.
I recommend that you connect the javadoc to the appropriate jar files, at least for javaagents-2.1.jar. In Eclipse, right-click on the project, select "Build path --> Configure build path". Then select the "Libraries" tab and expand the the jar file that you want to link javadoc to by clicking on the arrow in front of it. Click on "Javadoc location: (None)" and press the "Edit..." button. Choose the "Javadoc in archive" option and then the "Workspace file" option. Browse to the location of the javadoc, which is typically a jar file with the same name with "-javadoc" appended to it.
Create a new class that extends massim.javaagents.Agent. Implement the step() and handlePercept() methods. In addition to importing eis.iilang.Action, eis.iilang.Percept, and massim.javaagents.Agent, you may find it helpful to import massim.javaagents.agents.MarsUtil. See Section 4 of the javaagents.pdf in the documents directory of your download for more details. You'll also want to look at Section 5 of eismassim.pdf for details on the actions and percepts that are possible.
To test your agent, create a Run Configuration:
1. Set massim.javagents.App as the Main class
2. Put "-ea" under VM arguments
3. Set the working directory to the place where your eismassimconfig.xml and javaagentsconfig.xml files are. Alternatively, copy these files into the default working directory of your project. Note, to do a quick test, you might want to use javaagents/scripts/conf/dummyteam, but this will run the dummy agents provided as opposed to your agents.
4. Make sure that the class attribute in the agent element of the javaagentsconfig.xml file is set to the name of your class. If you have different Java classes for each type of agent, be sure to include each in the correct order.

Testing your agent

Starting up a server and running agents on it is relatively easy. Here's what to do to run a game:

In a new terminal window, go to massim-2013-1.4/massim/scripts
Execute ./startServer.sh
Choose the option that corresponds to the contest you wish to run
In a second terminal window, go to massim-2013-1.4/massim/scripts
Execute ./startMarsMonitor.sh
From Eclispe, Run the Run Configuration for your class
Press Enter in the first window (where you executed startServer.sh)

Running your agent without Eclipse

So far, I've been unable to modify the startAgents.sh script to work with custom agents. Assuming I've placed my .class file in the javaagents/target directory, it should be as simple as adding the classpath to the JRE invocation at the end of the script, a la:

java -ea -classpath ../../../target/ -jar ../../$package

but this hasn't worked for me yet. Fortunately, as long as you don't have too many different agents teams you want to try out, you don't need this script.

If you want an agent you can run without having to have Eclipse installed on the target machine, then from Eclipse, simply:

Right-click on the project and select "Export..."
Open the "Java" folder and choose "Runnable JAR file"
Pick the Launch Configuration you created for your agent
Choose an export destination and JAR file name
Choose "Extract required libraries into generated JAR"
Press "Finish"
Copy your two config files into the same directory as the JAR file
To run an agent packaged in a JAR named myagent.jar...
```
java -ea -jar myagent.jar
```

Compiling and Running without an IDE

(courtesy of Maxwell Anselm)
The steps below assume that all of your agents' java files are in a directory called myAgents and your config files are in myAgents/conf. It also assumes that you want to temporarily place your .class file in a build directory and that the main method is in massim.javagents.Apps.

From the myAgents directory run:

javac -d build -classpath /path/to/javaagents/target/javaagents-2.1.jar *.java

From the myAgents/build directory run:
```
jar cvf myAgents.jar *
```

From the myAgents/conf directory, run your agents with:

java -ea -classpath /path/to/javaagents/target/javaagents-2.1.jar:myAgents/build/myAgents.jar massim.javaagents.App

Alternatively, you can set up the entry point when you create the JAR file:

java cvfe myAgents.jar massim.javaagents.App *

and then run by simply typing:

java -ea -classpath /path/to/javaagents/target/javaagents-2.1.jar -jar myAgents/build/myAgents.jar

Configuration for the CSE 431 tournament

Our tournament will consist of pairwise matchups of teams of 10 agents each. Each team will have two of each type of vehicle. For easier visualization, the game will be played on a smaller board (15 x 10) than the default. Finally, I have tentatively set the number of steps to 200. If the agents don't spend much time before deciding on their actions, this will actually go too fast. However, if agents take the full 3.5 seconds allowed to choose their actions, games will take over 10 minutes. Below is a sample config file for the server that has two teams named A and B. In the actual competition, I'll use your official teamnames and give each team an individual password. However, for now you can use either team A or B to test your agents.

server-config.zip: Unzip this file in your \massim\scripts\conf\. When you run the script to start the server, choose 2013-cse431comp (Note, the startServer.sh script is written such that you can only choose from config files that start with "2013")

I have prepared sample config files for agents that allow you to have teams of 10 dummy agents and/or the team Tagaryen. Here's a zip of the sample files:

agent-configs.zip: Unzip this file in your javaagents\scripts\conf\ directory. There are four different configurations:
- dummy10a - 10 dummy agents as Team A. Can be used to test your team against dummy agents if you are Team B.
- dummy10b - 10 dummy agents as Team B. Can be used to test your team against dummy agents if you are Team A.
- dummy10ab - Both team A and team B with 10 dummy agents each. Can be used to test playing two dummy teams against each other.
- Targaryen10 - 10 Tagaryen agents as Team A. Can be used to test your team against non-dummy agents if you are Team B.

Evaluating Game Results

There are two useful tools for you to see how your agents did in a game. They are:

Game Statistics: The game statistics can be found in the statistics directory under the directory where you started the game server. There is a seperate directory for each game. A number of helpful charts are created, including the distribution of actions for each type of agent for each team, a graph of the change in score throghout the game, and a graph that illustrate zone scores.
Game Viewer: The game view allows you to replay a previous game step-by-step. Think of it as kind of an instant-replay. To use it, go to your massim/scripts directory and type:
```
startMarsFileView.sh xmls
```
(xmls is the directory where game information is stored). Then press the button Change Match (in the top-right) and select a game you wish to view. You can then step through at your own space, inspecting the information about agents and nodes by clicking on them.