CST 3170 Home Page
Middlesex Logo

CST 3170 Course Work 3

Pandemic Chatbot and Agents

Due Date: Week 24 (Thursday, March 30, 2023)

40% of Overall Course Mark

Pandemic is a cooperative boardgame. Here is the Pandemic Wiki. Two or more players play on a map of the world. The players can move about the board on their turn performing particular actions, like move, remove disease cube, and cure disease. There are two decks of cards, a player deck, and an infection deck. Players collect cards from the player deck, and use these to cure diseases and for other actions. The infection deck is used to add disease cubes to the board. The goal of the game is to solve all four diseases.

Your task is to build a system that allows a user to play the game. A simple version of the system will support many aspects of the game, allow the user to, in essence, play both players. As the game depends on cards, the luck of the draw matters. Depending on the luck of the draw and how the user plays, the user (or the team) should be able to win or lose.

The conversation: the user should interact with the game via a conversation. For the simple version, this can be a series of commands. As the complexity of the system increases, a conversation between the agent and the user can become quite sophisticated. The two can develop a plan via the conversation.

The agent: in the simple version of the system, the user, in essence, plays both players. A more complex version of the system supports a sophisticated agent that can help the user plan. This could use a game tree, remember the cards that have already been played, and use planning.

Marking scheme:
10Game Plays
10Team can win or lose
10Code Style

The Game

There are several version of the pandemic game, and we will work with the first version. The system does not have to implement the complete game, but the more that is added the better. Only aspects of the base game should be added. The module leader is happy to explain aspects of the game, and indeed discuss algorithms and data structures that might be used. Moreover, you are welcome to discuss these things with your colleagues, but it is important that all code is user own. Below there is an incomplete description of the game.

There are two or more players that may have extra skills. The players start in Atlanta (where the CDC is) and move about the board. There are 48 cities, 12 of each of the four colours (blue, yellow, red and black). There are two decks of cards: the player deck and the infection deck. At the end of their turn, the player draws cards. When a card from the infection deck is drawn, a cube of that colour is added to the city.

There are two or more players. Typically, the systems will use two players, but an advanced system may have more. Players alternate turns. On their turn a player performs their actions, draws player cards, then draws they may take up to four actions. In simple systems, all players can take up to four actions in their turn, and all are in essence equally powerful. In more advanced systems, there can be different types of players called roles (only one of each type on the team). For example, the Generalist can take five moves, and the Scientist can cure a disease with only four cards. Feel free to implement any of the roles from any of the games. (I like the pilot.)

There are 48 cities 12 of each colour. Colour are associated with diseases, so a blue city like Atlanta is associated with the blue disease. There is a city graph with nearby cities connected to each other. When the user uses the move action, they can only move to a connected city. When there is an outbreak (see below), it only spreads to connected cities.

Disease cubes: at the end of a players turn they draw cards from the infection deck. The disease deck is a deck of 48 cards, one for each city. (Typically players draw two cards, but as you draw epidemic cards you may increase the number players draw.) A disease cube of that colour is placed on the city drawn. Players can take use an action to remove a disease cube from the city they are in. If the disease has been cured, the player can remove all the cubes with one action. To start the game, the players draw nine infection cards. The city from the first three cards gets three infection cubes, the second three get two, and the last three one. These cards are placed in the infection discard pile.

There are 9 types of action a player can take: move, remove disease cube, give card, take card, fly to city, fly from city, fly from research station to research station, cure disease, and build research centre. A player can move to any connected city, and they can remove a disease cube from the city they are in. If the player is in same city as another player, they can give the other player a card or take a card from that player. They can fly to another city if they turn in that city card from their hand, or they can fly to any city by playing the card of the city they are in. If they are in a city with a research station, they can fly to another city that has a research station. A player can cure a disease if they are at a research city and turn in five cards of the same colour for that disease. A player can build a research station in the city they are in by turning in a card for the city they are in.

Again, a disease is cured by a player turning in five player cards of the diseases colour in a research station. A bonus is that if there are no cubes of that colour on the board, the disease is solved. When an infection card of that colour is drawn, no cubes are added.

Player cards are important, but a player can only have 7 cards in their hand at any time. If their turn ends and they have more than 7 cards in their hand, they have to throw enough away to go to 7.

