Download Functional Specifications - The Portfolio Website of Aaron Cook

Husky Hold'em: Functional Specifications, version 2.0
Aaron Cook, Dan McNamara, David Chanko, Chris Revel
9/22/2008
Introduction
Summary
This project is intended to replicate the functionality of two already available services. First,
online poker playing website is a service that allows remote players to gamble with one another,
the site itself is the trusted escrow for funds. Thus, we will serve an external customer market.
Second, We will replicate a poker statistical analysis program such as poker tracker, which is a
stand alone application that uses hand histories as inputs. This is a "shrinkwrap" application, and
serves poker enthusiasts. Chances are this group will be a subset of our first application. Finally,
our last effort will be a programmatic assisted client for our first services, that could provide tips
to the player based on what it sees. Because this functionality will depend heavily on our
implementation of the first product, we will be less specific about how they will be interfacing.
Requirements
Our poker application must provide users with the ability to play heads up texas hold'em exactly
as described by our rules, 100% of the time. The user must trust the application to maintain his
funds balance accurately. The interface must be very simple and appeal to the intuition of the
user. The user should be able to look at a single screenshot of the application and know what his
cards are, whose turn it is, what bet amount they will be facing, who else is in the hand, what all
the community cards are, how many chips each player has in front of him, and how many chips
are currently in the pot. So, none of that information can be hidden in a menu etc. Items the user
should be able to easily access are the hand histories of hands he has just seen, his current fund
balance, other tables that are running, and what account he is currently logged in under. The
statistics application will not need to be as stable as our poker client, and more emphasis should
be put on statistical accuracy. The user should be able to find the statistic he desires in a
straightforward way, and have the option of viewing some "standard" stats as well as custom
ones that he formulates himself. The stats application must be able to produce graphs that use big
bets and currency as units. The hand history importer must be highly automated, ideally once the
user has his default folder set it should be a one click process. Also see Project 1 for more detail.
Numbers
As of 9pm September 9th, there were 130k players on the pokerstars poker service, playing on
19.5k tables. These are numbers for what is arguably the most popular poker website, and are no
where near the numbers we will expect. However, that is not to say that we want to ignore the
performance of our service. I expect our intial attempts to be able to handle at least 10 tables.
Because it is turn based, latency of a <5 seconds is not a problem and does not affect gameplay,
so we have a much greater window of performance to work in. This should allow us to utilize the
server for most if not all calculations, to avoid users modifying the client maliciously.
It may be good to consider the business model of an online service, which is to maximize the
number of pots per hour. So, the more tables we can have dealing the more profitable our service
will be, so it is important to keep expandability in mind. Peak usage times would include most
non-office hours, typically 7pm-11pm and then throughout the day on weekends. Since most
services are international, this swing is spread across time zones as well.
The statistics application should be able to import over a 50,000 hands into the database. It
should be designed to have no maximum hand amount. Imports do not need a time requirement.
Statistics functions will not be expected to always perform operations over this many hands, and
a "standard" size request would consist of 500 hands. So, the program needs to have response
times of less than 10 seconds for all operations where the hand volume is 500, but note this
number does not include bandwidth issues. When operations are requested over more than 500
hands, there is no limit on response times.
Operating Environment
On the client side, the general website pages will run inside any Javascript enabled internet
browser. However, it will be recommended that the user uses an up to date browser for XHTML
1.0 compatibility, such as Internet Explorer 6.0 and Firefox 1.5.9 for proper display.
In order to run the poker game interface and statistics interface additional credentials are needed.
The user must be using be using Firefox 1.5+, Internet Explorer 6+, Safari 2.0.2+, or Opera 9+
internet browser. There are known problems with: Firefox 1.0.x, Internet Explorer 1.0-5.x, Safari
1.0-2.0.1, Opera 1.0-8.x, and the Konqueror browser.
The server code is designed to run on any web server that supports PHP 5. The GD graphics
library 2.0 or higher must be installed for generating statistical graphs.
Existing System
There are existing online poker systems as well as traditional off-line poker play. The main
reason for creating a new online poker game in our case is because we need a platform to use for
our player prediction component as well as an environment for our computer controlled
opponent.
One important question is why anyone would want to play a game that has traditionally
depended on the player's ability to read other players' intentions. While the lack of human
interaction is a definite limitation of the system, the ability to play multiple games at the same
time and the availability of opponents around the clock more than makes up for this problem.
Players can see much more action online than in real life and be exposed to a greater number of
opponents and styles, allowing the player to hone their technical poker skills.
Also, the ability to play against a computer opponent, while perhaps not as challenging as a
human adversary, provides a unique opportunity for the player to develop their creativity. The
computer opponent will be based off of the player's patterns in the past such as how they play a
strong hand, or how they react to opponent's actions. If the player find themselves being
routinely beaten by the computer, it might be time to change things up a bit as they are too
predictable.
The system will not provide the ability to wage real currency, however this is not a true
limitation as the site is mainly designed as a leaning tool for the game.
There are two main competitors in the poker statistics business. The older of the two,
PokerTracker, is currently in its third major revision, and retails for $90. The "new kid on the
block", Hold'em Manager is in its first retail debut at $80, but also has a small-stakes edition for
$55. In the real world if we wanted to enter this market we would need to have a competitive
advantage of some sort (speed, unique feature) that would entice users to abandon their
investment and re-import their hands into a new database, which can be a sizeable operation. I do
not expect our product to be able to have all of the features available in these applications.
Glossary / Terminology
<Insert Glossary again if we need to hand it in>dpm
References
Husky Hold'em Project proposal.
Microsoft Internet Explorer, Microsoft's Web
browser http://www.microsoft.com/windows/products/winfamily/ie/default.mspx.
Mozilla Firefox, popular alternative to Window's default web browser, Internet
Explorer. http://www.mozilla.com/en-US/firefox/.
Functional Description
Use Cases
A use case diagram detailing the high level interactions among the actors in the system is shown
below. Most of the details that apply to the user's experience in this diagram will be discussed in
the User section under Interfaces below. The actions from the administrator's point of view can
be found in the Administration Functions section below.
User Community
The system is designed for poker players who are still developing their skills and should be used
mainly as a tool to provide the player with some perspective on their play style. Beginning
players will find an environment in which they can learn the rules and experiment. Intermediate
players can use the system to find where their weaknesses lie and also, after importing a
sufficient amount of hand data into the system, they will be able to generate statics about their
play which can be used to find bad habits and predictability.
Administration Functions
The system will provide an interface for administrators to monitor the system. In the event of
disputes between players, game logs will be available to the administrator as well as a history of
players' games. This interface will be limited and will consist mainly of functions developers
find useful. Some of these functions are:
•
•
•
Summary of a player's account, including a list of game's played in a selected time
period, the value of the player's account, and other non private data about the user such as
contact information.
Ability to see any player's statistics. This will be helpful for testing as the administrators
will be super users who will have complete access to the system.
Allow standard reports to be run against the system to test functionality and correctness.
It is important to note that our administrator will not be an administrator in the traditional sense.
The main goal of the administrator functionality is to circumvent security features that might
make testing difficult, and to aid in verifying the system's correctness.
Error Handling
Connection errors such as a player being disconnected from the game, will result in the player
being removed from the table, and possibly the game ending if less than 2 players remain. If a
game is not ended by a disconnection, a player is is allowed to rejoin the table. A disconnection
occurs when a user does not ping the server for over 4 turns (which results in the player folding 4
times and then disconnecting).
Errors resulting from suspicious activity, will be logged accordingly.This may result in the
banning of the user.
The statistics application should have checks to ensure accuracy in its calculations, and
immediately stop calculations should an error be detected. The user should then get an option to
send an error report to us so that we can investigate. Hand Import errors should be taken less
seriously, and hands after the invalid one should be imported. However, we should alarm the
user that an error occured, and perhaps provide a message indicating the problem with the hand
history, since the user will be able to edit the plain text.
Security
The application will feature basic security standards, such as passwords for logging in. The login
process is handled by the Account Interface. When a user registers for the website, an md5 hash
is created of their password, and this is stored into the database. No other information about their
password is saved. This way, if the server database was ever compromised, only the user
password md5 hash will be available visible to the hacker, which a password cannot likely be
retrieved from. When a user logins in, their username is found in the database, and their given
password is converted in the md5 hash, and then compared with the hash found in the database.
If they match, the user is logged in. However, the user is not logged indefinitely, they are logged
in for 30 minutes. Because the login sessions lasts for a short finite time, it lessens the chance of
someone else using a users computer to ask Husky Hold'em illegitimately.
The main focus of this project's security will be on preventing cheating. Because this is a web
based application, it is important not to allow sensitive data and in the case of Javascript - code,
to be displayed and/or edited by malicious users.To counter these types of attacks, sensitive data
and code will only be handled on the server side, and not on the client's machine.
Further, data passed via Javascript is validated by the server. This is due to the general easiness
for a hacker to modify Javascript code and data. For example, the javascript that drives the Poker
Game Interface, stores players hands on locally on each users machine. In order to prevent
cheating and other hacking attempts, other player cards are stored encrypted on the local user
machine, to prevent them from being able to view other players cards. Further, if a user were to
modify their cards, so that they have a better hand, this would allow them to cheat when it came
to show their hand. To prevent such cheating, when a user sends their cards, they're validated
against the stored versions of their hand on the server.
PHP session handling allows us to limit the players ability to play more than one seat at a time. If
a player were to login more than once, this would allow them to potentially cheat during a game.
The login session handling allows only one session to exist per IP address. If a user tries to login
more than once, their previous session is overwritten. While this doesn't prevent users from using
proxies to login multiple times, it does make it more difficult to cheat.
All games will be logged, for debugging purposes and also in case of exploitations.
Help
Standard instructions will be provided where needed and an online version of the user manual
will be made available to the user. Links to various poker resources will be provided as well to
instruct the player how to play.
The statistics application will have its own user manual separate from the poker client. Within
the stats app, we should provide mouse-over tips that provide definitions for abbreviations with
the client.
Printing
N/A
Interfaces
User
There are four main interfaces where the user can interact with the system: an account
maintenance page, the statistics generator, the poker game interface, and the computer assistant
interface. A fifth general interface exists, the General site interface, that is common amongst all
of the interfaces.
Account
The first and simplest user interface is the Account Maintenance page where users can see a
general summary of their account including their account value. Here users can change their
password, other information about themselves and even delete their account. New users to the
site will create their account here. Since the focus of the system is on the poker game and
statistics, this section is simple and presents only basic functionality. Nevertheless, the
management of a user's funds and tracking of player history are two important areas of interest
and special emphasis will be placed on these areas including the option to search by dates or by
opponents and also to generate an account value summary resembling a bank statement.
Statistics Generator
The statistics generator will allow the user to generate graphs and summary information from
past games. Users will be able to enter data from a variety of online sources as well as access
hand history information from the system's own game. All this information can be used by the
user to analyze their performance and adjust their play style. Additionally, the user can search
past hands for a certain combination of cards dealt and bring up a hand summary window
detailing the results of the hand.
Some of the statistics generated will include(definitions in glossary):
•
•
•
•
•
•
$/100
PFR%
WTSD%
VPIP%
Agg
Cbet%
These are only a few of the statistics available and each will be presented in graph or table
format where appropriate.
In the following screenshot, we see a screen from holdem manager. The radio buttons on the left
control what actions we are looking at, and the colored chart on the right represents the "range"
that we have seen. So, in this example we are looking at calling a 3 Bet, and we see that Ace
King offsuit is 6.67% of this range.
Graph of Hands vs Dollars
If a player can play enough games against a certain opponent to gather sufficient data, the
system can also generate these statistics based on the opponent's patterns. An opponent
summary window will be used to display this data and allow a user to optionally view the details
of the statistics.
Player Prediction Interface
The player prediction interface will be accessible from both the game interface, if enabled by the
user, and will also be available to the user outside of the game for use with other online poker
sites. If a player is accessing the system from outside the game interface, they can set several
game parameters and ask the system to generate past statistics for the hand and the opponents'
actions. From inside the game interface, asking the system to generate advice will result in a
short message being posted to the screen stating the recommended course of action with the
option of displaying a more detailed report if the user desires. This message will be similar to
the opponent summary window described above.
Poker Game
The Poker Game user interface is used when the player is playing the actual game. This GUI
interfaces the players with the game logic and artificial intelligence. This interface is displayed
through the user's internet browser. The interface is dynamic and animated, supporting 2 to 6
players at a time. Each player is referred to by their username and shown at a poker table. The
Poker Game Interface is depicted below.
The interface represents the physical seating of a poker. Naturally, at the center of the screen is a
green rounded rectangle, which represents the table itself. Seated around the table, are the
players. Each player is depicted by a grey box. The remote players are depicted by the small grey
squares, while the local user is depicted by the larger rectangle. The position of the player at the
table is relative to the user's screen. For example, the local player is always depicted at the
bottom of the screen shown as player "Giants345". Seated after him in order, to his left, is
"Alyssa" and to his right is an empty seat. The game proceeds in a clockwise order, and it will be
Alyssa's turn after his. On the player of Alyssa's screen, things will look different, since the
display is relative. On her screen, she will be seated at the bottom. to her left, "Joey" will be
seated. To her right will be "Giants345".
Each remote player box contains two other items besides the player name. The first, in green
text, at the center of the box, is the current winnings the user has. This value is updated live,
whenever a player wins money. Below the current winnings is a line that represents the remote
player's current state. For example, this varies from "Joined game" when the player first joins the
game, to "Waiting", to a game action such as "Call $40".
At the bottom of the screen is the local player, represented by a rectangular grey box. This box
contains the player's current winnings (not shown), the player's hand, and the actions that are
available to them. The actions available to user are in displayed in blue, at the bottom of their
player box. These controls allow the player to fold, call, or raise. These controls are only
clickable when it is the players turn and the option is deemed possible. On the right side of the
local player's box is the player's hand, shown by two cards.
On the table, below the husky hold'em logo are community cards. These cards are not always
visible, and are shown at the proper time during the game. Located around the outside perimeter
of the table are the hands of the remote players. Like the community cards, these cards are not
shown until a certain phase of the game.
Empty seats at the table are displayed as in boxes similar to the remote player boxes. The boxes
simply contain "Empty", and are replaced with a full remote player box if and when a player sits
in that position at the table.
General Site Interface
The General Site Interface is used in every aspect of the website and is represented below.
The site interface is composed of a header and footer. The first, is the header. The header
contains the site's logo seen as "Husky Holde'Em" in the figure above and a menu, also shown
above as the maroon colored horizontal bar. The header is composed of images as well as
XHTML, and is driven by PHP. The menu contains dynamically list of options availabe to the
user at a specific page on the website. For example, shown above is a page that has the options
"Play Poker", Analyze Your Games" and "Create An Account". Another option exists, shown as
"Logout" in the figure. This option changes depending on whether the user is logged in or not. If
the user is logged in, the "Logout" option is available. If the user is not logged in, the "Login"
option is available. If the Login option is clicked, the user is taken to the login page (driven in
part by the Account Interface). If the user clicks Logout, their login session is termined and they
are logged out.
Below the menu, shown as beige box, is the body of the website. This is where the other
interfaces output their data to display to the user. Shown above is read out created by the Poker
Game interface, that allows a user to join a poker table. Below the beige box (not shown) is the
footer of the design. This footer consists of the bottom of the page, and currently consists of only
XHTML.
Software
The system will not be interfacing with any existing packages, although compatibility with all
major browsers needs to be ensured.
Boundary Conditions
While in theory there is no limit to the number of users that could potentially access our system,
we are limited by our hardware. The system will be designed to handle two or three tables at a
time as this should be sufficient for testing the correctness of the software. Each table will
initially be limited to 2-6 players, with room for expansion to 9. Additionally, a user will
initially be limited to playing one table at a time, possibly being increased to two or more.
Constraints
There are legal constraints placed on all gambling sites and on sites which deal with the transfer
of money. To avoid the limitations imposed by these constraints, we will not be supporting real
money, but only artificial currency.
Platforms
The system is designed to be accessed through a browser. As a result, any OS which allows the
use of a graphical browser will be supported. The specific browsers supported will be the most
current versions of Mozilla Firefox and Internet Explorer to start.
Internationalization
At this time there are no plans to internationalize the game. Given the limited scope of the
application, the use of fictional currency, and the standardized terms used, we believe that the
time spent on internationalization could be more effectively spent on development.
Performance
Capacity
The capacity of the system is sufficient to support several full tables (~25 users) without
straining the hardware of the server significantly. Based on the modular design of the server
components, e.g. Apache & MySQL, the server can be easily scaled to handle a nearly unlimited
number of users, by using clustering services to distribute transactional requests to multiple
identical web servers. MySQL can also be run through clustering services, essentially allowing
for "drop-in" scalability. Because of the nature of the program itself, and given the fact that all
computation is done based on information from the database, it is not neccesary to code the
application for multiple machines. In fact, because it is a stateless client, there is no need to
ensure that all players in a given table are on the same server or that they are even aware of the
presence of multiple machines running the application.
Response times
Response time of the game is a low priority, bluntly stated. There is a time constraint on player
actions, however, because this is a turn-based process, and the turn timeouts are sufficiently
lengthy, we are comfortable with response times as high as several seconds, without having a
significant negative effect on the playability of the game. A significant concern, however, due to
the nature of the internet, is in the ability of users to reconnect after being disconnected.
Reliability and Robustness
The main reliability concern which needs to be addressed is the consistency of our money
tracking system. If the the system fails or the user is disconnected their earnings or losses will be
saved to the database and not lost. Another important issue is that a user cannot lose all their
money at one table and before they leave that table buy into a separate table. To accomplish this
we need to design our system to to update the money totals in real time. This is not a problem
when permitting a user to play at one table at a time, but when multiple tables are active
concurrently careful control of the user's money, particularly when joining a new table, will be
added to ensure a user is not wagering more money than what is available in their account.
Reusability
The code generated through this project could be retasked (in part or as a whole) to server as a
user / account managemnet interface for another web site, and as an interactive statistical
analysis engine.
Portability
The system will be designed to be portable to different browsers, however there are no plans to
design the system for a different pla
tform such as a desktop application.
Expandability & Evolvability
The area most likely to be expanded would be the different game types available to the user.
While the system is initially designed for Texas Hold'em, the ease of adding additional game
types will be addressed. If possible, adding a new game type or changing a current game type
should involve mainly database changes and minimal coding.
As for adding different features to the site, the system will be designed to be modular with
respect to its major components to allow for additional features to be added without changing
current functionality.
Customization
Customization will not be a focus, although features such as the ability to change card style and
font size will be included.
Support & Maintenance
N/A
Configuration Management
We plan on releasing only one version of the software. Additional changes will all be made
server-side and will be indicated to the user through site announcements.
Documentation
Design Specifications: Details how the system will be implemented to meet the functional
specifications.
User Manual: Explains the basic user interfaces for the system including how to register with
the system, how to upload hand histories and view statistics, and how to play in the online game
interface.
Sample Login interface.