Table of Contents
In this year's 6.370 contest, your task will be to develop Java programs that
will play a realtime strategy game using virtual droids. Each droid's hardware
will be modelled as a set of abilities which your software will control
through a fixed interface. Software will run in timesliced Java virtual
machines written in Java, what we will call Droid Virtual Machines (DVM).
Using these abilities, droid software will be able to explore the closed
universe, interact with other objects and droids, and race to complete the map.
If you are unfamiliar with RTS terminology, please consult our
There are some differences to note from traditional RTS:
Resources are not gathered and expended from a single, omnipresent
"account" for each player. A droid may only gather and spend resources
There is not a single omniscient player controlling the army. Each droid
has a limited sensor and radio range and must communicate with other
friendly droids to accomplish goals. As such, there is a very
foggy fog-of-war in effect.
There are no buildings per se. One type of droid is stationary, guards
territory, and serves some other functions traditionally associated with
buildings. However, they can also run code like other droids.
There is no human intervention in the action of your droid army.
Once a game begins, your software controls the droids until the game ends
or is aborted.
There are two submission deadlines, and two official maps on which your entry
must compete. In both of them, the goal of your droids will be the search
for and recovery of special artifacts, as described in the
Tournaments & Maps section.
Calendar for a detailed timetable of events.
For the logistics see the section on
submitting your solution.
The first deadline is for your preliminary submission, which will compete
in the seeding tournament. The seeding tournament consists of one match
per team against our reference team.
Your team must beat the reference team by the end of IAP
to receive the 6 EDPs and 6 credits
for this course. All teams will automatically qualify for the final
tournament if they submit a preliminary solution.
Winning a match means recovering the greatest number
of artifacts of any side on the map; ties are broken by mean recovery time.
The total ordering of teams in the preliminary tournament is:
- Number of Artifacts Recovered
- Mean Recovery Time of Artifacts
- Droids Destroyed
- Droids Created
This total ordering is used to determine seeding rank in the
final tournament bracket.
You may then improve your solution until the the second deadline,
when you must submit the version which will compete in the final
What We Provide
We will provide you with a JAR file
that contains the following:
Specifications (this document)
colony.common package which defines the
interface and constants you must use in developing a solution.
packages implemented for the DVM.
HTML documentation for the above packages.
Software to test your solution.
Sample maps and example source code (but not the exact tournament maps or
source code of the reference player).
The compiled bytecode of the reference player (in package
which you must beat in the preliminary tournament to qualify for the
finals and to receive credit for 6.370.
How It Works
In this contest, you will write the software that controls a droid hardware
in the closed universe; see Writing Your Solution
for more details about writing this software. All the Java classes that you
write will collectively be called droid software; specific classes
which implement the
main static method will be called
players. In particular, the class called
Player in your
team package will be loaded by every droid when it first boots up; this
class is known as the primordial player.
Droid hardware is a collection of
abilities, which are constraints on its interactions
with the closed universe, and properties, which
are substates of the droid.
Your code is compiled into Java bytecode and runs on a Java virtual machine
written in Java, called a Droid Virtual Machine, or DVM. There is
a separate DVM for every droid hardware in the engine, each with its
own stack, program counter, static variables, garbage collection, and
heap limit. There are a few exceptions:
if you are replicating a new droid,
it will not have an associated DVM to run code until it finishes
If your droid software throws an uncaught exception or error,
the game engine will
remove the DVM from its collection and the associated droid hardware will
Each droid hardware exports a
to its controlling DVM;
this handle has methods for using abilities, gaining information about
properties, and gaining information about the closed universe.
This handle is the only way your software can interact with other objects,
droids, and the closed universe.
The game engine is what manages all the DVMs, droid hardwares, the map,
the clock, and their interactions. In one cycle, the engine takes the
following actions in order:
Each DVM in the game engine receives an allotted number of bytecode
instructions per cycle, called its timeslice. Each DVM currently
gets 1000 instructions per cycle; the game engine runs these timeslices
in sequences for every DVM in its collection. Some
active, meaning they change game state and end
the calling DVM's timeslice; use of active abilities queues up
After all DVMs have received their timeslice, the engine processes
all queued actions in order to prevent inconsistencies in game state.
Repair actions are always queued before other actions.
See Droid Abilities
Next, the action queue is cleared, and the engine calls a clocktick method
for every clocked object in its collection. All droid hardwares are clocked
objects, because certain properties are updated by the cycle (assembly status,
map position, etc.). In addition, maps can be clocked (to end the game after
a certain number of cycles for example) as well as artifacts (to take
some special action at a specific time).
Finally, the engine increments its time (in cycles), and begins the loop
As mentioned above, time is measured in cycles, which is the
longest continuous sequence of instructions executed by any one DVM.
Distance is measured in spans, which are continuous. Speed
is measured in spans per cycle.
There is one resources in this game, metal ore out of which
all droids are constructed. Ore is measured in a unit called stone and
is available in fixed quantities at certain locations on a map.
A droid's stored ore decreases when it replicates and increases when it
gathers ore. Ore coalsces; that is, if a droid is already carrying ore, any
additional ore it stores will "transfer" hit points over to the carried ore,
rather than being stored itself.
All objects, physical and nonphysical, are identified by
which are permanently
attached to this object upon its creation.
All droids have unique monikers, but entities like abilities and
terrains share a generic moniker. A moniker is analogous to
a name or hash key.
Physical objects, such as a droid or a piece of ore,
have a position on a map and hit points measured in stone.
entities do not have a size; as such, they can occupy the same location or
even pass through each other. Physical entities whose hit points reach zero
are remove from the map and game engine.
Abilities and terrains are examples of nonphysical entities.
Unlike other physical objects, droids have abilities
(including the ability
to store other objects, travel around the map, and replicate)
and are controlled by a DVM which can run bytecode.
Replicants, or droids that have not fully self-assembled, are still physical
objects but are uncontrolled and unpowered until they mature and their DVM
boots up their army's primordial player.
You will control four types of droids in the competition, which have all
the same abilities and properties, but with different parameters
(e.g. different ranges, different hit points).
that the ghetto graphics shown below are from early production
|Land reconaissance and exploration.
|Communications relay and perimeter guard.
|Naval senty unit.
|Aerial transport and scout.
All droids have the same basic abilities, which are described below.
Active abilities cause a change in the game state and cost 1 cycle of time
per use (that is, they are instantaneous and also end your DVM's timeslice).
They cause actions to be queued up while DVMs are running, to be processed
after all DVMs have run. Repair actions are queued up first; all other actions
are queued up in the order they were created.
Passive abilities do not change game state, and may be called multiple times
in one cycle; however, they are idempotent in that calling them more than
once per cycle gives you no new information.
All uses of abilities are
atomic function calls in the DVMs, meaning that they will always return
execution to the DVM before its timeslice ends.
Some abilities manage state for a droid or have ranges/parameters which
are the described in the property table.
The specific syntax for these abilities is discussed in the
PlayerConstants javadoc. All the abilities below are linked directly to their corresponding
moniker constant in this javadoc; moniker constants are passed into
the DroidHandle.useAbility method which is described in the Writing Your Solution section.
Most of these abilities operate on monikers, which you must first retrieve
using the Sensor ability. Using these abilities when their conditions are
not met will have no effect on the game state.
A droid can retrieve the hit points of any object within sensor range,
including its own.
A droid can retrieve the assembly status of any object within sensor range,
including its own. However, a droid that can run code to retrieve assembly
will already be 100% assembled.
A droid can retrieve the position of any object within sensor range,
including its own, as a
A droid can retrieve the velocity of any object within sensor range,
including its own, as a
A droid can retrieve the terrain moniker of any position within its
A droid can retrieve the amount of ore carried by any droid within its
sensor range, including itself.
A droid can retrieve the items stored by any object within sensor range,
including its own stored items, as an array of
A droid can retrieve the moniker of its owner if it is being carried.
A droid can retrieve the amount of storage available in any droid
within sensor range, including itself, as an
amount of available storage is in stone and uses the hit points of all
physical objects, and in the case of droids, all their stored items
A droid can retrieve the number of artifacts left unclaimed on the map
as an array of one Integer.
Droids can receive messages sent using the Radio Transmit ability. Droids
have a maximum buffer size of messages which are stored in a FIFO queue;
when the maximum size has been reached, the oldest message is deleted and
the newest one added. When this ability is used, all buffered messages are
returned the buffer is cleared.
Droids can retrieve the monikers of other free (unstored)
physical objects that are
nearby (within the range of the sensor).
The droid itself does not show up in its sensor readings, nor do its
stored items, nor do any objects carried by other droids. To get
stored items within range, use the GetStorage ability on the owners.
Droids can send messages to each other in the form of a single Byte, Short,
Integer, Long, Float, Double, Boolean, String, Moniker, or MapPoint. You may
not send arrays of these objects or any other types, as was erroenously
stated in previous revisions. The sender does not receive its
own message back. All droids within the range of the transmitter receive
the message; that is, the single transmitted object is queued in each
droid's receive buffer, waiting to be retrieved with the Radio Receive
A droid can reboot itself to load a new class in the team package.
Droids have the ability to carry other physical objects and
have a maximum capacity measured in stone; the storing weight of all
physical objects is their current hit points. The one exception is that
mature hemlocks cannot be carried.
Droids must approach within
a certain distance to store an object (specified in
Currently this is 1.0 spans. A droid that stores an object is known as
that object's owner.
A stored droid cannot itself pick up new
items or travel independently; its position is the same as its carrier.
Droids cannot store themselves.
Storage capacity is measured cumulatively; a droid must have enough
storage capacity for any droids it wishes to carry as well as those droids'
Ore that is stored will
automatically coalesce with any ore that is already present; a droid will
almost never need to retrieve ore monikers once the ore has been stored,
but rather, it can use the GetOreAmount ability. If a droid only has
room for part of a piece of ore, as much stone as will fit will coalesce into
the droid's possession, and the remaining stone will be left on the map.
If two droids simultaneously (in the same cycle) try to store an object,
it will go to the oldest droid (the one who was created first).
A droid has the ability to discard objects that it is
carrying. The discarded objects will be located at the droid's position at
the time of discarding.
A droid can inflict damage on another droid within a certain range. There
is no splash damage; only the droid which is targeted by an attack ability
receives damage. Each droid type can only attack other droids on certain
terrains; these are listed in Droid Properties.
Stored droids can be attacked as a unit on their carrier's terrain, but
can only attack on their original allowed terrains. Replicants can be
attacked whether they are carried or not, but obviously cannot attack back.
If a replicant receives damage faster than it can assemble, it can be
When a droid is destroyed, anything it carries will be
discarded into its owner if any; otherwise stored items will be discarded
onto the map at the location of the droid when it was destroyed.
A droid can use any stored ore to repair damage to itself up to its maximum
hit points. This repair uses an amount of ore equal to the minimum of the
damage amount and available ore amount; repairs occur in 1 cycle.
A droid can replicate another droid of the same type if it is carrying
enough ore. Replicants will appear on the map 1 span
distant from the parent's location at the time of replication. They
are initially unpowered and have 0 hit points; they require
a certain assembly time before they gain a DVM and can run code. During
assembly, their hit points increase linearly to their maximum value;
a replicant can be attacked at any time while it is assembling and can
be destroyed before it finishes assembling.
A droid can set its destination at a certain
proceed their in a straight line at maximum velocity. However, certain droid
types can only travel at certain speeds on certain terrains; see
Droid Properties for details. Once a
a destination is set, the droid can perform other actions while moving,
including attacking, storing, discarding, repairing, and replicating.
A droid can change destinations at any time, even whilst moving.
Ends a DVM's timeslice.
Note that there is no property of energy and no special abilities (talents).
|Radio Buffer Size(messages)
||0.5 water, 0.1 land
||1.0 land, water, mountain
||Can attack units on
||Land, Water, Air
Hit points are measured in stone and equal the amount of ore necessary
to initially replicate the droid and also how much damage the droid can
sustain before being destroyed.
Storage is the amount that a droid can carry in stone, whether its
cargo is ore or another droid.
Assembly time is the number of cycles between the time a droid is
first replicated to the time it is active and can run code.
Maximum velocity is the maximum rate of change in the position
of a droid, measured in spans per cycle.
Tournaments & Maps
Maps are two-dimensional arrays of grid points that are either
land, water, or mountain. Mountains are impassable to both land and water
units. Flying units are in the air terrain, which encompasses
all three of these floor terrains. There will be two tournament maps, one
for the preliminary tournament and one for the final tournament. The
parameters that will remain fixed across each tournament (but may differ
between the preliminaries and the finals) are:
- Map size (from 500x500 to 1000x1000 spans in size, will not necessarily
be a square)
- Map terrains and layout (land, water, and mountain)
- Number and type of starting droids (always 4, one of each type)
- Amount and distribution of ore (500-1,000 stone total in 10-50 quantities)
- Goal (collecting the majority of artifacts)
- Time limit (10,000 cycles)
Parameters which will vary randomly from match to match within the same
- Starting location (randomly chosen from several tactically equal positions), always near water, with all four initial droids within sensor range of each
other (within a radius of 10 spans, the smallest sensor range (scion)), and
the sea dragon in the water.
In the preliminaries, the number and distribution of artifacts will be
fixed for all matches, and carrying mature hemlocks is allowed.
In the finals, the number and distribution of
artifacts will be random for all matches, and the carrying of mature hemlocks
is not allowed. The number will range from
5-21 inclusive, always odd.
Ore will be distributed in small quantities (no mines) around the map;
it may be located anywhere on the map on any terrain. Both artifacts and ore
are indestructible. Artifacts will be 50 stone in weight. Artifacts will
not be located in mountains, or in an enclosing ring of mountains.
Maps have a goal which is installed into every droid's
handle. All maps in the tournaments will have the goal of collecting
as many artifacts as possible; the map will end
when the majority of artifacts are in the
possession of one side's droids or time runs out, whichever occurs first.
If no artifacts have been collected when time runs out, both teams are
disqualified and the next match is a bye for its corresponding team.
If the majority (over half) of the artifacts have not been collected
when time runs out, the team with the plurality of artifacts (more than
any other team) wins the match.
If two teams recover the same number of artifacts that is less than
the total number of artifacts, the team with the shorter mean recovery
time wins. (The mean recovery time is the time of last artifact recovered
divided by the number of artifacts recovered at the end of the match).
A map has a certain number of positions called sides
which can be filled by opposing teams. In all of our tournament matches,
there will be two sides who will compete to proceed to the next match.
Other than the information given in these specs, you will not be given any
other information about the tournament maps, and you are strongly discouraged
from optimising your solutions for any particular map.
Writing Your Solution
All your source files must use the same root package name.
Specifically, all your source files must begin with the line:
where <xx> is the two-digit team ID number you received upon
registration and which is available on the
teams list page.
You may use additional subpackages of your root team package if you wish.
One of your source files must be named
Player.java and define the
Player. This class, and any other player class into
which you would like to reboot, must have a method with the following
public static void main(DroidHandle handle)
This is the entry point into your code; you should not let execution
return from this method.
Define any other modules or subpackages that you need.
Make sure your code complies with the following requirements:
Your team submission should use the root package teamxx.
The team package should include a class named
class, and any other player class into which you would like to reboot,
must have the following method signature:
public static void main(DroidHandle handle).
The team-written source code should not make use of the Thread class,
the Runnable interface, or in any way spawn more threads of execution.
The team-written source code should only make use of the
implementations that we document in the contest Javadocs.
The team-written source code should not interface with non-Java source code,
compiled native libraries, compiled Java bytecode, or any Java
source code not written by the team explicitly for this particular contest.
Specifically, use of Java's Reflection classes, class loading,
file system operations, and network operations is not allowed.
For your edification, example code is dissected online.
Testing Your Solution
Note that when you test your solution with our software, you are helping
us test the final game engine as well. Please report any bugs or send
feedback to firstname.lastname@example.org.
First download and extract the jar file
It will produce the following directory structure
- classes/ - compiled bytecode of the contest software.
- docs/ - Javadoc HTML documentation for the common classes.
- conf/ - configuration files for the game engine
- images/ - icons and sprites used in contest software
- maps/ - map images
- logs/ - server and engine log files
- sources/ - example code
- specs.shtml - this document
Then you can compile your solution using the provided
package by including the
classes subdirectory in your classpath.
In order to test your solution, you will need to configure and start the
simulator by editing the plaintext file
It contains one team per line, with seven
to nine comma-delimited tokens, depending on whether a team has one, two, or
three members. Note that the line below has been broken to fit on the page,
but in the conf file it is one line.
For the server to locate your class, be sure to
include the appropriate package name for one of the teams.
Currently the built-in simulator map handles exactly two teams; you must
enter at least two lines in the following format (they may be the same).
To run the simulator, add the Sun 1.3.0 JDK by typing:
add -f jave
Then go to the
6.370 root directory and type:
java -classpath .:classes:<path_to_your_classes> colony.simulator.SimClient
If you are using Windows, substitute ';' for ':' above. If you are using
Cygwin, enclosing the entire classpath argument in double quotes. Note that
if you forget to include the current directory in the classpath (the leading
period), the JVM will not be able to find the sprites, maps, or conf files,
and you will be in a world of hurt.
You can configure the map by reading and modifying the file
maps/paleriver.map. It is a plaintext file with one
directive per line; each directive has one or more parameters.
You may use your mouse to drag the map around in the scroll pane, or you may
use the minimap in the lower-right corner. Units show up as green dots on
the minimap and static sprites on the main map.
Submitting Your Solution
Your submission consists of one jar file which contains all your team's
source code and documentation. The directory structure should look like:
<jar root directory>/
README - plaintext file describing any compilation issues, the
location of any documentation or tests, and whether or not you would like
to be used for academic judging.
Player.java - your primordial player.
<other source files>
Do not include any enclosing directories or
directory trees, as Java compilers will generate these automatically for
Note that documentation is not necessary for the preliminary submission,
and is only required for the final submission if you would like your
entry to be judged for academic merit and the
Best of Contest special prizes (note this
in your README file).
To pack your solution into a jar file for submission, type:
jar cvf team<xx>.jar -C <path to files> .
Note that the trailing '.' means the current directory, not the end of a
Note the two submission deadlines listed in boldface on the
The first member of your team (as listed on the
teams list page)
should create a subdirectory in his or her home directory named
6.370 and give the Athena group
6370 read permissions
in AFS like so:
athena% mkdir 6.370
athena% fs sa 6.370 system:6370 r
Place your jar file in this directory before the submission deadlines
for retrieval by the contest organisers. You will receive an e-mail within
an hour after the submission deadline telling you either that your solution
validated and successfully compiled or that there are some problems you
need to fix.
If you are experiencing trouble with the software, please make sure you have
downloaded the most recent version first here.
Problem: Receiving the following stack trace:
Uncaught error fetching image:
Solution: Be sure to include the current directory, denoted by a period (.)
in your classpath, as in:
Problem: Can't find class colony.simulator.SimClient
Solution: Be sure you are using the Sun JDK 1.3.0 JVM by typing
add -f java
First make sure your questions are not answered in these specifications
(keeping in mind that they may change over time, as recorded in the
Change Log). If you are experiencing problems
with our software, make sure you have downloaded the latest
jar file, then check the
Troubleshooting section for some common
If you have a technical question about the specs of software,
you can e-mail the 6.370 developers at
If you have an administrative question about the contest, you can e-mail the
6.370 organisers at email@example.com.
Organisers and developers may sometimes haunt the
Zephyr instance. You can write to them by typing:
zwrite -i 6370
There is also an Athena mailing list
for both teams and organisers to
discuss technical issues and answer questions about the contest.
We hope that competitors will help participate in the technical support
Please keep in mind that 6.370 is currently completely student run,
so we might not have all the resources to answer your questions.
Also, the contest organizers assume you have a basic knowledge of Java and/or
have reference materials to consult.
If you have a question about the Java programming language, you might want to
try Sun's Java forums and tutorials at:
Appendix A: Downloads
Revision 5.4, 27 January 2002
Downloading with Netscape (4.7x and lower) in Windows mangles the jar file.
If you are using Windows, use another browser or file transfer method to
get this file.
6370.jar, 1.0 MB
To extract this file, type:
jar xvf 6370.jar
Revision 5.4, 27 January 2002
- Destroyed physical objects are removed from the GUI correctly.
- Assigning small numbers fixed.
- Array bounds checking fixed.
- ArrayStoreException error fixed.
- Recovering majority of artifacts now ends the match.
- Removing objects that are not stored does not cause an error.
- Replicant damage and build time now reflect correctly in their
- Preliminary tournament map included.
Revision 5.3, 25 January 2002
- Object.clone implemented.
- System.arraycopy checks if elements are assignable.
- MapPoint.equals returns true for equal points of tolerance of 0.0.
- Discarded droids take on their current terrain immediately.
- Destroyed droids that are carried discard their stored items into their
You can find older changes on the Change Log page.
Appendix B: Javadoc HTML Class Documentation and Examples
Javadoc-generated HTML documentation
Appendix C: Development Environment
The programming contest will be conducted entirely in the Java language.
You are free to use any development platform, but your solutions must
compile and run in a Sun-certified Java 2 Platform, Standard Edition 1.3.
We recommend using Sun's free JDKs for Solaris, Linux, and Win32 available at:
or IBM's Developer Kit for Linux, Java 2
Technology Edition, Version 1.3.
We will be using Sun's
javac to compile your solutions, but
you may choose to use IBM's high-performance Java compiler called
jikes (v1.15) with Sun's 1.3.0 runtime libraries for your own
development purposes. You can learn more at the
We recommend working on Athena
workstations, which already have all the necessary tools available.
However, we can provide limited support for development on private Linux
and Win32 platforms using the tools described here.
To use JDK 1.3.0 on Athena (and optionally the jikes compiler)
add the following to your
setenv JIKESPATH /mit/java_v1.3.0/jre/lib/rt.jar
Then log out and log back in, or type
If you prefer to work in a POSIX-compliant environment within Windows
with GNU development tools (make, cvs, etc.) we recommend the free Cygwin
environment from Redhat at http://sources.redhat.com/cygwin/.
Appendix D: Configuring the Game Engine
Many parameters in the game engine and the map used in the simulator
can be configured by reading and altering the plaintext conf files in
maps directories, respectively.
- sim.conf - teams used in the simulator
- scion.conf - abilities and properties of Scions.
- hemlock.conf - abilities and properties of Hemlocks.
- seadragon.conf - abilities and properties of Sea Dragons.
- beetle.conf - abilities and properties of Beetles.
- ore.conf - abilities and properties of Ore.
You can find older changes on the Change Log page.
5.325 January 2002:
Revision 5.3 jar file posted in Downloads.
Carrying of mature hemlocks is not allowed for the final tournament,
but will be allowed for the preliminaries.
The following items are clarified in the
Droid Abilities section:
Store: stored items of stored droids are discarded into its owner when they are
destroyed, old droids win simultaneous stores;
Attack: damage to replicants and stored droids.
Current Limitations section removed.
MapPoint.equals fixed to handle tolerances of 0.0.
Changes moved to separate Change Log page.
Submitting Your Solution section finalised.
5.427 January 2002:
Revision 5.4 jar file posted in Downloads.
In the Tournaments & Maps section:
starting positions of droids is corrected to 10 span radius, since the
scion's sensor range is only 10 spans; all droids on a side begin within
sensor range of each other; preliminary tournament matches all have fixed
number of distribtion of artifacts and carrying mature hemlocks is
allowed; final tournament matches will
have a random number and distribution of artifacts, and carrying mature
hemlocks is not allowed.
In the Contest Format section, the total ordering
of teams in the preliminary tournament is described, and winning a
match is clarified. In the Development Environment
appendix, we will be using javac instead of jikes due to some
compatibility issues with certain team submissions.