AI Opponents

Relevant source files

The following files were used as context for generating this wiki page:

• hooks/use-ai-opponents.tsx
• hooks/use-poker-game.tsx
• lib/poker-engine.ts
• hooks/use-chat.tsx
• hooks/use-webrtc.tsx
• components/poker-table.tsx

The AI Opponents system provides automated, computer-controlled players to participate in poker games. Its primary purpose is to fill empty seats at a table, allowing a game to proceed even without a full roster of human players. The AI's behavior is managed by the useAIOpponents hook, which observes the game state and triggers actions for non-human players when it is their turn.

The current implementation features a simplistic, rule-based decision-making process that varies based on the game mode. The AI simulates player actions and communicates these actions through the in-game chat system to create a more immersive experience.

Architecture

The AI Opponent system is primarily driven by the useAIOpponents custom hook. This hook acts as a controller that subscribes to game state changes and interacts with other core systems to execute an AI player's turn.

The following diagram illustrates the high-level interaction between the AI hook and other parts of the application.

Key Components

Component	File	Description
useAIOpponents	hooks/use-ai-opponents.tsx	The central hook that contains the AI's decision-making logic. It observes the game and acts on behalf of AI players.
usePokerGame	hooks/use-poker-game.tsx	Provides the current gameState to the AI and exposes the makeAction function for the AI to submit its chosen move.
poker-engine.ts	lib/poker-engine.ts	Contains the processAction function, which validates and applies the AI's action to the game state.
useChat	hooks/use-chat.tsx	Used by the AI to send chat messages announcing its actions (e.g., "Fold", "Raise to $50").
useWebRTC	hooks/use-webrtc.tsx	Provides player information, such as names, which the AI uses for sending chat messages.

Sources: hooks/use-ai-opponents.tsx:9, hooks/use-poker-game.tsx:8, lib/poker-engine.ts:468, hooks/use-chat.tsx:7, hooks/use-webrtc.tsx:6

AI Turn Lifecycle

The AI's turn is initiated within a useEffect hook inside useAIOpponents. This effect is triggered whenever the gameState changes.

The sequence diagram below shows the flow of events from a game state update to the completion of an AI's action.

Sources: hooks/use-ai-opponents.tsx:12-92

1. The useEffect in useAIOpponents runs on every gameState change.
2. It checks if the currentPlayer is an AI (i.e., id is not "local").
3. A random delay between 1 and 3 seconds is initiated to simulate thinking time.
4. After the delay, the AI executes its decision logic based on the gameMode.
5. The AI announces its action by calling sendMessage from the useChat hook.
6. The AI performs its action by calling makeAction from the usePokerGame hook.
7. makeAction internally calls processAction in the poker-engine to update the state, which triggers the cycle again for the next player.

Sources: hooks/use-ai-opponents.tsx:12-21

Decision-Making Logic

The AI's logic is determined by the gameMode property within the gameState. The logic is intentionally simple and heavily reliant on random probabilities.

Sources: hooks/use-ai-opponents.tsx:29, components/poker-table.tsx:61

"All-in or Fold" Mode

In "All-in or Fold" mode, the AI's decision tree is binary. This mode is identified when gameState.gameMode === "allin".

Sources: hooks/use-ai-opponents.tsx:29-41

• All-in: 60% probability.
• Fold: 40% probability.

The AI is intentionally more aggressive in this mode.

Regular Game Modes

For other game modes (e.g., "sng", "omaha"), the logic is more nuanced but still based on Math.random(). It considers the amount to call and the player's chip stack.

Sources: hooks/use-ai-opponents.tsx:44-90

Scenarios and Probabilities

Scenario	Condition	Action	Probability	Source Lines
No bet to call	amountToCall === 0	raise	30%	hooks/use-ai-opponents.tsx:57-61
		check	70%	hooks/use-ai-opponents.tsx:62-66
Must go all-in or fold	amountToCall >= chips	all-in	30%	hooks/use-ai-opponents.tsx:69-72
		fold	70%	hooks/use-ai-opponents.tsx:73-76
Normal betting round	potOdds > 0.4 or random < 0.2	fold	~20% + pot odds condition	hooks/use-ai-opponents.tsx:80-83
	random < 0.5	call	30% (of remaining 80%)	hooks/use-ai-opponents.tsx:84-86
	random < 0.8	raise	30% (of remaining 80%)	hooks/use-ai-opponents.tsx:87-89
	(else)	all-in	20% (of remaining 80%)	hooks/use-ai-opponents.tsx:90-92

Note: The potOdds calculation is a simple ratio: amountToCall / (gameState.pot + amountToCall). The AI folds if the pot odds are greater than 40%, indicating a potentially poor risk/reward ratio.

Sources: hooks/use-ai-opponents.tsx:26-27, hooks/use-ai-opponents.tsx:78-92