Follow @codingthewheel on Twitter for grue-repellent recipes and zombie survival tips.
Several years ago, a client asked me to come up with a prototype for a real-money online poker bot. That's right: a piece of software you park on your computer while it goes out to a site like PokerStars or Full Tilt and plays no-limit Holdem for you, at 4 or 14 different tables, for real-money stakes.
If you're a poker player, and particularly if you're an online poker player, you've probably heard rumors about the rise of the poker bots. Unfortunately there's very little hard information out there (for obvious reasons) about how to build one of these bots. In fact, many so-called authorities still dismiss poker bots as a relic of the overactive poker player's imagination.
Well, I'm here to tell you that online poker bots are 100% real, and I know this because I've built one. And if I can build one, well. Anybody can build one. What's more, over the course of this multi-part article, I'll show you how. But first, a teaser (click on the image for a larger version):
That, ladies and gents, is a picture of a full-featured poker bot managing three play-money tables (note: this same bot also handles real-money tables) at an honest-to-goodness, real-money online poker site. Of course, it could be any site. The bot implementation I'm going to reveal will work at all major online poker sites, including Poker Stars, Full Tilt, Party Poker, Ultimate Bet, and most other major venues.
I debated for a long time whether or not to make this information public, as I'm a poker player myself and have no desire to see the game ruined by an avalanche of poker bots. It's not that building a poker bot is some sort of black magic, known only to the privileged few. Any competent programmer can build one. But this information hasn't, so far as I know, been collected and presented in one place, certainly not as a "How To" complete with sample code. So the question I struggled with was this: is it irresponsible to publicize this information, such that every Internet script kiddie out there now has the ammunition he needs to actually build a bot?
After thinking about it, I've decided that keeping the technology of poker bot building secret is like declaring that only criminals can carry handguns. The fact is, there are people in the world right now who are doing this:
Poker bots, underground online poker boiler rooms, and collusion are a reality. That doesn't mean online poker's not worth playing, just that it pays to be educated about what's possible. Furthermore, there should be public discussion regarding what to do about it because one thing's certain: computers and programming languages aren't exactly going to be getting less powerful. The rise of the poker bots is a virtual certainty. I'd like to see the major online poker venues open up their famously vague "bot detection" and "anti-collusion" strategies to public scrutiny, as cryptography and security providers learned to do years ago. The best security algorithms and techniques all have the weight of public review behind them and I don't see how online poker's any different.
But even assuming all that weren't the case:
If you're visiting this page from 2 + 2 or another poker community, and you want to stay on top of this article (which will be in several parts), you can subscribe to the Coding the Wheel RSS feed or get it in your email inbox as I don't participate in these communities often. For easy digestibility, I'll be organizing these posts using a question and answer format, as there's a lot of highly technical material to cover.
Now, without further ado, let's talk about the basics. If you're not a programmer, fair warning: highly technical, possibly excruciatingly boring material ahead.
At a very high level, the poker bot is best analyzed according to the classic model of information handling: Input, Processing, Output.
You'll find that your programming tasks decompose rather nicely into these three basic stages.
Input. The input to the system is the poker client software itself, including all its windows, log files, and hand histories, as well as internal (often private) state maintained by the running executable. The goal of the input stage is to interrogate the poker client and produce an accurate model of the table state - your hole cards, names and stack sizes of your opponents, current bets, and so forth.
Processing. The processing stage runs independently of the other two stages. It's job is to take the table model assembled during the Input phase, and figure out whether to fold, check, bet, raise, or call. That's it. The code that performs this analysis should (ideally) know nothing about screen scraping or interrogating other applications. All it knows is how to take an abstract model of a poker table (probably expressed as some sort of PokerTable class) and determine which betting action to make.
Output. Once the processing stage has made a decision, the Output stage takes over. It's tasked with clicking the correct buttons on the screen, or simulating whatever user input is necessary in order to actually make the action occur on a given poker site/client.
This is a broad question which it's better to break down into particulars. First of all, there's a very easy way to detect hole cards via a screen-scraping or "poor-man's OCR" approach. You don't have to be an image-recognition expert. All you have to know is how to get the color of a handful of different pixels on the screen. Or to put it another way, for any given card in the deck, there are a handful of pixels you can test which will uniquely identify that card.
That's fairly easy to implement, and requires zero knowledge of OCR, image recognition, graphics processing, etc. But depending on the specific poker site, pulling card rank and suit information might be even easier. On some sites, the hole cards will be emitted into the real-time game summary info:
Occasionally you'll find that hole cards are emitted into the log file. Poker Stars, for example, conveniently emits this information into its log file, and it does so in real time (meaning you can snoop on it in real time, and in the next installment, I'll show you how):
::: 8s <-- Hole Card 1, Cool!
::: 13c <-- Hole Card 2, Cool!
Last but not least, hole cards are always included in the hand history for a given game:
*** HOLE CARDS ***
Dealt to CodingTheWheel [Qs 9h]
MargeLeb: calls 10
ke4njd: calls 10
diamondlover2nite: calls 10
WhoAmINot: calls 5
*** FLOP *** [4h 7c Qd]
CodingTheWheel: bets 10
The only problem is that, in many cases, the hand history file isn't emitted until the end of the hand.
You will need:
Those two pieces are essential. Other than that, you're free to structure things however you want. I'll have more to say on this as we get into the nitty-gritty details of the implementation.
There are a number of well-documented techniques for injecting your code - for example, a DLL you've written - into another application's address space. The method I used, and the method I'm going to recommend you use, is by installing what's known as a Windows Hook and specifically a CBT Hook. The relevant Windows API is SetWindowsHookEx, and here's the actual source code. If you're familiar with C++ and the Windows API, it should be straightforward:
The above source code would live in a DLL: the DLL you plan on injecting into the poker client's address space. This DLL will also contain whatever code you write to handle the "input" (screen-scraping) and "output" (button-clicking) stages of the bot.
An even better way is to use a two-stage injection process. The problem with global CBT hooks (or any other kind of global hook for that matter) is that they cause the hook DLL to be loaded into the address space of every process on the machine. If your hook DLL is very fat (for example, if it contains a bunch of code to do screen scraping and so forth) this can impact system performance as your DLL will get mapped into processes you care nothing about, like Notepad.exe.
So to get around that, make the hook DLL - the DLL that gets loaded into every process - as lightweight as possible. Then, whenever the hook DLL detects that it's been loaded by a poker client process, such as POKERSTARS.EXE, have it explicitly load another DLL (again, written by you) containing the bulk of the bot I/O processing code. This in fact is the purpose of the theInjector object in the above code sample - it figures out if the DLL is being mapped into a poker client process and, if so, uses LoadLibrary to load the actual DLL that knows how to do things like screen-scraping and so forth.
A picture might help to clarify:
Here, INJECT.DLL would be a lightweight DLL, written by you, which contains the CBT Hook procedure and installation code I showed you above. POKERBOT.DLL is the fat, messy DLL, also written by you, that contains the poker bot's screen-scraping logic.
Do things this way, and the drag on the system shouldn't even be noticeable, other than a brief load period when you first install the hook. This method is a lot easier than most other methods of DLL injection, and more importantly, it's supported across all the major Windows operating systems.
Almost every online poker client displays a small window in which game summary text is displayed:
Now, depending on which poker client you're using, this window may or may not be a standard Windows edit box or rich text control.
If it is a standard Windows control, you can get the handle (HWND) to the window, and then get its text via the GetWindowText API. Furthermore, you can do this even if the window you're interrogating is owned by another process.
But what you'll find is that many poker clients don't use "normal" Windows controls. They may write their own custom display controls, or they may subclass a standard Windows control and cause WM_GETTEXT to return an empty string.
In that case you have at least three options, none of them trivial:
When building the bot, I went with the second approach: API Hooking. Once you know how to hook a particular Windows API, so that whenever POKERSTARS.EXE thinks it's calling DrawText, it's actually calling your custom version of DrawText, which snoops on the text before passing the call on to the original DrawText, it's a simple matter to examine the output coordinates to determine, aha: this text is being written to the summary window; this text is being written to the title bar; etc.
This is a deep enough topic that I'll roll it into its own installment along with specific code examples.
Every Windows application in the world has to call into the Windows API to get things done: open files, create windows, display text, etc. Even language-specific libraries such as the C run time library or the C++ standard library internally will use the OS-provided facilities to work with things like files, memory, and so forth.
API hooking or "instrumentation" is the process of intercepting the function calls that an application (any application) makes, and redirecting them to a custom function defined by you. Specifically, you're going to intercept some of the calls that the poker application makes to the Windows API...
...and redirect these calls to a custom "interceptor" function, written by you. Your code thus gets a chance to examine the parameters of the call (which could be a string containing the player's name, for example) and do any other work you desire. When your "preprocessing" is done, you'll pass control back to the original API the poker application thought it was calling in the first place so that everything works transparently.
This technique can be used to extract all manner of useful internal information from any application, not just online poker clients. The best part is: you no longer have to write custom assembler code to achieve this. Instead you'll use a third-party library, and one of the best is a little-known Microsoft Research Project, Detours. Download it. Learn it. Love it. Learning how to accomplish API instrumentation means that ultimately, there's nothing the poker client can really hide from you - but that doesn't mean you'll be able to snoop around and figure out your opponent's hole cards. Don't even try. Unless the implementors have been sloppy, that information won't exist anywhere on your machine until your opponents have actually flipped their hole cards over.
And yes, if there's sufficient interest I'll put together a dedicated post with sample code showing exactly how to instrument a poker application.
We've covered a few of the specifics so far, and we'll cover many, many more in future installments. But specific techniques aside, getting information from the poker client is an exercise in detective work. First of all, be aware of just how much information is available:
The bot's job is simply to eavesdrop on that information, and analyze it to produce an accurate model of the table's state at any given point in time. So any technique now or in the future which allows you to do that is potentially a technique you'll want to leverage in the bot. Later, I'll suggest an architecture whereby a number of different interrogators can be used to query poker tables in a simple, extensible, and above all tweakable way.
That's the million-dollar question. I could tell you that the folks over at the University of Alberta's Computer Poker Research Group have made impressive headway towards producing a winning poker bot. I could tell you that extensible rules-based systems like the one I implemented for my bot...
...are a lot more powerful than you think. I could tell you a lot of things, and we'll investigate how to leverage some of the poker bot frameworks that are already out there, and how to combine those with your own custom rulesets. But understand one thing: you don't have to create a winning poker bot in order to make money with a poker bot. All you have to do is create a bot that's capable of breaking even.
If you can create a bot that breaks even - neither wins nor loses money - rakeback deals and specific programs like the Poker Stars Supernove Elite will ensure that you get a fairly hefty payday per bot account. I mean many tens of thousands of dollars per year, per account. And nothing except the logistical nightmare of it all restricts you to a single bot account; why not have ten; or a hundred?
And indeed, unbeknownst to the rest of the world, somewhere, someone probably does. But not me, and not you; and that's a disparity in basic firepower I'd like to see remedied, since none of the online poker sites have really stepped up to the plate and either a) made bots legal (similar to the way that they're legal on Internet Chess Club) or b) put effective prevention measures in place.
Well, you'll want to be well-versed in the nuances of C++ and the Windows API, at a minimum.
In addition to that, you'll either need to be familiar with, or get familiar with, an assortment of Windows development topics that reads like a chapter out of Richter (whose books I highly recommend purchasing and studying if you plan on implementing a bot yourself).
While it would probably be possible to build a bot using C#, VB.NET, or any other language, you'll find that some of the powers you'll need are only available through specific Windows APIs, and getting access to these APIs from a managed language is a little clunky. Another reason you'll want to use native C++ is that you'll need to sneek some of your code into the client poker process, and it's a lot cleaner to inject a small DLL than it is to inject all the machinery necessary to get managed code to run inside another (native) process.
This post has only scratched the surface of building a full-fledged poker bot. Hopefully it's given you food for thought and possibly whetted your appetite for the mountain of details left to be discussed. Assuming there's sufficient interest, I'll be posting a series of installments, each describing at a detailed level how to accomplish one specific poker bot task. If you found this document through a link on 2 + 2 or one of the other poker forums, you can subscribe to this site in a reader or get it in your email inbox, as I rarely post (or reply) on the poker forums these days.