DEV Community: Stojan Kojo

This article provides a definitive guide for anyone interested in the complexities of building or launching online poker software. It addresses the common misconception that there is a simple "tutorial" for creating a real-money poker platform.

Stojan Kojo — Wed, 10 Jun 2026 15:43:26 +0000

Stojan Kojo

Jun 10

Any good and easy tutorial on how to build a poker software?

#architecture #gamedev #softwaredevelopment #tutorial

9 min read

Any good and easy tutorial on how to build a poker software?

Stojan Kojo — Wed, 10 Jun 2026 15:42:20 +0000

Building a poker software platform from scratch is one of the most complex challenges in the gaming industry. There is no single "easy" tutorial that will take you from zero to a fully licensed, secure, and scalable real-money poker room. The gap between a simple coding exercise and a production-ready gaming platform is vast, involving not just game logic, but also regulatory compliance, financial security, and high-concurrency architecture.

However, if your goal is to understand the process, the components, and the strategic decisions required to build or launch poker software, we can break down the entire lifecycle. This guide serves as a comprehensive roadmap, replacing the need for a simple "how-to" video with a deep dive into the reality of poker platform development.

The Reality of "Building" Poker Software

Before writing a single line of code, it is crucial to understand what "building" means in this context. You are not just creating a game; you are building a bank, a security firm, a customer support center, and a regulated financial institution, all wrapped in a game interface.

A true poker software platform consists of three distinct layers:

The Game Engine: The logic that deals cards, calculates pot odds, determines winners, and manages game state.
The Platform/Backend: The user management, wallet systems, payment processing, and database architecture.
The Frontend: The client applications (Web, iOS, Android, Desktop) that players interact with.

While you can find open-source projects like PokerTH or Holdem Manager tutorials on GitHub, these are rarely suitable for a commercial, real-money operation. They lack the security, anti-fraud, and compliance features required by gaming commissions.

1. Introduction: The Scope of the Challenge

Why is there no "easy" tutorial for building poker software? Because the stakes are incredibly high. If you build a shopping cart incorrectly, a customer might not buy a shirt. If you build a poker room incorrectly, you risk losing player funds, getting hacked, or facing severe legal penalties.

The poker software industry is dominated by a few key players who have spent decades refining their code. New entrants usually do not build from scratch; they license White-Label solutions or use turnkey platforms.

This article is designed for founders, operators, and technical leads who want to understand the mechanics of poker software. Whether you are planning to code it yourself (the "Custom Build" route) or evaluate a vendor (the "White-Label" route), you need to know what lies under the hood. We will explore the architecture, the legal hurdles, the security requirements, and the operational realities of running a poker platform.

By the end of this guide, you will have a clear understanding of:

The core components of a poker network.
The difference between building from scratch vs. licensing.
The critical security measures required to prevent bots and collusion.
The financial and legal infrastructure needed for real-money gaming.
How to scale a platform from 10 to 10,000 concurrent players.

2. Core Concept: The Anatomy of a Poker Room

At its heart, poker software is a real-time, stateful, distributed system. Unlike a standard web app where a user loads a page and submits a form, a poker room is a continuous connection where thousands of players are interacting simultaneously.

The Game Engine

The game engine is the brain. It is responsible for:

Shuffling and Dealing: Using a certified Random Number Generator (RNG) to ensure fairness.
Hand Evaluation: Determining the winner of a pot based on complex hand rankings (e.g., Royal Flush vs. Full House).
State Management: Tracking the current phase of the hand (Pre-flop, Flop, Turn, River, Showdown) and the actions of every player.
Timer Management: Enforcing shot clocks (time limits for actions) to keep games moving.

The Network Architecture

Modern poker rooms are rarely standalone. They are often part of a Poker Network, where multiple brands share the same player pool.

Client-Server Model: The client (the player's app) sends actions (Fold, Call, Raise) to the server. The server validates the action, updates the game state, and broadcasts the new state to all players at the table.
WebSocket Protocol: To achieve the low latency required for poker, servers use WebSockets. This keeps a persistent connection open, allowing instant data transfer without the overhead of HTTP requests.

The Wallet System

This is the financial engine. It must handle:

Deposits and withdrawals.
Table stakes (buying in).
Rake calculation (the fee taken by the house).
Bonus tracking and promotion credits.
Multi-currency support.

3. Technical Breakdown: Architecture and Implementation

Building a poker platform requires a sophisticated stack. Let's break down the technical components required for a production-ready system.

The Backend: High Concurrency and Low Latency

Poker is I/O intensive. You need to handle thousands of concurrent connections with microsecond latency.

Languages: Go (Golang), C++, Rust, or Java are preferred for the core game engine due to their performance and concurrency models. Node.js or Python might be used for peripheral services (user profiles, marketing), but rarely for the core hand logic.
Database:
- Relational (PostgreSQL/MySQL): Used for transactional data like user accounts, financial ledgers, and KYC documents. ACID compliance is non-negotiable here.
- NoSQL (Redis/Cassandra): Used for game state. Redis is ideal for storing the current state of thousands of tables in memory, allowing for instant access and updates.
Message Queues: Systems like Apache Kafka or RabbitMQ are used to decouple services. For example, when a hand ends, the game engine publishes an event to the queue, which is then consumed by the analytics engine, the loyalty system, and the hand-history logger.

The Frontend: Cross-Platform Compatibility

Players expect to play anywhere.

Web: HTML5/Canvas/WebGL for browser-based play.
Mobile: Native apps (Swift for iOS, Kotlin for Android) or cross-platform frameworks like Flutter or React Native. Note: Native is often preferred for performance and access to device features.
Desktop: Often built using Electron or as a native wrapper, though the market is shifting heavily to mobile.

The RNG (Random Number Generator)

This is the most critical component for fairness.

Not Just Math.random(): Standard pseudo-random generators are predictable and insecure.
Certified RNGs: You must use a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG).
Auditing: The RNG must be tested and certified by independent labs like eCOGRA, GLI (Gaming Laboratories International), or iTech Labs. This certification is required for almost all gaming licenses.

Security Architecture

Encryption: All data in transit must be encrypted via TLS 1.3. Data at rest (database) must be encrypted.
Anti-Collusion: Algorithms that detect if players at the same table are sharing information or folding to each other intentionally.
Anti-Bot: Behavioral analysis to detect automated play (e.g., perfect timing, identical action patterns).
DDoS Protection: Poker rooms are frequent targets. You need enterprise-grade DDoS mitigation (e.g., Cloudflare, AWS Shield).

4. Business Impact: Cost, Profitability, and Operations

Choosing between building from scratch and buying a white-label solution is the most significant business decision you will make.

Option A: Custom Build (From Scratch)

Pros: Complete ownership of IP, no recurring licensing fees, full customization, no revenue sharing with a provider.
Cons: Extremely high upfront cost ($500k - $2M+), long development time (12-24 months), high risk of failure, requires a large team of senior engineers.
Best For: Large gaming groups, well-funded startups with a unique tech angle, or specific niche markets.

Option B: White-Label / Turnkey Solution

Pros: Launch in 4-8 weeks, lower upfront cost ($50k - $200k), proven technology, built-in compliance and payment integrations, shared liquidity (if on a network).
Cons: Monthly licensing fees, revenue share (often 20-40% of GGR), limited customization, dependency on the provider.
Best For: Most new operators, affiliates expanding into operations, and brands wanting to test the market quickly.

