## Changing the game

### Using predefined games

Three predefined games exist: the Prisoner's Dilemma, the Stag Hunt, and Divide-The-Cake.  One switches between these games using SetGame().

#### The prisoner's dilemma

The default prisoner's dilemma uses the following payoff matrix:

 Cooperate Defect Cooperate (2, 2) (0,3) Defect (3, 0) (1, 1)

If you are happy with this payoff matrix, you can switch to this game by entering
`SetGame( PrisonersDilemma );`
If the default payoff matrix won't do, you need to create a new form of the prisoner's dilemma.  You do this by requesting a new prisoner's dilemma with certain values for the temptation (T), reward (R), punishment (P), and sucker (S) payoffs.
So, if you want a prisoner's dilemma with T=1.0, R=0.9, P=0.2, and S=0.0 you get this by entering
`SetGame( new PrisonersDilemma(1.0, 0.9, 0.2, 0.0) );`
Alternatively, you could create this new game in stages:
`g = new PrisonersDilemma(1.0, 0.9, 0.2, 0.0);SetGame(g);`
The standard prisoner's dilemma requires that T+P/2<R (so that mutual alternation of defect and cooperate is not more beneficial and joint cooperation) and that T>R>P>S (so that defection strongly dominates cooperation).  However, no checking is performed to insure that the passed parameters satisfy these constraints.  Notice, though, that the order of the arguments to the constructor is T, R, P, andS, which helps you keep at least one of the two requirements satisfied.

#### The stag hunt

The default stag hunt uses the following payoff matrix:

 Hunt Stag Hunt Rabbit Hunt Stag (7.5, 7.5) (4.0, 7.0) Hunt Rabbit (7.0, 4.0) (5.0, 5.0)

You switch to this game using similar syntax to the above:
`SetGame( StagHunt );`
As for the prisoner's dilemma, you can create a new form of the stag hunt if you do not like the above payoff matrix.  You need to specify the payoffs for Stag-Stag (SS), Stag-Rabbit (SR), Rabbit-Stag (RS), and Rabbit-Rabbit (RR) as follows:
`SetGame( new StagHunt( SS, SR, RS, RR ) );`
This will create a stag hunt with the payoff matrix

 Hunt Stag Hunt Rabbit Hunt Stag (SS, SS) (SR, RS) Hunt Rabbit (RS, SR) (RR, RR)

As above, you can also create this game in stages:
`g = new StagHunt( SS, SR, RS, RR);SetGame(g);`

#### Divide-the-Cake

To change the game to Divide-the-Cake with the default cake size of 10:
`SetGame( DivideTheCake );`
Versions of Divide-the-Cake for any cake size C can be created by
`SetGame( new DivideTheCake(C) );`
or by
`g = new DivideTheCake(C);SetGame(g);`

### Defining a custom game

Creating a custom game is a two (or three, or four) step process:

#### Creating a new game

Creating a new game to modify is straightforward: you just have to tell it the number of strategies you want.  So, for a three-strategy game the command
`g = new Game(3);`
sets the variable g to be a no-frills, three-strategy game in which all of the payoffs are zero, the strategies are labelled "Strategy 0", "Strategy 1", and "Strategy 2", and the color map (which is what is used to indicate the strategies when drawn on-screen) involves various shades of gray.  Each of these can be changed.

#### Specifying a payoff matrix for the game

Let's change the payoffs of g to be those of rock-paper-scissors, where 0 = lose, 1 = draw, and 2 = win.  Let's make strategy 0 be "rock", strategy 1 be "paper", and strategy 2 be "scissors".  The payoff matrix, then, is

 Strategy 0 Strategy 1 Strategy 2 Strategy 0 (1,1) (0,2) (2,0) Strategy 1 (2,0) (1,1) (0,2) Strategy 2 (0,2) (2,0) (1,1)

Rock-paper-scissors

