pokerserver

command module
v0.0.0-...-0c1b919 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2014 License: MIT Imports: 20 Imported by: 0

README

Hacker School Poker Engine

Overview

The Hacker School Poker Engine (HSPE) is a persistently running game server that coordinates and executes games of poker. Remote users can connect to HSPE and participate in games of poker against other remotely-connected users. The HSPE API provides a Restful interface with lightweight JSON-formatted responses to interact with the HSPE.

This documentation provides an overview of how the Hacker School Poker Engine (HSPE) operates and how you can use the API to build AI bots to play games of poker.

Game Rules

General rules

Games of poker in HSPE are played using the rules of No Limit Texas Holdem. We also enforce the following rules:

  • Each game has a maximum of 10 players allowed.

  • Each game has a minimum of 2 players required to play the game. If you are the only player in a game the game will not start until another player joins.

  • All players start with $10,000

  • Big blinds are $20, Small blinds are $10

Betting

Betting is allowed in increments no smaller than $1 (no floating point bets). All bets sent to HSPE must be valid. Invalid bets will lead to you immediately folding your hand. Invalid bets are:

  • Bets with negative values

  • Bets greater than your current wealth

  • Bets less than the minimum required to call and less than your current wealth (you are allowed to bet less than the amount required to call if this bet would put you “all in”)

  • Bets that raise on the previous bet, but do so less than the minimum raise amount as defined by the general rules of poker (you must raise at least as much as the last raise amount)

Understanding the state of the game

It is the responsibility of a player to query HSPE at regular intervals and get the state of the game they are playing. There is currently no rate limiting enforced but we suggest players to query HSPE no more than once every 50ms

Ordering and turns

A player can join a game at any time. If a hand is in progress, the player will start playing at the beginning of the next hand. If the game is full, the player will be put in queue and will start playing once there is a seat open at the table.

A player can fold and leave a game at any time.

HSPE will only accept bet/fold orders from a player when it is that player's turn. Orders sent when it is not that player's turn will be ignored. When it is a player's turn, they will have a 15 second window to send a bet/fold instruction before HSPE times out and removes the player from the game.

Running the server

Fork the github repo, run go build, then run pokerserver. This will start up a server running on your machine on port 8080.

Accessing the API

HSPE will be hosted on port 8080. Say you spin up a instance of the server running on 127.0.0.1. A request to retrieve all active games would look like:

GET https://127.0.0.1:8080/games/

Authentication

Some requests to HSPE need to be authenticated. HSPE uses HTTP basic authentication for this purpose.

Output formats

The bodies of successful responses will be sent in JSON format. Unsuccessful responses, those with error codes, maybe be sent as plain text not formatted as JSON.

API Resources

The following documentation assume the server is running on 127.0.0.1:8080. Replace this address with the appropriate location of the server.

Make a new user
Details
URI https://127.0.0.1:8080/users/
Synopsis Create a new user
HTTP Method POST
Parameters --
Success code 201 Created
Success body string(GUID)
Error response 400 Bad Request if can’t parse request
403 Forbidden if username already exists
Error body Error details (if applicable)
Requires Auth Y
Notes There is no second registration step. Authentication user and password are used to create new user.
Get information about all active games
Details
URI https://127.0.0.1:8080/games/
Synopsis Get detailed information on all active games
HTTP Method GET
Parameters --
Success code 200 OK
Success body array(Game)
Error response --
Error body --
Requires Auth N
Notes If authenticated request is made from a user who is playing in the game, that player’s “hole” cards will be included in the response
Get information about a specific game
Details
URI https://127.0.0.1:8080/games/:gameID
Synopsis Get detailed information on game with :gameID
HTTP Method GET
Parameters --
Success code 200 OK
Success body Game
Error response 404 Not Found if can’t find :gameID
401 Unauthorized if auth credentials are invalid
Error body Error details (if applicable)
Requires Auth N
Notes If authenticated request is made from a user who is playing in the game, that player’s “hole” cards will be included in the response
Join a game
Details
URI https://127.0.0.1:8080/games/:gameID/players/
Synopsis Join game :gameID
HTTP Method POST
Parameters --
Success code 201 Created if able to join game
202 Accepted if table is full but game does exist
Success body string(GUID)
Error response 404 Not Found if can’t find :gameID
401 Unauthorized if auth credentials are invalid
Error body Error details (if applicable)
Requires Auth Y
Notes --
Bet or Fold
Details
URI https://127.0.0.1:8080/games/:gameID/players/:playerID/acts/
Synopsis Place a bet or fold
HTTP Method POST
Parameters Act
Success code 201 Created
Success body --
Error response 403 Forbidden if trying to act when it’s not your turn
404 Not Found if can’t find :gameID or :playerID
401 Unauthorized if auth credentials are invalid
Error body Error details (if applicable)
Requires Auth Y
Notes --
Leave game
Details
URI https://127.0.0.1:8080/games/:gameID/players/:playerID
Synopsis Leave the game, forfeit winnings
HTTP Method DELETE
Parameters --
Success code 200 OK
Success body --
Error response 404 Not Found if can’t find :gameID or :playerID
401 Unauthorized if auth credentials are invalid
Error body Error details (if applicable)
Requires Auth Y
Notes --