Revenue Models

How does a poker room make money?

Rake: A small percentage (usually 2.5% to 5%) of the pot, capped at a certain amount.
Time Collection: Charging a fixed fee every 30 minutes in high-stakes cash games.
Tournament Fees: The entry fee includes a portion that goes to the prize pool and a portion kept as the "rake" or "fee."
Affiliate Revenue: Earning money from players brought in by affiliates (though this is a cost, not revenue).

Operational Costs

Licensing Fees: Obtaining a gaming license (e.g., Malta, Curacao, Isle of Man) can cost $50k to $500k+ annually.
Payment Processing: Transaction fees (2-5%) and potential chargeback reserves.
Customer Support: 24/7 support teams are mandatory.
Marketing: The biggest cost. Acquiring a player (CPA) can range from $100 to $500+ depending on the market.

5. Common Mistakes

Even experienced teams make critical errors when entering the poker software space.

Underestimating Security: A single breach of the wallet system or a successful bot attack can destroy a brand's reputation instantly. Security must be a priority from day one, not an afterthought.
Ignoring Liquidity: A poker room with no players is useless. Launching without a strategy for player acquisition or without joining a network for shared liquidity is a common fatal error.
Poor Mobile Experience: Over 70% of poker traffic is mobile. If your mobile app is clunky or slow, you will lose players to competitors.
Inadequate RNG Certification: Using an uncertified RNG can lead to immediate license revocation and legal action.
Over-Engineering: Trying to build the "perfect" custom engine before launching. It is better to launch a robust white-label solution and iterate later.
Regulatory Blindness: Failing to understand the specific laws of the target market (e.g., KYC/AML requirements) can result in massive fines.

6. Best Practices

To succeed in the competitive poker software market, adhere to these industry standards:

Start with White-Label: Unless you have millions in funding and a unique tech advantage, start with a white-label solution to get to market fast.
Focus on Player Experience (UX): The interface should be intuitive. Complex tables with too many buttons confuse players.
Implement Robust KYC/AML: Know Your Customer (KYC) and Anti-Money Laundering (AML) checks are mandatory. Automate these processes to avoid bottlenecks.
Use Multi-Brand Networks: If possible, join a network that allows your brand to share players with other brands. This ensures tables fill up quickly.
Invest in Bonuses and Loyalty: A well-structured VIP program and rakeback system are essential for retention.
24/7 Support: Have a dedicated team ready to handle disputes, technical issues, and payment queries instantly.
Data Analytics: Use data to track player behavior, detect fraud, and optimize bonus offers.

7. Real-World Example: The Launch of "PokerPro"

Let's look at a hypothetical case study of "PokerPro," a new operator targeting the European market.

The Challenge:
PokerPro wanted to launch a real-money poker room within 90 days with a budget of $200,000. They had a strong marketing team but no technical expertise.

The Solution:
Instead of building from scratch, they opted for a White-Label solution from a provider based in Curacao.

Implementation Steps:

Licensing: They secured a sub-license under the Curacao eGaming authority ($15k setup).
Platform Integration: The provider supplied the game engine, wallet, and 24/7 support infrastructure.
Branding: PokerPro customized the skin (logo, colors, UI) to match their brand identity.
Payment Integration: The provider integrated their existing payment gateways (Visa, Crypto, Skrill).
Marketing: They launched an affiliate program offering 30% revenue share to drive traffic.

The Outcome:

Launch: Live in 8 weeks.
Liquidity: Immediate access to the provider's network of 5,000+ daily players.
Cost: $150k upfront + 25% of GGR (Gross Gaming Revenue) to the provider.
Result: Within 6 months, PokerPro was generating $50k/month in net revenue. They used the profits to build their own custom features later.

Key Takeaway: By not trying to "build" the software, they focused on what they did best: marketing and operations.

8. Comparison: Custom Build vs. White-Label

Feature	Custom Build (From Scratch)	White-Label / Turnkey
Development Time	12 - 24 Months	4 - 8 Weeks
Upfront Cost	$500,000 - $2,000,000+	$50,000 - $200,000
Ongoing Cost	Maintenance, Server, Team	Monthly Fee + Revenue Share
Flexibility	100% Customizable	Limited to Provider's Options
Liquidity	Must build own player pool	Shared network liquidity
Risk	High (Technical/Market failure)	Low (Proven tech)
Best For	Large Enterprises, Unique IP	Startups, Affiliates, Niche Brands

9. Future Trends

The poker software landscape is evolving rapidly. Here are the trends shaping the future:

AI and Personalization: Using AI to tailor bonus offers, detect bot behavior in real-time, and provide personalized coaching to players.
Blockchain and Crypto: Integration of cryptocurrencies for faster, anonymous (where legal) transactions. Some platforms are exploring "provably fair" systems using blockchain.
VR and AR Poker: Immersive poker rooms using Virtual Reality to replicate the physical casino experience.
Social Poker: Hybrid models where players can play for fun with social features, then seamlessly switch to real-money modes.
Mobile-First Design: As mobile usage surpasses desktop, platforms are optimizing specifically for small screens and touch interfaces.
Streamlined KYC: Using biometric verification and AI to speed up the onboarding process while maintaining compliance.

10. Conclusion

There is no "easy" tutorial to build poker software that results in a successful, compliant, and profitable business. The complexity of game logic, security, financial compliance, and high-concurrency architecture makes it a formidable challenge.

For most entrepreneurs, the path to success is not through writing code from scratch, but through strategic partnerships. Leveraging white-label solutions allows you to focus on the business side: marketing, player acquisition, and brand building. If you do choose to build from scratch, be prepared for a multi-year, multi-million dollar journey with a high risk of technical and regulatory hurdles.

Whether you build or buy, the key to success lies in trust. Players need to trust that the game is fair, their money is safe, and their data is protected. By prioritizing security, compliance, and user experience, you can build a poker platform that stands the test of time.

Building Poker Software: From Zero to Hero

Stojan Kojo — Tue, 09 Jun 2026 16:11:01 +0000

Building poker software from "zero to hero" requires transitioning from a simple game loop to a distributed, event-driven, real-time multiplayer architecture. The journey involves mastering deterministic state machines, cryptographic RNG, low-latency networking, and rigorous security compliance.

1. Phase 1: The Core Engine (Determinism & Logic)

The foundation is a pure, deterministic game engine. No networking, no UI, just logic.

Architecture: Use a Functional Core, Imperative Shell pattern. The core logic (rules, hand evaluation, state transitions) must be pure functions with no side effects.
State Machine: Implement a Finite State Machine (FSM) for betting rounds. Every state (Pre-flop, Flop, Turn, River) and transition (Check, Call, Raise) must be mathematically exhaustive.
Hand Evaluator: Integrate a Lookup Table (LUT) based evaluator (e.g., Cactus Kev) for $O(1)$ performance. Never use runtime logic for hand ranking.
RNG: Implement a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) (e.g., crypto.randomBytes in Node, rand_chacha in Rust). Crucial: The seed must be derived from high-entropy sources (OS entropy, hardware RNG).
Testing: Write Property-Based Tests (e.g., using QuickCheck) to verify that for any sequence of actions, the final pot distribution is mathematically correct.

2. Phase 2: Real-Time Networking (The "Live" Layer)

