Poker Server

This project is a server designed to run a friendly game of Texas Holdem Poker. This is the server only, not the front-end or User Interface. The server exposes a REST API for client side functionality.

What This Project Is

This is a server program designed to facilitate a home game of Texas Holdem Poker. Some features:

• Dealing every hand and performing a proper random suffle of the deck
• Tracking the dealer button, small blind, and big blind
• Tracking chip stacks for every player
• Tracking each player's hole cards as well as the community cards
• Tracking which player is currently supposed to act as well as what actions are legal for that player
• Handling the evaluation of the poker hands, determining who wins and loses, handling split pots, and handling side pots when there are multiple all in players
• Handling the blind structure and timers
• Exposing all of this functionality in a REST service.

This software is for use with friendly games of poker, for home games where everyone is in the same room. This was my thought when I designed it, and my thinking when I wrote it.

What This Project Is Not

• This is not professional online poker software
• This is not designed to be used in highly competative situations with large amounts of money at risk
• There is no guarantee of security, and I'm not promising anything. I doubt I can stress this enough
• This is not an infrustructre project. This is just the java server. To use it, you can set it up however you like, with apache/tomcat or jboss or whatever, but it does not come pre-configured.
• This is not designed to replace the normal interaction between players in a poker game, it is designed to augment it.
• This is not a UI. Some simple front-end projects that consume the service this project provides are available on my github page (http://github.com/jacobhyphenated).

Some Background

I created this project for a couple of reasons. For one thing, it sounded fun, and was a good way to keep my Java/Spring skillset up to date and sharp. But also, I felt that it might be a cool and useful tool for running poker games.

Generally when I play a friendly home game of poker, there are a couple of things that can have negative impacts on the experience of the game. Sometimes people are new to the game, and the inexperience can slow down the pace of play. Sometimes people are not paying close attention, so they act out of turn, or take too much time to act. Sometimes people make mistakes, flip their cards up, or misdeal and the hand has to start over. Lastly, dealing takes a lot of time, and not everyone is very good at shuffling.

None of these issues are a big deal. It's a friendly game; no need to be stressed out about the little things. But a program like this might go a long way to making the game run more smoothly by eliminating some of these mistakes and streamlining the gameplay.

I also invision this as a good learning tool. It is easier to learn the game without being distracted by chipstacks, dealing, maintaining the blinds, moving the dealer button, and remembering whose turn it is.

A lot of these ideas were floating around in my mind when I started development on this project, so this is the background info that influenced a lot of my design and architecture decisions.

Technical Things

This is a java server project using Java 1.6 with Spring(3.2) for IOC and Hibernate(4.1) for ORM and Maven for dependency management/deployment. I used Spring for unit tests as well.

The database is MySQL.

The API was build using Spring MVC and Jackson for JSON marshalling.

Spring Cache Abstraction is used to cache the Player Status API calls (as this will be by far the most commonly called API function). The caching is invalidated on any method that changes the game state (player actions, dealing cards, new hand, etc). The current implementation uses spring's ConcurrentMapCacheFactoryBean, but the caching strategy will scale if using a properly configured ehcache setup.

The algorithm used for Texas Holdem hand evaluation uses a precomputed table of values. This is very memory intensive and will overflow some of the default java heap space allocations, specifically eclipse servers and JUnit testing. I find that adding the VM Arguments: -Xms512m -Xmx1524m was more than sufficient to solve the problem.

Setup and Installation

Spinning up this server will largely depend on what your setup is. I had originally intended to include a war file in the repository, but it was too big and made pull/push times impractical. To get a working war file, you will have to set up and build the project.

Setting up the development will depend on your IDE and various plugins. I used eclipse, so my instructions will be mostly centered around that.

This project was built on Maven, so you will need maven properly installed to pull the libraries and build the war file.

1. Clone the repository

• If you have a git eclipse plugin, use that to clone the repository and import the project into eclipse
• If you do not have a plugin, clone the repository then import the project as an existing project

2. Run maven. Use maven build or maven install or an eclipse plugin. This will pull all the jar files needed for the project.

• Set up the database. I used mysql and you will have to make some configuration changes if you are wanting to use a different database.
• There is a mysql dump of the database structure in the scripts folder
• The file hibernate-context.xml in the WEB-INF/spring/ folder contains the configuration for the database (username,password,etc).
• Deploy the eclipse project to an eclipse server
• If you don't have an eclipse server set up, just create a new server (ex. Tomcat V7.0) and deploy the project to that.
• Change the server vm args (Overview --> open launch configurations --> arguments --> VM arguments), adding -Xms512m -Xmx1524m
• Publish and start the server.
• There you go, should be working.

I get that this might be a bit much, and I have obviously not spent a lot of time on the configuraion side of things, so I welcome pull requests that make the initial set up easier.

Outstanding issues, Quality, Polish

This is still a work in progress. What is currently here on github should work successfully with no major bugs, but there are some known issues that need to be worked on, or issues that have simple work-arounds and do not detract too much from the overall process.

The issues that I know about I have added to the Issues Tab. You can probably find a few //TODO messages throughout my code pointing out things that need additional work as well.

Because this is still a work in progress, I will likely be making periodic changes. The plan is to make sure any functionality change is backward compatible with the API, but I cannot guarantee that will happen with 100% certainty. However, I do plan on tagging all major releases of functionality, so it should be easy to switch back to a working version if new changes create new issues.

API

The API consists of two components. The game component, and the player compomant. The way I envision it, there will be a device (say for example, an iPad) that sits in the center of the table and displays the blind time, the community cards, and other game information, that is the Game Controller. Each player will have their own device, and will use the player section of the API.

Requests to the server are made using http request parameters. The response is properly formatted JSON.

Current Version: 0.5

New in Version 0.5: The Player Status API call now returns the small and big blind, giving the player client easier access to the blind information. Version 0.5 is completely backwards compatible with Version 0.4.

New in Version 0.4: Sitting out of the game, and sitting back in. There are new API calls that allow the game controller to "sit out" an idle player. This player will be skipped in the game action order. In a tournament, the player will still post blinds, but will fold to any bet or raise. A second API call is added to the player controller, allowing that player to sit back in.

Version 0.4 is backwards compatible with 0.1 as only new API calls were added, and no other API calls changed. The exception is Player Status. There is now a new status called SIT_OUT_GAME that represents a player who has been sat out. If a client targeting an earlier version of the API cannot handle the new status, then it will not be able to use a Server running 0.4.

New in Version 0.3: UUID identifiers for player ID. The playerId API parameter is now a longer more unique string, making the id next to impossible to guess.

Version 0.3 is backward compatible through 0.1. The catch is that the playerId is now a guaranteed String type, so any implementation that used an integer for playerId may no longer work. The type was never specified as an integer in the previous API specifications, but an integer would have worked in previous versions; only String will work moving forward.

New in Version 0.2: JSONP. Simply add a parameter named callback to the query, with the value of the javascript function.

http://your-url.com/ping?callback=test Results in test({"success":true"});

Version 0.2 is completely backwards compatible with Version 0.1. All that was added was JSONP support.

Game Controller

List Structure (/structures)

Get a list of currently available structures for the poker game. These game structures represent the blind structure, the blind length, starting chip stacks, etc.

request

No parameters

response

• Array of Game Structures:
• name - A unique identifier for the game structure type
• description - a short description of structure and the game