What really makes the game difficult is epidemics. When the game begins, the player deck of 48 cards (one for each city but you can also have magic cards see below) is shuffled and cards are dealt to each player. (For two players each player gets four cards.) The remaining cards are split into four piles. An epidemic card is added to each pile and they are shuffled and the four piles stacked to form the player deck. At the end of each turn, the player draws two new cards. (Playing a magic card or discarding a card to reach their hand limit.) When the player deck is empty, the team looses. If an epidemic card is drawn, the bottom card from the infection deck is selected, and its city is given three cubes. It is then placed in the infection discard pile, which is shuffled and added to the top of the infection deck. When the player then infects, those cards from the top are drawn. If a city with three cubes of the same colour is drawn, there is an outbreak.

Another difficulty that can be included is outbreaks. When there is an outbreak, all of the cities connected to the outbreaking city are given an extra cube. This can lead to a further outbreak, though no city outbreaks twice on a given turn. If there are eight outbreaks in total, the team loses. Note that a city never has more than three cubes of a colour, but it may have cubes of different colours.

When the game starts, there is one research centre, in Atlanta. Players can take an action (turning in a card) to make a new research centre. Diseases can be cured only in a research centre, and players can fly from one research centre to another for an action. There are only 6 research centres.

Magic cards: special cards can be added to the player deck and drawn into players hands. There are a range of them, and you can feel free to put any from the game, or for that matter make up your own into the game. Example cards are fly anywhere, build a research station anywhere, solve a disease with one less cube, and send a card to another player. Once you play a card, it goes into the player discard pile. Adding more magic cards makes it easier form the team to win. Also note that these cards extend the game as they make the deck larger.

The players win the game if the cure all four diseases. They can lose by running out player cards, or by having an eighth outbreak.

Marking scheme

The marking scheme above goes from simplest to most complex. The game should play. The user (team) should be able to win and lose. Code should be written well, with good comments, good variable names, named constants, and reasonably sized functions.

You should write a brief (1-4 page) report on your system. It should say how to run the program and describe any interesting algorithms or data structures. A simple sysem will have few game aspects and an agent that just helps the user understand the options of the game. The report can be quite brief and will necessarily get a low (but passing ) mark. A more sophisticated system might keep track of the cards and say, when asked, how likely a particular card or type of card is to appear. A more sophisticated sytstem might use a probabilistic game tree, and probabilistic planning to suggest future moves. These aspects could be described in the report to gain a better mark.

The example conversation (from the provided code) is extremely simple and is just a simple one input to one ouput mapping. A more robust conversation, with sentences and variance, is one way to progress. Feel free to make it fun asking the user's name and creating banter. Part of the robustness of the system is the robustness of the conversation. For reasonable conversation marks, the user should be able to play the game just by chatting. A simple conversational extension might explain the game to the user. That would be more than just a text file dump. However, to get above 20 points, you'll need a proper conversation about what to do in the future. This will probably be supported by an agent that does some degree of planning, or at least can keep track of the decks and talk about them. You can provide a GUI, but command line text interface is fine. What's important is the conversation.

In the simplest game, the user, in essence, plays both players. To give the system a degree of complexity, the user and the agent need to agree on a plan. The agent can then make his actions on his own, though he could get agreement with the user; it is after all a collaborative game. The agent could gain complexity by having a planning system with goals. It could use a probabilistic game tree to help with the planning. Other mechanisms are also plausible. Indeed, an extraordinary coursework might take advantage of the game to learn weightings for decisions so that it could perform better.

Code should be written in Java, should run in the lab from eclipse, and you should write it yourself (except possibly the code I provide below). If you use an existing algorithm, you should reference that algorithm in your code and in your report. The code should be written in Java, and should run in the lab from eclipse. A city connectivity file is here and my simple version of pandemic is here. You are welcome to use this pandemic code, but put describe what you use in the report. It's not enough to pass. You should use the map file or your own variant.

The minimally passing system: it should be easy to get the game playing (10 points). Getting the system to include losing and winning is a bit more complex, and requires the player deck and curing diseases (10 points). Use Standard good coding practice from the beginning (6 points). A reasonable report can be brief on this (8 points). You'll need to get 6 points for the conversation to get 40; this would explain all the moves and the state of the game. (In this case the agent is really just the user playing both players so it get's 0/25).

Please submit the code, and report to the coursework 3 folder of CST 3170 on myunihub. You are also welcome to email a copy to the tutor.