This phase introduces latency and concurrency challenges.

Protocol: Use WebSockets (raw ws or uWebSockets.js for C++ speed) or gRPC-Web for low-latency bi-directional communication. Avoid HTTP polling.
Message Format: Use Protocol Buffers (Protobuf) or MessagePack for binary serialization. JSON is too verbose and slow for high-frequency state updates.
Server Topology:
- Game Servers: Stateless, in-memory state machines. Each server handles ~500-2,000 concurrent tables depending on the language (Go/C++ > Node/Java).
- Lobby/Matchmaking: A separate service that assigns players to Game Servers based on region, stakes, and skill.
- State Sync: The server is the Source of Truth. Clients send intent (e.g., Action: Raise(100)), not state updates. The server validates, updates state, and broadcasts the new StateSnapshot to all clients in the room.
Latency Handling: Implement Client-Side Prediction for UI responsiveness (e.g., show the card flip immediately) but Server-Side Reconciliation to correct any discrepancies.

3. Phase 3: Data Persistence & Event Sourcing

Do not store the "current state" as the primary database record. Use Event Sourcing.

Pattern: Every action (Deal, Bet, Fold, Showdown) is an immutable event appended to a log.
Storage:
- Hot Path (Redis): Store the current GameState and active Event Log for fast access and replay. Use Redis Streams for high-throughput event logging.
- Cold Path (PostgreSQL): Store finalized HandHistories, PlayerStats, and Transactions.
Replayability: If a server crashes, the new instance loads the last Snapshot and replays the Event Log from Redis to reconstruct the exact state. This is critical for dispute resolution.

4. Phase 4: Security, Compliance & Anti-Fraud

This is where "social" poker becomes "real-money" poker.

RNG Certification: The RNG algorithm and its implementation must be audited by a third party (e.g., eCOGRA, GLI-11). You cannot just "use Math.random()".
Anti-Collusion:
- Graph Analysis: Run background jobs that analyze player interaction graphs. If Player A and B always fold when Player C raises, flag them.
- IP/Device Fingerprinting: Detect multiple accounts from the same IP/MAC address.
- Chip Transfer Monitoring: Detect abnormal chip flow between accounts (e.g., "soft play" where players avoid raising against each other).
Wallet Integration: Use a Double-Entry Ledger system. Every chip movement is a debit/credit pair. Never trust the balance field; calculate it as Sum(Credits) - Sum(Debits).

5. Phase 5: Scalability & Infrastructure

Microservices: Decouple the Lobby, Wallet, Game Logic, and Analytics.
Orchestration: Use Kubernetes (K8s) with Horizontal Pod Autoscaling (HPA). Scale Game Servers based on CPU/Memory usage or custom metrics (e.g., "Tables per Node").
Sharding: Shard the database by TableID or Region to distribute load.
Monitoring: Implement Distributed Tracing (Jaeger/Zipkin) to track a hand across services. Monitor P99 Latency for WebSocket messages.

Architecture Diagram (High Level)

[Client (React/Flutter)] 
       | (WebSocket/Protobuf)
       v
[API Gateway / Load Balancer]
       |
       +---> [Lobby Service] (Matchmaking, Player Profiles)
       |
       +---> [Game Server Cluster] (State Machines, FSM, RNG) <---+
       |                         |                                |
       |                         v                                |
       |                   [Redis Cluster] (State & Events)       |
       |                         |                                |
       +---> [Wallet Service] <---+ (Double-Entry Ledger)         |
       |                         |                                |
       +---> [Analytics Service] (Event Stream Processing)        |
       |                         |                                |
       +---> [Fraud Detection] (Background Job, Graph Analysis)   |
       |
       v
[PostgreSQL] (Hand Histories, Audit Logs)

Real-World Implementation Example

Scenario: A 6-max Hold'em table with 100k concurrent users.

Join: Player connects to Lobby Service, gets assigned to GameServer-42 via consistent hashing.
Hand Start: GameServer-42 generates a seed, draws cards (CSPRNG), emits HandStarted event.
Betting: Player clicks "Raise". Client sends Raise(100). Server validates against FSM. If valid, updates state, emits ActionApplied.
Side Pot: If an all-in occurs, the server calculates side pots using the multi-pass algorithm and emits SidePotCreated.
Showdown: Server evaluates hands (LUT), distributes pots, emits HandEnded.
Persistence: Event log is flushed to Redis, then asynchronously to PostgreSQL.
Audit: Fraud service consumes the event stream, updates player risk scores.

Trade-offs & Decisions

Language: Go or Rust for Game Servers (high concurrency, low GC pressure). Node.js or Python for Lobby/Analytics (rapid development, rich ecosystem).
Database: Redis for speed (state), PostgreSQL for integrity (wallets/histories). Avoid NoSQL for financial ledgers.
Consistency: Strong Consistency for wallet transactions (ACID). Eventual Consistency for player stats/follower counts.

FAQs

Q1: Why not use a monolithic architecture for a poker site?
Monoliths are easier to start with but become unmanageable at scale. A crash in the "Lobby" service could take down the "Game" logic, freezing all active hands. Microservices allow independent scaling (e.g., adding more Game Servers during peak hours without touching the Wallet service) and isolation of failures.

Q2: How do you handle the "All-In" logic if the server crashes mid-hand?
The server state is stored in Redis (in-memory) with persistence enabled (AOF/RDB). If the process crashes, the Kubernetes pod restarts. The new instance loads the last snapshot from Redis, replays the event log to reconstruct the exact state, and resumes the hand. This is why Event Sourcing is mandatory for real-money poker.

Q3: Can I use a standard web server (Nginx/Apache) for the game logic?
No. Nginx is for routing and static content. Poker requires persistent, full-duplex connections (WebSockets) and in-memory state management. You need a dedicated application server (e.g., Go, Node.js, C++) that maintains the connection and state for each table.

Q4: How is the RNG certified?
You cannot just "write good code." You must submit your RNG algorithm (and its implementation) to an independent testing lab (e.g., eCOGRA, GLI, BMM Testlabs). They run statistical tests (Chi-square, Kolmogorov-Smirnov) on billions of generated numbers to prove uniformity and unpredictability.

Q5: What is the biggest security risk in poker software?
Race Conditions in the wallet system. If two requests try to deduct chips simultaneously, a poorly designed system might deduct twice. This is solved using Optimistic Locking (version numbers) or Pessimistic Locking (database row locks) in the wallet service, ensuring only one transaction can modify a balance at a time.

What is the most efficient way to evaluate poker hands at scale?

Stojan Kojo — Sun, 07 Jun 2026 08:21:35 +0000

The most efficient way to evaluate poker hands at scale is not to write logic that checks for straights and flushes at runtime. Instead, the industry standard for high-frequency trading (HFT) and real-money poker is pre-computed Lookup Tables (LUTs) combined with bitwise operations and SIMD (Single Instruction, Multiple Data) vectorization.

The goal is to reduce hand evaluation to a single CPU instruction or a few array lookups, achieving nanosecond-level latency. This allows the engine to evaluate millions of hands per second for Monte Carlo simulations, AI training, or real-time fairness checks.

1. The Core Architecture: Lookup Tables (LUTs)

