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 existing source code. I suggest you use massim-all-versions-2013-1.4/javaagents/src/main/java as your directory.
  4. Link additional source (using the Build Path->Link Source option) from massim-all-versions-2013-1.4/eismassim/src/main/java to your project. Because you already have a folder called java, I suggest you type javaeis for the folder name.
  5. Add two external archives (using the Build Path->Add External Achives... option) from massim-all-versions-2013-1.4/javaagents/target/dependency to the project:
  6. 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.
  7. 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.
    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

The "full package" does not include any class or JAR files, but since you have no reason to change the server, I recommend that you simply use the "Getting started" package to run the server and the monitor. Assuming you have unzipped this package, 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, 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 -ei -jar myagent.jar

Configuration for the CSE 431 tournament

Our tournament will consist of pairwise matchups of teams of 10 agents each. For easier visualization, the game will be played on a smaller board than the default. I have also 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: