FalloutBots
by Ari Wilson
CS396

Last updated: April 16, 2007

Note on the title: Fallout is the title of a popular PC game describing the aftermath of catastrophic nuclear war. The scenario explored in this project resembles that of the food crisis these people would face in such an event, in that it would initially would be a free-for-all to get the most desirable items, and afterward become a mostly-controlled bargaining environment. The name may be a little morbid than say, "ResourceBots", but it's quite a bit more catchy. I strongly believe that half of the effort in developing a research project should be devoted to coming up with such a name in order to make a strong impression on anyone who wishes to invest in your endeavor :)

This C++ code, written in Visual Studio 8, is an implementation of the scenario and agents described in my project deliverables. C++ was chosen as I am most comfortable writing code in it. At first, I was going to implement everything with Java and the TeamBots package (available from www.teambots.org), but I realized that the emphasis of my project was not on the resource gathering stage of things, but rather on the auctioning end. None of the existing domains or agents or classes in TeamBots had much to do with this kind of simulation, and only the Forage domain came close to meeting my needs for agent resource gathering. Even Forage was designed for a more complex resource collection scenario than I was envisioning and modifying it to fit my needs would've taken more time than I had available. Essentially, I was spending about twice as much time as I would spend on a "from scratch" solution looking for hacks in the sparse documentation of the TeamBots communication and simulation library in order to get everything to work. I also plan to run many tests of 1,000 or more games, which would not be feasible to do quickly in TeamBots.

For these reasons, I constructed the entire simulation environment and agent code from scratch. One disadvantage of not using TeamBots has been that there is as of yet no graphical display of game progress. Automatic simulation statistics gathering is not as good as it could be. It is recorded in human-readable format to .log files but could be output in something like CSV with an Excel macro to autogenerate figures and such.

The structure of my code as it is executed during a typical test run is as follows. Most limitations on simulation parameters are placed in the code as #defined constants with names in ALL CAPS.

At the beginning of execution, the main function creates a Metagame object and lets it run a trial, recording the results of the trial to a log file. The Metagame class controls the number of agents, their priorities, and the number of resources that will be available during a trial. The results of a Metagame consist of the results of a certain number of Games. 

The Game class is initially responsible for determining agent positions and placing resource piles. Once a Game starts, it is responsible for giving each agent its turn (for fairness, order of turns is determined randomly for each iteration), as well as determining when the resource gathering stage ends and when the auctioning stage ends.

It is within this context that the ResourceGathering and Auctioning classes determine whether particular actions are allowable and update the game world accordingly. Each particular type of agent is derived from a base Agent class and has a strategy during both stages of a game (respectively, gather() and auction()). The simulation environment's fully observable nature is represented by the agents having access to a global vector of all agents' resources and positions. Agent communication in auctioning is achieved through a globally accessible message buffer in the Auctioning data structure that is passed to all agents during their turn. A turn is the fundamental unit of time for an agent and allows them to either move one unit, collect one unit of resource, or examine messages, place bids and/or list auctions. A message consists of a type (starting an auction, inquiring on the current highest bid, placing a bid, or announcing a winner), content, a source, and a destination (or -1 for broadcast).

TODO: indicates things that I have left to do in the code, HACK: indicates a quick hack I used to solve a problem.

The code can definitely use some major touch-ups as far as style goes. Most of the statistical elements are bolted-on rather than well-integrated into the stat() feature of each major class as was initially planned. Several other elements are probably very inefficient time- and space-wise and could be fixed. The use of some design patterns and generics would probably be appropriate for some of the metalevel classes, enums, and namespaces. There's also a strange bug, where, when running several trials over a large number of games, the program will suddenly crash! It has to be due to some vector getting written out of bounds (it happens with all agents), but I doubt this because it works with the vast majority of trials which should exercise all the vector bounds. It could also result from accidentally using too much memory...

In any case, I figure you pay for what you get, and in this case, you didn't pay much :). Please drop me an e-mail at ari.wilson@gmail.com if you decide to use this code for anything. The code is licensed under the BSD license contained in license.txt.