The fundamental insight is that there are a finite number of 5-card combinations from a 52-card deck: $\binom{52}{5} = 2,598,960$.
For 7-card games (Hold'em/Omaha), it's $\binom{52}{7} = 133,784,560$.

The Strategy:

Pre-computation: Before the server starts, generate a massive array where every possible 5-card (or 7-card) combination maps to a unique integer "strength" value.
Runtime: Convert the player's hand into a unique integer key (hash).
Lookup: Access the array at that index. The value returned is the hand's strength.

Memory Trade-off:

5-Card LUT: ~2.6 million entries. If each entry is a 4-byte integer, this is ~10 MB. Fits easily in L3 CPU cache.
7-Card LUT: ~133 million entries. ~534 MB. Fits in RAM, but may spill out of cache on large servers.
Optimization: Most engines use a 5-card LUT and a 7-to-5 reduction algorithm. They generate all $\binom{7}{5} = 21$ combinations, look them up, and pick the best.

2. The Bitwise Implementation (The "Cactus Kev" / "TwoPlusTwo" Method)

The most famous high-performance implementation is the Cactus Kev algorithm (popularized by poker-eval in C/C++). It maps cards to prime numbers or bitmasks to perform arithmetic operations that instantly detect flushes and straights.

Data Representation

Cards: Represented as integers.
Ranks: 2-14 (2-Ace).
Suits: 4 bits (1 for Spade, 2 for Heart, etc.).
Bitmasks: A 52-bit integer where the $i$-th bit is 1 if the $i$-th card is present.

The Evaluation Function (Pseudocode)

// Pre-computed table: maps a 5-card hash to a strength score (0-7462)
// Lower score = better hand (or higher, depending on convention)
int lookup_table[2598960]; 

int evaluate_hand(int hand_mask) {
    // 1. Check for Flush: Sum of suit bits. If any suit sum >= 4 (5 cards), it's a flush.
    // This is done via bitwise AND with suit masks (e.g., 0xF0F0F0F0F0F0F0F0)
    if (is_flush(hand_mask)) {
        return lookup_flush[hand_mask]; // Pre-computed flush strength
    }

    // 2. Check for Straight: Use a "rank bitboard".
    // Shift bits to detect sequences of 5 consecutive bits.
    if (is_straight(hand_mask)) {
        return lookup_straight[hand_mask];
    }

    // 3. Standard Evaluation (Pairs, Trips, etc.)
    // Use the "Cactus Kev" prime multiplication method.
    // Each rank is a prime: 2=2, 3=3, ..., A=41.
    // Multiply the primes of the 5 cards.
    // The product is unique for every hand type (e.g., A-A-A-K-K always yields X).
    int product = 1;
    for (int i = 0; i < 5; i++) {
        product *= RANK_PRIMES[get_rank(hand_mask, i)];
    }

    return lookup_table[product];
}

Why this is fast:

No Loops: The logic uses bitwise shifts and masks, which are single-cycle CPU instructions.
Cache Friendly: The lookup table is small enough to stay in the CPU's L1/L2 cache.
Branch Prediction: The if statements are highly predictable (most hands are high-card, few are straights), minimizing pipeline stalls.

3. Scaling to Millions of Hands: SIMD & Vectorization

For Monte Carlo simulations (e.g., "What is my equity if I run this hand 100,000 times?"), single-threaded evaluation is too slow. You must use SIMD (AVX2, AVX-512 on x86; NEON on ARM).

The Approach:

Load 8 or 16 hands into a single 256-bit or 512-bit register.
Perform the bitwise operations (flush check, straight check) on all 8/16 hands simultaneously.
Use lookup tables that are vectorized (or use shuffle instructions to map multiple keys to multiple values).

Library Example: HandEvaluator in Rust/C++ with AVX2

// Conceptual SIMD evaluation (using a crate like `hand-eval-simd`)
fn evaluate_batch(hands: &[Hand], results: &mut [u32]) {
    // Load 8 hands into a 256-bit register
    let hand_vec = load_simd(hands);

    // Parallel Flush Check
    let flush_mask = check_flush_simd(hand_vec);

    // Parallel Straight Check
    let straight_mask = check_straight_simd(hand_vec);

    // Parallel Lookup (requires a specialized vectorized LUT or scatter/gather)
    let scores = vectorized_lookup(hand_vec, flush_mask, straight_mask);

    store_simd(results, scores);
}

This can achieve 100M+ hands per second per core on modern CPUs.

4. Architecture for Production Systems

The "Evaluator Service" Microservice

In a distributed architecture, do not embed the heavy evaluation logic in the main game loop if you need to run simulations. Offload it to a dedicated Evaluator Service.

Protocol: gRPC or UDP (for low latency).
Language: C++ or Rust for the evaluator core (maximum performance).
Interface:
- EvaluateHandsRequest: { hand_1: [c1, c2...], hand_2: [...] }
- EvaluateHandsResponse: { score_1: 1234, score_2: 5678 }
Scaling: Run the service as a stateless pod in Kubernetes. Use Horizontal Pod Autoscaling (HPA) based on CPU utilization.

Database & Caching

Redis: Cache the results of common board textures (e.g., A-K-Q-J-T on board) if the same board appears frequently in simulations.
PostgreSQL: Store the final hand history, including the hand_strength_score and winner_ids. Do not store the raw bitmasks unless needed for debugging.

5. Security & Compliance

Determinism: The evaluator must be pure. No random numbers, no external state. If the same 7 cards are passed in, the same score must be returned. This is non-negotiable for regulatory compliance.
Certification: The LUT generation algorithm must be certified by an independent lab (e.g., eCOGRA, GLI). The source code for the LUT generator is often audited, not just the runtime binary.
Anti-Cheating: Never expose the evaluator logic to the client. The client sends cards only when allowed; the server evaluates.

6. Real-World Implementation Example

Scenario: A 6-max No-Limit Hold'em table.

Pre-flop: Player A (AA) vs Player B (KK).
Simulation: The engine runs 100,000 Monte Carlo simulations to determine equity for the "All-In" button.
Execution:
- The "Simulator" service generates random boards (5 cards).
- It calls the Evaluator 200,000 times (2 hands x 100k simulations).
- The Evaluator uses the Cactus Kev LUT + AVX2 to process 8 hands in parallel.
- Total time: ~50ms.
Result: Player A has 82% equity. The server updates the UI.

Trade-offs:

Memory vs. Speed: A full 7-card LUT is fast but memory-heavy (500MB+). A 5-card LUT + 21 combinations is slower (21x lookups) but uses only 10MB.
Solution: Hybrid approach. Use a 5-card LUT. If the board is a flush/straight, use the optimized path. Otherwise, use the standard lookup.

7. Code Snippet: The "Fast" Evaluator (Node.js with N-API)

Since Node.js is single-threaded and slow for raw math, use N-API to bind a C++ evaluator.

// evaluator.cc (C++ N-API Module)
#include <node_api.h>
#include "poker_eval.h" // The C++ LUT engine

 napi_value EvaluateHand(napi_env env, napi_callback_info info) {
   // 1. Extract card array from JS
   // 2. Convert to bitboard (uint64_t)
   // 3. Call C++ evaluate(bitboard) -> int
   // 4. Return int to JS
   return napi_create_int32(env, result);
 }

// evaluator.js (Node.js)
const evalModule = require('./build/Release/evaluator.node');

function getHandStrength(holeCards, communityCards) {
  // Hole: [0, 1], Board: [2, 3, 4, 5, 6]
  const allCards = [...holeCards, ...communityCards];
  return evalModule.evaluate(allCards);
}

FAQs

Q1: Why not just write a simple if (isFlush) return ... function in Python/JavaScript?
Because a standard if-else approach involves loops to check suits, loops to check ranks, and sorting. This is $O(N)$ or $O(N \log N)$ and involves many conditional branches. In a high-load environment (10k hands/sec), this creates a bottleneck and high CPU usage. A LUT approach is $O(1)$ and uses bitwise operations, which are orders of magnitude faster.

Q2: How do you handle 7-card hands (Omaha/Hold'em) with a 5-card LUT?
You generate all $\binom{7}{5} = 21$ possible 5-card combinations from the 7 available cards. You run the 5-card LUT on each of the 21 combinations and pick the highest score. This is still extremely fast because the LUT lookup is instant. Advanced engines optimize this by pre-computing the "best 5 of 7" directly into a 7-card LUT, but the 21-lookup method is often sufficient and uses less memory.

Q3: Can I use this for Web3/Blockchain poker?
Yes, but with a caveat. On-chain evaluation (e.g., on Ethereum) is too expensive for full LUTs due to gas costs. The standard pattern is Off-chain Evaluation with On-chain Verification. The server (or a trusted oracle) evaluates the hand off-chain using the LUT, signs the result, and the smart contract verifies the signature. The contract never runs the evaluator.

Q4: What is the "Cactus Kev" method?
It is a specific algorithm developed by Cactus Kev (Eric Persson) that maps each card rank to a prime number. The product of the primes of 5 cards is unique for every hand type (e.g., a Full House of Aces over Kings has a unique product). This allows the engine to determine the hand type and strength using a single multiplication and a lookup table, avoiding complex conditional logic.

Q5: How do I ensure the LUT is correct and not buggy?
You must verify the LUT against a known reference implementation (like the PokerStars or WSOP logic) or a brute-force generator.

Generate all 2.6M 5-card hands.
Evaluate them with a slow, correct (but inefficient) reference algorithm.
Evaluate them with your fast LUT.
Assert that the results match for every single hand. This verification process is part of your CI/CD pipeline.

How do you handle side pots correctly when multiple all-ins occur?

Stojan Kojo — Sun, 07 Jun 2026 08:19:19 +0000

Handling side pots correctly is one of the most critical logic challenges in a poker engine, as errors here directly result in financial loss and regulatory failure. The solution requires a deterministic, multi-pass evaluation algorithm that decouples pot creation from hand evaluation.

The core principle is: A player can only win a pot they contributed to. The engine must logically segregate the total chips on the table into distinct "Pots" (Main, Side 1, Side 2, etc.) based on the minimum effective stack at each stage of the betting.

1. The Data Model: Pot Segregation

Do not store a single totalPot integer. Instead, maintain a list of Pot objects, each tracking:

id: Unique identifier.
eligiblePlayers: A Set of player IDs allowed to compete for this pot.
amount: Total chips in the pot.
contributions: A map of { playerId: amount } to track exactly who put in what (crucial for refunds if a player is eliminated early or for audit trails).

State Transition Logic:
When a player goes All-In, the engine must immediately check if this All-In amount is less than the current highestBet. If so, it triggers a Side Pot Creation event.

2. The Algorithm: Multi-Pass Side Pot Calculation

The most robust implementation uses a two-pass algorithm (or a single pass with deferred distribution) to ensure mathematical accuracy.

Pass 1: Determine Pot Boundaries (The "Stack Normalization" Phase)

Before dealing cards or evaluating hands, the engine must calculate exactly how many pots exist and their sizes.

Sort Players by Stack: Get all active players and sort them by their currentStack (chips remaining before the current betting round).
Identify Effective Stacks: Iterate through the sorted players to find "breakpoints."
- Example: Player A (100), Player B (100), Player C (50), Player D (200).
- The first "layer" is limited by the smallest stack (Player C: 50). Everyone contributes 50 to the Main Pot.
- Player C is now "All-In" for the Main Pot layer.
- Remaining stacks: A (50), B (50), D (150).
- The next "layer" is limited by the next smallest (A/B: 50). A and B contribute 50 to Side Pot 1.
- Player D contributes 50 to Side Pot 1.
- Remaining stacks: D (100).
- Side Pot 2: D contributes the remaining 100. Only D is eligible? No, D is the only one left, but usually, this implies D is raising against someone else.
- Correction: The logic is:
  - Main Pot: Everyone contributes min(stack, current_bet).
  - Side Pot 1: Players with stack > min_bet contribute the difference up to the next lowest stack.
  - Side Pot N: Repeat until all chips are allocated.

Pseudocode for Pot Calculation:

function calculateSidePots(players: Player[], currentHighestBet: number): Pot[] {
  // 1. Filter active players (not folded)
  const activePlayers = players.filter(p => p.status === 'active' || p.status === 'all_in');

  // 2. Sort by remaining stack (chips they can still put in)
  activePlayers.sort((a, b) => a.remainingStack - b.remainingStack);

  const pots: Pot[] = [];
  let currentLayerLimit = 0;
  let layerIndex = 0;

  // 3. Iterate through stack layers
  for (let i = 0; i < activePlayers.length; i++) {
    const player = activePlayers[i];
    const amountToContribute = Math.min(player.remainingStack, currentHighestBet - currentLayerLimit);

    // If the player has no more chips to contribute to this layer, skip
    if (amountToContribute <= 0) continue;

    // Create a new pot layer if this is a new stack tier
    if (player.remainingStack > currentLayerLimit) {
      const newPot = new Pot(layerIndex++);
      // Add all players who have enough stack for this layer
      activePlayers.forEach(p => {
        if (p.remainingStack >= currentLayerLimit + amountToContribute) {
          const contribution = Math.min(p.remainingStack - currentLayerLimit, amountToContribute);
          newPot.addContribution(p.id, contribution);
          p.remainingStack -= contribution;
        }
      });
      currentLayerLimit += amountToContribute;
      pots.push(newPot);
    }
  }

  return pots;
}

Pass 2: Hand Evaluation & Distribution

Once pots are defined, the engine evaluates hands independently for each pot.

Iterate Pots: Start with the Main Pot, then Side 1, etc.
Filter Eligible Players: For Pot X, only players in Pot X.eligiblePlayers are considered.
Evaluate: Run the HandEvaluator for eligible players using their hole cards and community cards.
Distribute:
- If multiple players tie for the best hand in Pot X, split the pot.
- If a player went all-in and lost, they are removed from the eligiblePlayers set for subsequent pots.

Critical Edge Case: The "Unmatched" All-In
If Player A (100) calls Player B (150) All-In, and Player B raises to 200:

Player A puts in 100.
Player B puts in 100 (matched) + 50 (side pot).
Main Pot: 200 (100 each).
Side Pot: 0 (Player A cannot contribute).
Player B wins the Side Pot automatically (no one else can contest it), but the engine must still run the logic to confirm the Main Pot winner.

3. Architecture & Data Flow

The "Pot Manager" Microservice

In a large-scale architecture, the pot logic should be isolated in a dedicated service or a pure function within the Game Engine.

Input: List<Player>, CurrentHighestBet, BettingHistory.
Output: List<Pot> with winners and amounts.
State: The Pot objects are immutable snapshots stored in the event log.

Database Schema (PostgreSQL)

Store pot structures as JSONB or normalized tables for auditability.

CREATE TABLE game_pots (
    id UUID PRIMARY KEY,
    game_id UUID NOT NULL,
    pot_type VARCHAR(20) NOT NULL, -- 'MAIN', 'SIDE_1', 'SIDE_2'
    total_amount BIGINT NOT NULL,
    eligible_players JSONB NOT NULL, -- ["player_id_1", "player_id_2"]
    contributions JSONB NOT NULL,    -- {"player_id_1": 100, "player_id_2": 100}
    winner_ids JSONB,                -- ["player_id_1"]
    amount_per_winner JSONB,         -- {"player_id_1": 200}
    created_at TIMESTAMP DEFAULT NOW()
);

4. Scalability & Performance

Algorithmic Complexity: The sorting and layering algorithm is $O(N \log N)$ where $N$ is the number of players. Since $N \le 10$ (usually 9 or 10 max), this is effectively $O(1)$ and executes in microseconds.
Concurrency: Pot calculation is a read-heavy operation (triggered at showdown) but must be consistent. Since it's a pure function of the game state, it can be executed on a separate worker thread without locking the main game loop.
Memory: Do not create new objects for every calculation if possible. Reuse object pools for Pot and Contribution objects to reduce GC pressure in high-frequency environments (e.g., 100k hands/hour).

5. Security & Compliance

Audit Trail: Every side pot creation must be logged as an event: SidePotCreated(potId, amount, eligiblePlayers).
Determinism: The algorithm must produce the exact same result on any server. No floating-point math; use integer arithmetic (cents/smallest currency unit) exclusively.
Refund Logic: If a player folds after a side pot is created but before the showdown, they are simply removed from the eligiblePlayers set. Their contribution remains in the pot. If a player goes all-in and folds before the showdown (impossible in poker, but hypothetically), the logic must handle refunds correctly. (In poker, once all-in, you are in the pot regardless of folding).

Real-World Example: Three-Way All-In

Player A: 500 chips
Player B: 300 chips
Player C: 150 chips
Current Bet: 100 (everyone calls 100).
Action:
1. C goes All-In (150).
2. A and B call (150 each).
3. Main Pot: 450 (150 each). Eligible: A, B, C.
4. Remaining: A (350), B (150).
5. B goes All-In (150 more).
6. A calls (150).
7. Side Pot 1: 300 (150 from A, 150 from B). Eligible: A, B. (C is ineligible).
8. Remaining: A (200).
9. A goes All-In (200).
10. Side Pot 2: 200 (200 from A). Eligible: A only? No, A is the only one left to contribute, but B and C are already all-in.
11. Correction: If A has 200 left and B/C are all-in, A cannot raise against them. A just calls.
12. Scenario Change: A raises to 500. B calls 300 (all in). C calls 150 (all in).
13. Main: 450 (150 each).
14. Side 1: 300 (150 from A, 150 from B).
15. Side 2: 200 (200 from A).
16. Winners:
  - Main Pot: Best hand among A, B, C.
  - Side 1: Best hand among A, B.
  - Side 2: A (automatic win, no one else eligible).

Implementation Checklist

Normalize Stacks: Always work with remaining stacks, not total bets.
Layering: Create pots from smallest stack to largest.
Eligibility: Strictly enforce that a player cannot win a pot they didn't contribute to.
Tie-Breaking: Handle split pots within each layer independently.
Logging: Record every pot distribution event.

FAQs

Q1: Can a player win a side pot if they are the only one who contributed to it?
Yes. If Player A raises, Player B folds, and Player C goes all-in for less than the raise, Player A and C play for the Main Pot. If Player A has enough chips to raise again and Player B is out, any further chips A puts in form a "Side Pot" where A is the only eligible player. A wins this pot automatically. The engine must still create the pot object for audit purposes.

Q2: What happens if two players tie for the best hand in a side pot?
The side pot is split equally between the tied players. Any odd chip (if the amount is odd) is typically awarded to the player with the highest card in the hand (or by position rules defined in the specific game variant), or simply given to the player to the left of the dealer button if tie-breakers aren't specified. The engine must implement a "split pot" function that handles integer division and remainder distribution.

Q3: How does the engine handle "All-In" players who fold?
In poker, a player who goes All-In cannot fold. They remain in the hand until the showdown for any pot they contributed to. The FSM state machine must prevent a "Fold" action for any player with status == 'all_in'. The only way they leave the active betting is if they lose the pot or the hand ends.

Q4: Is it possible to have a side pot with only one player?
Yes, but only if that player is the only one eligible. This usually happens if one player raises, everyone else folds, and the raiser has chips left over (which is impossible in a standard hand unless it's a specific tournament rule or a multi-way all-in scenario where the side pot is created by the remaining stack of the aggressor against no one else). In a standard 3-way all-in, Side Pot 2 might only have Player A if B and C are all-in and A raises further, and B/C cannot call. Wait, if B and C are all-in, they can't call. So A's extra chips go into a pot where only A is eligible. A wins it.

Q5: How do you handle the "Dead Button" or special tournament rules with side pots?
The side pot logic is independent of button position. The button determines the order of action, but the side pot calculation is purely mathematical based on stack sizes. The "Dead Button" (where a player sits out but chips remain) is handled by ensuring the eligiblePlayers set only includes players with status != 'folded' and status != 'sitting_out' (if sitting out means they can't win). The engine must respect the specific tournament rules regarding "sitting out" players in the eligiblePlayers filter.

How should betting rounds be modeled using finite state machines?

Stojan Kojo — Sun, 07 Jun 2026 08:13:44 +0000

Modeling betting rounds using a Finite State Machine (FSM) is the industry standard for ensuring deterministic, bug-free poker logic. The core concept is to treat every possible game situation as a distinct State and every player action as a Transition that moves the system to a new state. This eliminates "if-else" hell and guarantees that invalid actions (like raising before the flop in a specific variant) are mathematically impossible to execute.

1. The Core FSM Architecture

In a poker engine, the betting round is not a loop; it is a state machine where the current state dictates valid transitions.

State Definition

The state must capture the exact context of the round, not just the current pot size. A robust state tuple looks like this:

type BettingState = {
  street: 'preflop' | 'flop' | 'turn' | 'river';
  currentActorId: string;
  highestBet: number;      // The current best bet in the round
  minRaise: number;        // Minimum legal raise amount
  activePlayers: Set<string>; // Players still in the hand
  lastAggressorId: string | null; // Who made the last raise?
  actionCount: number;     // Used to detect round completion (everyone acted)
  roundStatus: 'active' | 'completed' | 'all_in';
};

Transition Logic

Transitions are triggered by PlayerAction events. The FSM validates the action against the current state before applying it.

Valid Transitions (Example: No-Limit Hold'em):

Idle/Start: Transition to WaitingForBlinds.
Blind Posting: Transition to PreFlopActive.
Check: Valid only if highestBet == 0. Moves actor to next player.
Call: Valid if betAmount == highestBet. Moves actor to next player.
Raise: Valid if betAmount > highestBet and betAmount >= minRaise. Resets the "round completion" counter. Moves actor to next player.
Fold: Removes player from activePlayers. If only 1 player remains, transition to Showdown.
All-In: Special transition. Player remains active but cannot act further. If highestBet remains unmet, the round continues; otherwise, it closes.

2. Implementation Details: The State Machine Pattern

Do not use simple boolean flags (e.g., isRoundOver). Use a formal State Machine library or a strict class structure.

The State Machine Class (TypeScript Example)

enum BettingRoundState {
  OPENING,
  ACTIVE,
  ALL_IN,
  COMPLETED
}

class BettingRoundFSM {
  private state: BettingRoundState;
  private context: BettingStateContext;

  constructor(context: BettingStateContext) {
    this.context = context;
    this.state = BettingRoundState.OPENING;
  }

  // The core entry point for all actions
  async processAction(action: Action): Promise<void> {
    const validTransitions = this.getValidTransitions();

    if (!validTransitions.includes(action.type)) {
      throw new InvalidActionError(`Action ${action.type} invalid in state ${this.state}`);
    }

    // Execute state transition logic
    switch (this.state) {
      case BettingRoundState.OPENING:
        this.handleOpening(action);
        break;
      case BettingRoundState.ACTIVE:
        this.handleActive(action);
        break;
      case BettingRoundState.ALL_IN:
        this.handleAllIn(action);
        break;
    }

    // Check for round termination
    if (this.isRoundComplete()) {
      this.state = BettingRoundState.COMPLETED;
      await this.triggerNextStreet();
    }
  }

  private handleActive(action: Action): void {
    // Update highest bet
    if (action.amount > this.context.highestBet) {
      this.context.highestBet = action.amount;
      this.context.lastAggressorId = action.playerId;
      this.context.roundStatus = 'reset'; // Reset counter, everyone must act again
    }

    // Handle player elimination
    if (action.type === 'FOLD') {
      this.context.activePlayers.delete(action.playerId);
    }

    // Move turn to next active player
    this.context.currentActorId = this.getNextActivePlayer();
  }

  private isRoundComplete(): boolean {
    // Logic: Everyone active has matched the highest bet
    // AND the last aggressor has acted (or no one raised)
    const allMatched = this.context.activePlayers.every(p => 
      p.currentBet === this.context.highestBet || p.isAllIn
    );
    const everyoneActed = this.context.actionCount >= this.context.activePlayers.size;

    return allMatched && (this.context.lastAggressorId === null || this.context.lastAggressorId === this.context.currentActorId);
  }
}

3. Handling Edge Cases & Complex Logic

Side Pots & All-Ins

The FSM must handle "All-In" as a special state modifier, not a standard action.

State Split: When a player goes all-in, the FSM creates a Side Pot context.
Transition: The player is removed from the "Active Betting" set but remains in the "Showdown Eligible" set.
Logic: The main round continues with remaining players. If the all-in player was the aggressor, the round only ends when everyone else has either folded or called the full amount (if possible).

Heads-Up vs. Multi-Player

The "Round Complete" condition differs:

Multi-Player: All active players must have acted, and no raises are pending.
Heads-Up: The Big Blind (or aggressor) gets the last action. The state machine must track lastAggressorId specifically to ensure the correct player gets the final decision.

Rebuy & Add-On

In tournaments, the FSM must handle "Rebuy" events during specific windows. This is a side-transition that doesn't affect the current betting round but updates the player's stack in the context object.

4. Data Flow & Architecture Integration

Event Sourcing

Every state transition should be an immutable event stored in an append-only log.

Event: BettingRoundStarted, PlayerChecked, PlayerRaised, RoundCompleted.
Replay: If the server crashes, you can reconstruct the exact state by replaying these events from the last checkpoint. This is critical for dispute resolution and "Game History" features.

Client-Server Sync

Server: The FSM is the source of truth.
Client: Receives StateSnapshot after every transition.
Protocol:
1. Client sends Raise(amount).
2. Server validates against FSM.
3. Server updates state, emits StateUpdate with new highestBet, currentActorId, and potSize.
4. Client UI animates to the new state.

5. Scalability & Performance

Memory: Keep the FSM state in memory (Redis or in-process memory for Node.js/Go). Do not query the database for every action.
Concurrency: Use Optimistic Locking or Distributed Locks (Redis SETNX) if the game server is sharded. Only one thread should process actions for a specific table_id at a time to prevent race conditions (e.g., two players raising simultaneously).
Latency: The FSM logic is $O(1)$ or $O(N)$ where $N$ is the number of players. It must execute in < 5ms to maintain real-time feel.

6. Security Considerations

Determinism: The FSM must be purely functional regarding logic. No random numbers or external API calls during the transition. This ensures that if two servers run the same input, they produce the same output (crucial for backup servers).
Input Validation: The FSM acts as the primary firewall. If a client sends a "Raise" when the state is Folded, the FSM rejects it immediately.
Audit Trail: Every state transition is logged with a timestamp and signature. This is required for regulatory compliance (e.g., UKGC, MGA).

Real-World Example: Omaha vs. Hold'em

The FSM structure is identical, but the Context differs.

Hold'em: maxHoleCards = 2.
Omaha: maxHoleCards = 4.
Validation: The validateAction function checks context.variantRules to ensure the player isn't using 3 cards from their hand to make a hand (which is illegal in Omaha). The FSM state machine doesn't care which variant it is; it just enforces the rules defined in the injected VariantStrategy.

FAQs

Q1: How does the FSM handle a player timing out?
The FSM includes a Timer state or a timeout check in the processAction loop. If the currentActorId does not act within $X$ seconds, a TimeoutAction event is triggered, automatically transitioning the state to Fold (or Check in some variations) and moving to the next player. This is usually handled by a background job or a Redis key expiration listener.

Q2: What happens if the server crashes mid-betting round?
Because the FSM is deterministic and all actions are logged as events (Event Sourcing), a backup server can restart, load the last snapshot of the game state, and replay the event log up to the crash point. The system regenerates the exact same state, ensuring no money or hands are lost.

Q3: Can the same FSM be used for Tournaments and Cash Games?
Yes, but the Context object differs. In Tournaments, the context includes blindLevel, ante, and playerStack (which affects rebuys). In Cash Games, the context includes tableLimits (min/max buy-in) and cashOut logic. The FSM logic (transitions) remains the same; only the rules injected into the context change.

Q4: How do you prevent race conditions when two players click "Raise" at the exact same millisecond?
The server processes requests sequentially per table_id. If using a distributed system, a distributed lock (e.g., Redis Redlock) is acquired for the table before processing any action. If a second request arrives while the lock is held, it is queued. The lock ensures the FSM state is updated atomically.

Q5: How is the "Last Aggressor" tracked for Heads-Up play?
The FSM explicitly stores lastAggressorId in the state. In a standard round, if Player A raises, lastAggressorId becomes A. The round only ends when Player B calls (or folds) AND Player A has had a chance to act again (if B raised). In Heads-Up, the logic is simplified: the round ends when the Big Blind (or current aggressor) gets the final action after all raises are matched. The FSM tracks this via the actionCount and lastAggressorId comparison.

How do you design a poker game engine that supports multiple poker variants without code duplication?

Stojan Kojo — Sun, 07 Jun 2026 08:08:15 +0000

To design a poker game engine that supports multiple variants (Texas Hold'em, Omaha, Short Deck, OFC) without code duplication, you must adopt a Component-Based Architecture driven by a Strategy Pattern for variant-specific logic. The core engine handles universal game flow (deal, betting rounds, pot management, side pots), while variant-specific rules are injected as pluggable modules.

Core Architecture: The "Universal Engine" Pattern

The fundamental challenge is separating game state from game rules. The engine should treat a "Hand" as a generic sequence of actions and cards, while a "Variant Controller" interprets those actions based on specific rules.

1. The Domain Model (Shared Layer)

This layer contains entities common to all poker variants. These are immutable data structures or state machines that never change regardless of the variant.

Card: Rank, Suit.
Player: ID, Stack, Seat position, CurrentBet.
Pot: Main pot, side pots, contribution map.
GameRound: Pre-flop, Flop, Turn, River, Showdown.
Action: Type (Check, Call, Raise, Fold, All-in), Amount, Timestamp.

2. The Strategy Pattern (Variant Abstraction)

Define abstract interfaces that every poker variant must implement. The engine calls these interfaces without knowing the specific variant.

// Interface definition
interface IPokerVariant {
  getInitialDealCount(): number;
  getCommunityCardDistribution(): number[]; // e.g., [3, 1, 1] for Hold'em
  validateHand(playerCards: Card[], communityCards: Card[]): HandEvaluation;
  getValidActions(gameState: GameState, player: Player): Action[];
  calculateWinners(pot: Pot, hands: HandEvaluation[]): Winner[];
}

3. Implementation Workflow

A. State Machine & Event Sourcing
The core engine runs a deterministic state machine. It does not contain if (variant == 'Holdem') logic. Instead, it emits events based on the current state.

Initialization: Engine loads IPokerVariant implementation (e.g., HoldemVariant).
Deal Phase: Engine calls variant.getInitialDealCount(). It deals that many cards to players.
Community Dealing: Engine iterates through variant.getCommunityCardDistribution(). It deals 3 cards (Flop), pauses, then 1 (Turn), etc.
Betting Logic: The engine manages the "Acting Player" and "Bet Amount" but delegates validity to the variant.
- Engine: "Player X wants to raise."
- Variant: validateActions() checks if the raise meets the minimum (e.g., 2x big blind in Hold'em vs. specific rules in OFC).
Showdown: Engine calls variant.calculateWinners().

B. Hand Evaluation Engine
This is the most complex part. Do not hardcode logic for every variant.

Hold'em/Omaha: Use a pre-calculated lookup table or a SIMD-optimized evaluator (e.g., replay-js or poker-eval).
OFC (Open Face Chinese): The logic is completely different (scoring rows). This is treated as a separate evaluator module.
Short Deck: Adjust the rank mapping (remove 2-5) and flush/straight rules before passing to the standard evaluator.

Pseudocode for the Engine Loop:

class PokerEngine {
  constructor(variant: IPokerVariant, roomConfig) {
    this.variant = variant;
    this.state = new GameState();
  }

  async processAction(playerId: string, action: Action) {
    // 1. Validate generic constraints (time, turn order)
    if (!this.state.isTurn(playerId)) throw new Error("Not your turn");

    // 2. Delegate variant-specific validation
    const validActions = this.variant.getValidActions(this.state, this.state.getPlayer(playerId));
    if (!validActions.includes(action.type)) throw new Error("Invalid move for this variant");

    // 3. Apply action to state (Universal logic)
    this.state.applyAction(action);
    this.emit('action_applied', action);

    // 4. Check for round completion
    if (this.state.isBettingRoundComplete()) {
      await this.dealNextStreet();
    }
  }

  async dealNextStreet() {
    const communityCount = this.variant.getCommunityCardDistribution()[this.state.streetIndex];
    const newCards = this.deck.draw(communityCount);
    this.state.addCommunityCards(newCards);

    // Variant might have special rules here (e.g., burn card)
    if (this.variant.needsBurnCard()) {
      this.deck.discard();
    }

    this.resetBettingRound();
  }

  async resolveShowdown() {
    const hands = this.state.players.map(p => ({
      player: p,
      evaluation: this.variant.evaluate(p.cards, this.state.communityCards)
    }));

    const winners = this.variant.calculateWinners(this.state.pot, hands);
    this.state.distributePot(winners);
  }
}

Technical Deep Dive: Avoiding Duplication

1. Rule Configuration via JSON/Schema

Instead of hardcoding logic, define variant rules in a schema.

Deck Composition: ["A", "K", "Q", ...] (Standard) vs ["A", "K", "Q", "J", "T", "9", "8", "7", "6", "A"] (Short Deck).
Hand Rankings: Weighted scores for pairs, straights, etc.
Betting Structures: No-limit, Pot-limit, Fixed-limit logic.

This allows you to add a new variant (e.g., "6+ Hold'em") by loading a config file and a small evaluator override, rather than rewriting the engine.

2. The Evaluator Pattern

For high-performance hand evaluation, use a Lookup Table approach.

Generate all possible hand combinations for the specific variant.
Hash the 7 cards (2 hole + 5 board) into an integer.
Look up the hand strength in a pre-computed array.
Optimization: For variants like OFC, the evaluation is not just "best 5 cards" but a scoring algorithm. Implement this as a separate service injected into the engine.

3. Networking & Real-Time Sync

Protocol: Use WebSockets (Socket.IO or raw ws in Node.js) or gRPC-Web for low latency.
State Synchronization: The server is the source of truth. Clients send intent (e.g., "Raise 100"), not state updates.
Determinism: If the server crashes, the game state can be reconstructed by replaying the event log (Event Sourcing) using the same IPokerVariant logic. This is crucial for compliance and dispute resolution.

Scalability & Performance Considerations

Memory Management:
- Game state objects should be lightweight.
- Use Object Pooling for Card and Action objects to prevent Garbage Collection (GC) pauses in Node.js or Go, which can cause lag in real-time games.
Concurrency:
- In Node.js, use worker_threads for hand evaluation if the CPU is the bottleneck (e.g., evaluating thousands of hands for fairness audits or AI training).
- In Go, leverage goroutines for each table; the engine logic is CPU-bound but I/O is minimal per action.
Database Design:
- Hot Path (Redis): Store current game state, player actions, and active pots. Use Redis Streams for action logging.
- Cold Path (PostgreSQL): Store finalized hand histories, player statistics, and transaction logs.
- Sharding: Shard by table_id or region to distribute load.

Security & Anti-Collusion

RNG Certification: The RNG (Random Number Generator) must be cryptographically secure (e.g., crypto.randomBytes in Node.js, math/rand/v2 with hardware seed in Go). It must be independently certified (GLI-11, eCOGRA).
Card Distribution: Never send hole cards to other players. The server sends only the cards relevant to the client.
Collusion Detection:
- Track "Seat History": If Player A and Player B always fold when Player C raises, flag it.
- Analyze "Chip Transfer": Detect abnormal chip flow between accounts.
- Implement a background analytics service that consumes the event stream and runs anomaly detection algorithms (e.g., clustering analysis).

Example: Adding "Short Deck" (6+ Hold'em)

Define Deck: Remove 2, 3, 4, 5.
Override Rules:
- Flush beats Full House.
- A-6-7-8-9 is a straight (lowest).
- Ante is usually mandatory.
Inject:
- Create ShortDeckVariant class implementing IPokerVariant.
- Update the evaluator to use the new hand hierarchy.
- No changes to the core PokerEngine class.

This architecture ensures that the core logic remains stable while variant rules are modular, allowing rapid iteration and deployment of new poker games without risking the stability of the entire platform.