Out: Sunday, 13 February
Preliminary Deadline: Thursday, 10 March, 11:59pm
Final Deadline: Thursday, 17 March, 11:59pm

Your assignment for this project is to build a bot that plays West Virginia Hold ‘Em, a simple variant of Texas Hold’Em where there is a single post-flop betting round. To qualify, your bot must be able to beat the benchmark player we have provided. There will be a maximum bankroll tournament run between all the qualifying bots. (Full details on the tournament mechanics will be posted later.)

Teams

Each team will be two or three people. You may either form a team yourself or be assigned a team in class on Tuesday, February 15. If you wish to form a team yourself, you and your teammates should send me a single email, cc:ing everyone on your team, and stating that you want to work as a team.

Getting Started with the ACPC Server

This assumes you are running Linux. The examples were tested on power2.cs.virginia.edu, running Ubuntu, but should work on any reasonably recent Linux distribution. The provided code is written in C (but you can write your bot in any language you want, so long as you can produce a Linux executable).

Download: ACPC 2011 Server Code.

To build the server:

> bunzip project_acpc_server.tar.bz2
> tar xf project_acpc_server.tar
> cd project_acpc_server
> make
gcc -O3 -Wall -o dealer game.c rng.c dealer.c
gcc -O3 -Wall -o example_player game.c rng.c example_player.c

Now, you should be able to run a game using the provided example_player (which just makes random raises with probability 1/2):

> perl play_match.pl foo holdem.limit.2p.reverse_blinds.game \
           1000 6501 Alice ./example_player.limit.2p.sh \
                          Bob ./example_player.limit.2p.sh
SCORE:-5440|5440:Alice|Bob

The Perl script play_match.pl takes as parameters the name of the game, game description file, number of hands to play, random number seed, name of player 1, script to start player 1, name of player 2, script to start player 2 (and so on if there are more than 2 players). It starts the dealer, a server that executes the game, and starts the players as separate processes that connect to the dealer (using a port specified when the dealer is started). The dealer with then execute the game protocol, sending players update messages with the current state, and processing their responses. The player scripts (e.g., example_player.limit.2p.sh) just execute the player passing in the game description file and server port.

When the game runs, several log files are generated using the name of the game parameter: foo.err (output from stderr stream, a detailed script of the full game and any error messages), foo.log (a log of all the game states), foo.playerno.err (error log for player) and foo.playerno.std (output log for player). The player logs should all be empty for this execution, but you will find these helpful when you are debugging your own player.

West Virginia Hold ‘Em

For this project, you will build a bot to play a simple poker variant we’ll call West Virginia Hold ‘Em (or Mountaineer if you prefer!). This is a two-player game with two rounds of betting. The definition of the game is:

GAMEDEF
limit
numPlayers = 2
numRounds = 2
blind = 10 5
raiseSize = 10 20
firstPlayer = 2 1
maxRaises = 2 2
numSuits = 4
numRanks = 13
numHoleCards = 2
numBoardCards = 0 5
END GAMEDEF

Initially, each player gets two hole cards. There is a round of betting, with the bet size fixed at 10. Player 1 is forced to make a big blind bet (10), and player 2 is forced to make a small blind bet (5). Then, Player 2 has the option to either fold, call (by contributing 5 more to the pot), or raise 10 (betting 15 total). If Player 2 raises, Player 1 can fold, call (paying 10), or raise (betting 20 total). After this, player 2 can either fold or call (no more raising allowed).

Then, the dealer deals five community cards. (Unlike Texas Hold’Em there are no betting rounds after the 3rd and 4th community cards are dealt.) For this round, Player 1 acts first and can either check or bet 20. If Player 1 checks, Player 2 can either check (ending the hand) or bet 20; if player 1 bets, player 2 can either fold, call, or raise 20. If Player 2 bets or raises, then Player 1 has the option to fold, call, or raise 20. If Player 1 raises, player 2 has the option to fold or call.

If the hand ends in a showdown (neither player folds), the player who can make the best 5-card hand from her hold card and the 5 community cards wins the hand. If the players are tied, the pot is split evenly between them. (Hands are ranked according to the normal poker rules. See Wikipedia’s page if you are not familiar with the hand rankings.)

Download: wvholdem.zip. This zipfile contains:

  • benchmark_player — Linux executable for the benchmark player. You should view this as a “black box”, and not attempt to reverse engineer it by analyzing the binary, but only by observing its outputs.
  • benchmark_player.wvlimit.2p.sh — a script for starting the player
  • wvholdem.limit.2p.game — a description of the game (as shown above)

Deliverables

Submissions. Each team should send its submission as a single zip file attached to an email message to evans@virginia.edu that is received before 11:59pm on Thursday, March 17.

Your zip file should contain:

  • A directory containing all the source code needed to build your bot, including a Makefile that builds it using make on a Linux machine (e.g., power2.cs.virginia.edu).
  • A Linux executable named team_player that is your bot executable (team is a name of your choosing).
  • A PDF document that describes your bot. It should explain your design and testing strategy, and include interesting insights from your experience. This document should also clearly describe the sources of any code that you did not write yourselves (or obtain from the provided code).

I will test the submitted bots against the benchmark player, and then run the bot-versus-bot tournament among the qualifying bots.

Presentations. Each team should be prepared to make a short presentation in class on Tuesday, 15 March.

Suggestions

You can use any strategy you want to build your bot. I encourage you to use more general machine learning strategies, however, rather than spending a lot of hand-tweaking effort to craft your bot.

There are many libraries available with implementations of standard machine learning algorithms. The two I think will be most useful are:

but depending on your strategy and programming language of choice you may find others more useful, and are free to use anything you want (so long as you follow the distribution license for the code provider).

The benchmark player is provided to give you an initial player to train against, and a target for qualification. It is unlikely, however, that a bot that only trains against this player will do well against the other submitted bots. So, I would encourage you to develop alternative testing strategies once you have gotten to the level of a bot that can consistently beat the benchmark player.

Although there is a competitive tournament among the submitted bots, it will be very beneficial for teams to cooperate. You are encouraged to share generally useful code with other teams, and may even find it useful to share test bots with other teams. You are free to collaborate across teams in any way you want, so long as the final submission clearly documents everything you used and credits the sources for any code that you did not write.