100 lines
3.7 KiB
Rust
100 lines
3.7 KiB
Rust
//! # Player Module
|
|
//!
|
|
//! This module defines the core `Player` trait that all poker bot implementations must
|
|
//! implement. The Player trait provides the interface between the poker game engine
|
|
//! and individual bot logic, enabling different AI strategies and human player interfaces.
|
|
//!
|
|
//! ## Player Trait Overview
|
|
//!
|
|
//! The `Player` trait defines the essential methods that a poker bot must implement:
|
|
//! - **Initialization**: Setup with preferences and game parameters
|
|
//! - **Hole Cards**: Receive private cards at the start of a hand
|
|
//! - **Action Selection**: Choose appropriate actions during betting rounds
|
|
//! - **Game Observation**: Receive information about game state changes
|
|
//!
|
|
//! ## Key Methods
|
|
//!
|
|
//! - `init()`: Initialize player with preferences and configuration
|
|
//! - `hole_cards()`: Receive private hole cards for the current hand
|
|
//! - `get_action()`: Return the player's chosen action when it's their turn
|
|
//! - GameObserver methods: Receive updates about game state and other players' actions
|
|
//!
|
|
//! ## Implementation Requirements
|
|
//!
|
|
//! Any struct implementing `Player` must:
|
|
//! - Handle initialization with arbitrary preferences
|
|
//! - Process hole cards correctly
|
|
//! - Return valid actions in `get_action()`
|
|
//! - Implement all `GameObserver` methods appropriately
|
|
//!
|
|
//! ## Examples
|
|
//!
|
|
//! ### Basic Player Implementation
|
|
//!
|
|
//! ```rust
|
|
//! use poker_api::api::player::Player;
|
|
//! use poker_api::api::action::{Action, ActionType};
|
|
//! use poker_api::api::card::Card;
|
|
//! use poker_api::api::game_observer::GameObserver;
|
|
//! use poker_api::api::preferences::Preferences;
|
|
//!
|
|
//! struct SimpleBot {
|
|
//! hole_cards: Option<(Card, Card)>,
|
|
//! }
|
|
//!
|
|
//! impl Player for SimpleBot {
|
|
//! fn init(&mut self, _prefs: Box<dyn Preferences>) {
|
|
//! // Initialize bot with preferences
|
|
//! }
|
|
//!
|
|
//! fn hole_cards(&mut self, c1: Card, c2: Card, _seat: usize) {
|
|
//! self.hole_cards = Some((c1, c2));
|
|
//! }
|
|
//!
|
|
//! fn get_action(&mut self) -> Action {
|
|
//! // Simple logic: always call if cards are good
|
|
//! Action::call_action(0.0)
|
|
//! }
|
|
//! }
|
|
//!
|
|
//! impl GameObserver for SimpleBot {
|
|
//! // Implement game observation methods...
|
|
//! # fn game_start(&mut self, _info: poker_api::api::game_info::GameInfo) {}
|
|
//! # fn game_end(&mut self) {}
|
|
//! # fn round_start(&mut self, _round: u8) {}
|
|
//! # fn round_end(&mut self) {}
|
|
//! # fn player_action(&mut self, _seat: usize, _action: Action) {}
|
|
//! # fn community_cards(&mut self, _cards: Vec<Card>) {}
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Design Decisions
|
|
//!
|
|
//! - **Trait-Based Design**: Enables polymorphism between different bot types
|
|
//! - **Event-Driven Architecture**: Players receive game state through observer pattern
|
|
//! - **Minimal Interface**: Core methods required for any poker bot implementation
|
|
//! - **Extensible Preferences**: Support for arbitrary bot configuration
|
|
//! - **Action-Based Decisions**: Players return complete action objects
|
|
//!
|
|
//! ## Performance Characteristics
|
|
//!
|
|
//! - **Memory**: Minimal trait object overhead
|
|
//! - **Method Calls**: O(1) trait method dispatch
|
|
//! - **State Management**: Player manages internal state as needed
|
|
//! - **Action Generation**: Variable time depending on bot complexity
|
|
|
|
use crate::api::action::Action;
|
|
use crate::api::card::Card;
|
|
use crate::api::game_observer::GameObserver;
|
|
use crate::api::preferences::Preferences;
|
|
|
|
pub trait Player: GameObserver {
|
|
/// Initialize your player from the given preferences.
|
|
fn init(&mut self, prefs: Box<dyn Preferences>);
|
|
|
|
/// Receive your hole cards.
|
|
fn hole_cards(&mut self, c1: Card, c2: Card, seat: usize);
|
|
|
|
/// Requests an Action from the player. Called when it is the Player's turn to act.
|
|
fn get_action(&mut self) -> Action;
|
|
}
|