There are two ways you can change the payoff matrix: all at once, or by changing one payoff at a time.  The all-at-once method is easiest for small games like this when writing out the full payoff matrix doesn't take long.  Changing payoffs one at a time is easiest for large games consisting of many strategies where changing the payoff can be embedded in a loop.
##### Changing the payoff matrix all at once.
The game stored in the variable g has a couple functions (or "methods") that you use to change values.  If you're familiar with object-oriented programming, this syntax will be familar.  If not, keep the following in mind and you'll be OK: if myObject is an object (like a game), then the command myObject.someFunction() calls the function someFunction() that "belongs to" the object.  In most cases, this changes something about myObject (in this case, we'll be changing the payoff matrix belong to the game g).  Contrast this with the effect of calling functions like SetGame( DivideTheCake ), which changes a global property of the model or program.

Changing the payoff matrix all at once is done by passing a two-dimensional matrix, or array, containing the payoffs to the function setPayoffMatrix() that belongs to g. One way to do this is:
`payoffs = new double[][] {{1.0, 0.0, 2.0},                          {2.0, 1.0, 0.0},                          {0.0, 2.0, 1.0}};g.setPayoffMatrix( payoffs );`
Alternatively, you can combine the two lines into one:
`g.setPayoffMatrix( new double[][] {{1.0,0.0,2.0}, {2.0,1.0,0.0}, {0.0,2.0,1.0}} );`
Since all of the payoffs are integers, you can omit the decimal point and trailing digit:
`g.setPayoffMatrix( new double[][] {{1,0,2}, {2,1,0}, {0,2,1}} );`
##### Changing one payoff at a time.
Changing one payoff at a time is done by calling setPayoff( row, column, payoff ).
`g.setPayoff(0, 0, 1.0);g.setPayoff(0, 1, 0.0);g.setPayoff(0, 2, 2.0);g.setPayoff(1, 0, 2.0);g.setPayoff(1, 1, 1.0);g.setPayoff(1, 2, 0.0);g.setPayoff(2, 0, 0.0);g.setPayoff(2, 1, 2.0);g.setPayoff(2, 2, 1.0);`

#### Changing the names of the strategies

Changing the names of the strategies proceeds along the same lines as changing the payoff matrix, except that you only need to specify a one-dimensional array of names.  The first element of the array renames the first strategy ("Strategy 0"), the second element renames the second strategy ("Strategy 1"), and so on.
`g.setLabels( new String[] {"Rock", "Paper", "Scissors"} );`

#### Changing the color map

Changing which colors are used to draw strategies on screen is purely a matter of taste.  However, picking bright, distinctive, and highly contrasting colors can make evolutionary behavior of your model much easier to see.  It can also make your screen look like an angry fruit salad, though, so be mindful of what colors you choose.

Let's use the following color code: Rock = red, Paper = green, and Scissors = blue.  One way of setting up this color map is the following:
`colors = new Color[3];colors[0] = Color.red;colors[1] = Color.green;colors[2] = Color.blue;g.setColorMap( colors );`
another way is:
`g.setColorMap( new Color[] {Color.red, Color.green, Color.blue } );`
and a third way is:
`g.setColor(0, Color.red);g.setColor(1, Color.green);g.setColor(2, Color.blue);`

### Setting the custom game

At this point, g contains a full definition of Rock-Paper-Scissors.  You can make it the current game by entering
`SetGame(g);`
The custom colors and custom labels will be used when displaying the legend and payoff matrix, as shown below (click to enlarge).

### Saving the game

If the game you've just defined is one you will use often, you can save it to a text file and read it into the shell using the source() command.  A copy of one file for Rock-Paper-Scissors is available for download.  If you install this in the same directory as the model, you can load it by entering
`source("rps.bsh");`
(or whatever you named the file instead of "rps.bsh").  The above file creates a new game named RockPaperScissors, allowing you to change to that game by simply entering
`SetGame( RockPaperScissors );`
as if it were one of the predefined games.