Quick start guide

Learn the basics to develop your own software player (bot) with dipGame and run Diplomacy games against it.

Contents

  1. Introduction
  2. Play your first game
  3. Create your first bot
  4. Play against your bot
  5. Add negotiation capabilities to your bot
  6. Template for a negotiating bot

1. Introduction

Diplomacy is a game played by seven players. In dipGame we want to create software players of this game and make them compete along them and against human players. DAIDE was a pioneer doing it. We continue their work and we made it more suitable for scientific researchers of areas like Multiagent Systems.

In the following we assume that you know the rules of the game and refer to spring movements as SPR, spring retreates as SUM, fall movements as FAL, fall retreates as AUT and adjustments as WIN. The available orders in each phase are (for movements:) to hold, move, support hold, support move, (for retreates:) retreat, disband, (for adjustments:) build, remove and waive. Convoys are not allowed in dipGame.

2. Play your first game

Every user can play Diplomacy on-line using our website (click on New Game ).

If you pretend to create your own bot, you should learn how to play off-line, on your own computer. To do so: download the Game Manager , install it and run a game involving 6 bots and a human player.

3. Create your first bot

The complexity of creating a bot varies a lot depending on your requirements. The simplest bot ever just holds its position, disbands and removes units or waives depending on the phase of the game. We call this bot HoldBot.

To implement HoldBot we can extend the es.csic.iiia.fabregues.dip.Player class from the dip framework and implement its method play() . Other method headers must be also in our HoldBot class (like receivedOrder(Order arg0) ) but it is not necessary to include any sentence into them. The method play() for HoldBot should look like the following:

@Override
 public  List<Order> play() {
  List<Order> orders = new  Vector<Order>();
  switch  (game.getPhase()) {
  case  SPR:
  case  FAL:
   //Holding all controlled units
   for (Region unit: me.getControlledRegions()){
    HLDOrder hldOrder = new  HLDOrder(me, unit);
    orders.add(hldOrder);
   }
   break ;
  case  SUM:
   case  AUT:
      //Disbanding all dislodged units
      for (Region dislodgedUnit: game.getDislodgedRegions(me)){
        DSBOrder dsbOrder = new  DSBOrder(dislodgedUnit, me);
        orders.add(dsbOrder);
      }
      break ;
    default :
      //That's WIN
      int  nBuilds = me.getOwnedSCs().size()-me.getControlledRegions().size();
      if (nBuilds > 0){
        //Waiving nBuilds times
        for (int  i=0; i<nBuilds; i++){
          WVEOrder wveOrder = new  WVEOrder(me);
          orders.add(wveOrder);
        }
      }else if (nBuilds < 0){
        //Removing nBuilds units
        int  nRemovals = -nBuilds;
        for (int  i=0; i<nRemovals; i++){
          Region remUnit = me.getControlledRegions().get(i);
          REMOrder remOrder = new  REMOrder(me, remUnit);
          orders.add(remOrder);
        }
      }
      break ;
    }
    return  orders;
  }

The HoldBot as described before is not a program because it has no main method. To complete it and be able to execute your bot you need to define a method like the following one:

public static  void  main(String[] args){
    try  {
      IComm comm = new  DaideComm(InetAddress.getByName("localhost")16713"HoldBot");
      HoldBot holdBot = new  HoldBot();
      holdBot.start(comm);
    catch  (UnknownHostException e) {
      System.err.println("Unknown host name.");
    catch  (CommException e) {
      System.err.println("Cannot connect to the server.");
    }
  }

dip requires three libraries. Thus, your bot requires a total of four libraries to be imported. Copy those libraries into a folder together with the HoldBot.java file. Run a terminal and locate yourself into the same folder. To compile your bot you just need to type the following sentence:

javac -cp .:dip-1.6.jar:tcpIpComm-0.1.2.jar:jac-0.8.1.jar:utilities-1.0.3.jar HoldBot.java

If the compilation works fine no output must apear. Now, your HoldBot is ready to play games.

4. Play against your bot

To play a game against your new HoldBot you can run a game with gameManager setting as empty one of the players. Then, a game will be launched with several players connected to it and you should run your HoldBot connecting to the same server location. If you want to run HoldBot in the same computer that you are running the gameManager, then the game server ip is 'localhost' and the server port is '16713', that are the same values that we specified in the main method. Now you can execute your bot as follows:

java -cp .:dip-1.6.jar:tcpIpComm-0.1.2.jar:jac-0.8.1.jar:utilities-1.0.3.jar HoldBot

You can also add your bot to gameManager as described at the gameManager page . To do so it is recommended to generate an executable jar file containing your code and the required libraries. There are several ways to do so, the easiest using Apache Ant.

5. Add negotiation capabilities to your bot

Adding negotiation capabilities means adding a new level of complexity to the development of your bot. We recommend to exercise first developing bots without negotiation capabilities.

The esiest negotiator bot is the one that talks about peace and alliance without understanding at all what do they mean. This bot proposes randomly peaces and alliances and accepts or rejects them also randomly. This bot is useless as a negotiator but it is probably the best way to exemplify the development of a negotiating bot.

To negotiate in dipGame we use the nego negotiation framework. nego provides the class org.dipgame.negoClient.simple.DipNegoClientImpl for sending messages to other Diplomacy players and the class org.dipgame.negoClient.simple.DipNegoClientHandler to indicate what to do whenever the bot receives a message.

In the following example we create a new class RandomNegotiator implementing the org.dipgame.negoClient.Negotiator interface that creates and runs the negotiation. Then, we create a new bot extending HoldBot and adding the capability of negotiating with the previous random negotiator:

import java.net.InetAddress;
import java.util.List;

import org.dipgame.examples.negotiator.Negotiator;
import org.dipgame.examples.negotiator.RandomNegotiator;

import es.csic.iiia.fabregues.dip.orders.Order;


public class RandomNegotiatorHoldBot extends HoldBot{
  private int negotiationPort;
  private InetAddress negotiationServer;
  private Negotiator negotiator;
  
  public RandomNegotiatorHoldBot(InetAddress negotiationIp, int negotiationPort){
    super();
    this.negotiationServer = negotiationIp;
    this.negotiationPort = negotiationPort;
  }

  @Override
  public void init() {}
  
  @Override
  public void start() {
    super.start();
    negotiator = new RandomNegotiator(negotiationServer, negotiationPort, this);
    negotiator.init();
  }

  @Override
  /**
   * Negotiates before sending orders
   */
  public List<Order> play() {
    negotiator.negotiate();
    return super.play();
  }
}

RandomNegotiator negotiates only about peace and alliance but the negotiation can include movements and other sort or offers.

6. Template for a negotiating bot

As a start point for developing a negotiating bot we recommed you to use the following template of an Eclipse project.

This template is useful also if you don't use Eclipse as its readme.txt file explains how to compile and execute it in both cases. It also explains how to generate an executable jar file from the code.