This directory should contain sources for Zoo referees.

Contents:
1.  Introduction
2.  Stock referees
2.1  Default referee
2.2  myref
2.3  transref
3.  Creating your own referee
3.1.  Writing the code
3.2.  Installation

---

1.  Introduction

Zoo is a Player plugin intended to be used alongside Stage.  It provides an
interface for researchers to set up experiments involving several robots
(models) and controllers, usually oriented around the performance of some
task.  The Zoo is divided into several components: the driver, a set of
species, and a referee.

The Zoo driver (zoo_driver.cc) is the driver loaded by Player; it requires
Stage to be loaded as well.  The driver keeps track of the set of species,
the set of robots (or top-level models), and the controllers as they are
actually running.  Zoo has the capability to stop controllers and to start
them, connecting them to robots on specific ports.  Zoo also loads and
starts the referee.

Robots in the Zoo are partitioned into species.  A species is a "population"
of robots (given as a set of top-level model names), along with a set of
controllers that are to be connected to these robots.  There is no preset
relationship between which controller is connected to which robot in a given
species; it is up to the referee to determine this (by default, controllers
are chosen on a prioritized round-robin scheme).

The referee is that part of the Zoo responsible for understanding the task
at hand, and for overseeing activity in the world according to the rules of
that task.  That is, it may direct the driver to start or stop a controller,
and it may keep track of some kind of score for each controller.  It may
also modify any other libstage-accessible feature of the world as
appropriate to the task at hand.

The purpose of the Zoo is to provide a level testing ground for robot
controllers.  Thus an "exhibit" is a specific set of goals that robots as a
group must perform.  Goodness of performance is judged by the referee.  A
"species" is a set of robots that have the same role within the exhibit;
their goal can be thought of as a distinct task.  For example, in an exhibit
where the goal is transport widgets from A to B, there is one task, and
thus, probably just one species.  However, there may be many competing
controllers, which the referee will assign to robots as it sees fit.  On the
other hand, consider an exhibit where some robots must gather widgets, and
some others must chase the gatherers; here we have two distinct species, and
while a variety of controllers might compete at the gathering task, they
will be kept separate (in a separate species) from those attemping to
disrupt operations.

---

2.  Stock referees

Three referees are currently distributed with Zoo.

2.1.  The default referee takes no actions other than connecting some
controller to every model known to Zoo (that is, every model in the
population of some species).  Controller selection is prioritized
round-robin.

2.2.  myref is a dummy referee derived from the default.  Its only extra
feature is that it reads an item from the configuration file and
regurgitates it.

2.3.  transref is a referee for a transportation task.  Robots must seek out
"source" sites which hand out pucks.  Then they must deliver pucks to "sink
sites.  A robot can carry at most one puck at a time.  Every puck delivered
to a sink awards the delivering robot a point.  There are several sources
and sinks, as well as dummy sites which neither give out nor accept pucks.

Pucks are an abstract concept associated with no model in Stage; they are
known only to the referee.

---

3.  Creating your own referee

3.1. Writing the code

The only requirement is that your program provides the following function:

	ZooReferee *zooref_create( ConfigFile *, int, ZooDriver * )

This function should, obviously, create a new ZooReferee object and return a
pointer to it.  Probably you will want to subclass ZooReferee and override
some of its functions.

The third parameter to zooref_create will be a pointer to the ZooDriver that
loads the referee.  A variety of useful functions exists to aid the referee.
For more information on these functions, as well as the default referee's
interface, please see the Stage documentation under Zoo.

---

3.2.  Installation

To configure: if you write a referee called "fooref", then update
Makefile.am as follows:
1) Add "libfooref.so" to lib_LTLIBRARIES.
2) Add a line "libfooref_so_SOURCES = A B C ...", where "A B C ..." are the
list of source files needed to build your referee.

Then rerun "bootstrap" and "configure" in the top level directory of the
Stage source tree.

To load: the config file section that loads Zoo should also contain a line

	referee "libfooref.so"

Alternatively, "libfooref", "fooref.so", and simply "fooref" should all
succeed.

Any other options that your referee will need to know about could also go
into that section, but you are under no obligation to put them there.
