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.

  1. Download the full package from
  2. Unzip on your harddrive
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. In a new terminal window, go to massim-2013-1.4/massim/scripts
  2. Execute ./
  3. Choose the option that corresponds to the contest you wish to run
  4. In a second terminal window, go to massim-2013-1.4/massim/scripts
  5. Execute ./
  6. From Eclispe, Run the Run Configuration for your class
  7. Press Enter in the first window (where you executed

Running your agent without Eclipse

So far, I've been unable to modify the 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:

  1. Right-click on the project and select "Export..."
  2. Open the "Java" folder and choose "Runnable JAR file"
  3. Pick the Launch Configuration you created for your agent
  4. Choose an export destination and JAR file name
  5. Choose "Extract required libraries into generated JAR"
  6. Press "Finish"
  7. Copy your two config files into the same directory as the JAR file
  8. 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.
  1. From the myAgents directory run:
    javac -d build -classpath /path/to/javaagents/target/javaagents-2.1.jar *.java
  2. From the myAgents/build directory run:
    jar cvf myAgents.jar *
  3. 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.

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:

Evaluating Game Results

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