Types

Act

Fields

Name Type Description
action int 0 for "fold", 1 for "bet"
betAmount uint How much to bet
Game

Fields

Name Type Description
gameID string GUID for this game
table array(Player) Who is actively playing
turn Turn Whose turn it is
cards dict[string:array(string)] Dealt cards up to this point
pots array(Pot) Money bet so far.

Notes
Each round will have at least one Pot. Some rounds might have multiple pots if side pots are needed. Pots are ordered chronologically earliest to latest

Player

Fields

Name Type Description
playerID string GUID identifying player
handle string Player username
state string “active” - Player needs to bet
“folded” - Player has folded their hand
“called” - Player has called or raised
wealth int Total money player has
bet_so_far int Amount bet so far in round
small_blind boolean Is this player small blind?
Turn

Fields

Name Type Description
playerID string GUID identifying player
bet_so_far int Amount bet so far in round
bet_to_player int Total amount that must be matched to call
minimum_raise int Minimum amount you can raise
expiry datetime Time you need to respond by in order to stay in the game
Cards Dictionary

Fields

Name Type Description
hole array(string) Player’s hole cards. Only populated if request is authenticated
flop array(string) Three cards dealt at the “Flop”
turn array(string) Card dealt at the “Turn”
river array(string) Card dealt at the “River”

Notes
flop, turn, and river are populated when the appropriate round is reached, and are otherwise null values. Cards are represented as strings of two characters. For example, the ace of spades is “AS”, the two of hearts is “2H”, and the ten of clubs is “TC”.

Pot

Fields

Name Type Description
size int Amount of money in this pot
players array(GUID) Players who have bet into this pot
Example JSON response

Request:

GET http://127.0.0.1:8080/games/fbbbbb44-bc4f-c3f6-6519-d81bd1a66d8a

Response:

[
   {
      "gameID":"fbbbbb44-bc4f-c3f6-6519-d81bd1a66d8a",
      "table":[
         {
            "playerID":"2fd318e4-0947-64b9-8b63-14f5a5824b8b",
            "handle":"",
            "state":"active",
            "wealth":15002,
            "bet_so_far":0,
            "small blind":true
         },
         {
            "playerID":"0dd7d693-06f9-b5ba-694d-f8779579fa8a",
            "handle":"",
            "state":"active",
            "wealth":4006,
            "bet_so_far":0,
            "small blind":false
         }
      ],
      "turn":{
         "playerID":"2fd318e4-0947-64b9-8b63-14f5a5824b8b",
         "bet_so_far":0,
         "bet_to_player":0,
         "minimum_raise":0,
         "expiry":"2014-09-24 15:14:53.021303798 -0400 EDT"
      },
      "cards":{
         "hole":[
            "AC",
            "TD"
         ],
         "flop":[
            "2S",
            "3S",
            "JS"
         ],
         "turn":[
            "4D"
         ],
         "river":[
            "AH"
         ]
      },
      "pots":[
         {
            "size":60,
            "players":[
               "8c479795-adcb-a3c1-bebd-4bdf54016f4a",
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         },
         {
            "size":0,
            "players":[
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         },
         {
            "size":0,
            "players":[
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         }
      ]
   }
]

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL