Porting Plan — Java Supersonic → Rust holdem_bots Comprehensive porting plan covering recommended bots, folder structure, TOML-based assembly, implementation phases, and dependency graph. --- ## Part A: Strategy Components per Game Type — All Generations ### A.1 Multi-Generation Strategy Matrix Each game type needs **at least one strategy component from every applicable generation**. This enables cross-generational simulation testing (e.g., Gen 4 vs Gen 1, Gen 3 vs Gen 2). | Game Type | Gen 1 (Static) | Gen 2 (Mathematical) | Gen 3 (Nash/ICM) | Gen 4 (Opponent Modelling) | |-----------|---------------|---------------------|-------------------|---------------------------| | Cash NL 10-max | `BigStackBot` + `ShortStackBot` (already ported) | `RingNLStrategyV1` (EHS postflop) | N/A for cash | N/A for cash | | Cash NL 6-max | `BigStackBot` + `ShortStackBot` (same, adjusted thresholds) | `RingNLStrategyV1` (looser ranges) | N/A | N/A | | Cash FL 10-max | N/A (no static FL bot exists) | `RingFLStrategyV1` | N/A for cash | N/A for cash | | Cash FL 6-max | N/A | `RingFLStrategyV1` (looser ranges) | N/A | N/A | | SNG NL 10-max | `SimpleBot` / `KillSimple` (test baselines) | `PostFlopEHSStrategy` (PSim) | `ModNashICMv7` + `PushOrFold` | `CustomModNGV2` | | SNG NL 6-max | Same baselines | `PostFlopEHSStrategy` | `ModNashICMv7_6max` | `CustomModNGV2` (6-max) | | MTT NL | `SimpleBot` baseline | `PostFlopEHSStrategy` | `ModNashICMv7` + `PushOrFold` | `CustomModNGV2` | | HU NL | `AlwaysCall`/`AlwaysFold` (baselines) | `PostFlopEHSStrategy` (HU mode) | `KEHU20BBNeqV3` + `EGHUPreFlopV8` | `NGHUPostFlopStrategyV2` | ### A.2 Generation Purpose | Generation | Role | Use Case | |-----------|------|----------| | **Gen 1 (Static)** | Baseline opponent | Simple, predictable play. Good for measuring minimum bot quality. Also useful as "fish" opponents. | | **Gen 2 (Mathematical)** | Intermediate test | EHS-based decisions with `HandPotential`. Tests whether a bot can beat mathematically sound play. | | **Gen 3 (Nash/ICM)** | Advanced bot | Game-theoretic optimal play in endgame situations. The benchmark for tournament strategies. | | **Gen 4 (Opponent Modelling)** | Best overall | Adapts to opponents in real-time. Should beat all prior generations by exploiting tendencies. | ### A.3 Current Capability Matrix | Game Type | Gen 1 (Static) | Gen 2 (EHS) | Gen 3 (Nash/ICM) | Gen 4 (OppModel) | |-----------|:-:|:-:|:-:|:-:| | Cash NL 10-max | ✅ Ported | ❌ Not ported | N/A | N/A | | Cash NL 6-max | ✅ Ported | ❌ Not ported | N/A | N/A | | Cash FL 10-max | N/A | ❌ Not ported | N/A | N/A | | Cash FL 6-max | N/A | ❌ Not ported | N/A | N/A | | SNG NL 10-max | ❌ Not ported | ❌ Not ported | ❌ Not ported | ❌ Not ported | | SNG NL 6-max | ❌ Not ported | ❌ Not ported | ❌ Not ported | ❌ Not ported | | MTT NL | ❌ Not ported | ❌ Not ported | ❌ Not ported | ❌ Not ported | | HU NL | ❌ Not ported | ❌ Not ported | ❌ Not ported | ❌ Not ported | --- ## Part B: Proposed Folder Structure ### B.1 Source Code Structure ``` holdem_bots/src/ ├── lib.rs # Crate root — registers all bot types ├── strategy_bot.rs # StrategyBot adapter (HoldemPlayer → Strategy) │ ├── common/ # Framework utilities (EXISTING) │ ├── mod.rs # Re-exports: Strategy, ModularStrategy, etc. │ ├── modular.rs # Strategy trait, ModularStrategy, VotingMode │ ├── context.rs # StrategyContext — game state snapshot │ ├── action_recorder.rs # ActionRecorder — per-hand action history │ ├── hand_analyzer.rs # HandAnalyzer — hand evaluation utilities │ ├── hand_helper.rs # HandHelper — board texture, hand categorization │ └── hand_potential.rs # HandPotential — ppot/npot/nutpot/rpot/EHS │ ├── cash/ # Cash game strategies (EXISTING, needs expansion) │ ├── mod.rs # Re-exports: BigStackBot, ShortStackBot, etc. │ ├── big_stack.rs # BigStackBot (Gen 1, stack > 25 BB) │ ├── big_stack_preflop.rs # BigStackPreFlop — hand grouping preflop │ ├── short_stack.rs # ShortStackBot (Gen 1, stack ≤ 25 BB) │ ├── short_stack_preflop.rs # ShortStackPreFlop — push/fold preflop │ ├── postflop.rs # PostFlopStrategy — shared postflop (needs EHS upgrade) │ ├── nl.rs # [NEW] RingNLCash — Gen 2 EHS-based NL cash bot │ ├── fl.rs # [NEW] RingFLCash — Gen 2 FL cash bot │ └── thresholds.rs # [NEW] Cash threshold configuration structs │ ├── sng/ # [NEW] SNG strategies │ ├── mod.rs # Re-exports: SngBot, etc. │ ├── bot.rs # SngBot — composition root for SNG │ ├── preflop.rs # SNG-specific preflop (ICM-aware ranges) │ ├── postflop.rs # SNG-specific postflop (ICM-adjusted EHS) │ └── push_fold.rs # Push/fold chart strategy │ ├── mtt/ # [NEW] MTT strategies │ ├── mod.rs # Re-exports: MttBot, etc. │ ├── bot.rs # MttBot — composition root for MTT │ ├── preflop.rs # MTT-specific preflop (bubble-aware) │ └── postflop.rs # MTT-specific postflop │ ├── hu/ # [NEW] Heads-up strategies │ ├── mod.rs # Re-exports: HuBot, etc. │ ├── bot.rs # HuBot — composition root for HU │ ├── nash_tables.rs # Precomputed Nash equilibrium tables (20BB/15BB) │ ├── preflop.rs # HU preflop (Nash + profiling) │ └── postflop.rs # HU postflop (simplified, aggressive) │ ├── nash/ # [NEW] Nash equilibrium solver │ ├── mod.rs # Re-exports: NashSolver, etc. │ ├── solver.rs # Iterative best-response Nash solver │ └── push_fold_range.rs # Push/fold range computation │ ├── icm/ # [NEW] ICM equity calculator │ ├── mod.rs # Re-exports: IcmCalculator, etc. │ ├── calculator.rs # ICM equity computation (recursive) │ └── bubble_factor.rs # Bubble factor calculation │ ├── opponent/ # [NEW] Opponent modelling │ ├── mod.rs # Re-exports: PlayerModel, RangePredictor, etc. │ ├── player_model.rs # In-memory opponent statistics tracker │ ├── stats.rs # OpponentStats struct (VPIP, PFR, AF, etc.) │ ├── range_predictor.rs # Opponent range prediction from actions │ └── hand_range.rs # Weighted hand range representation │ ├── deception/ # [NEW] Bluff and lure modules │ ├── mod.rs # Re-exports │ ├── bluff.rs # Semi-bluff, continuation bluff │ └── lure.rs # Trap/slowplay, induce bets │ ├── assembly/ # [NEW] TOML-driven strategy assembly │ ├── mod.rs # Re-exports: StrategyFactory, etc. │ ├── factory.rs # StrategyFactory — reads TOML, assembles ModularStrategy │ ├── registry.rs # StrategyRegistry — maps type names → constructors │ └── config.rs # Config structs (BotConfig, StrategyConfig, etc.) │ ├── baseline/ # [NEW] Baseline/test opponents (Gen 1) │ ├── mod.rs # Re-exports │ ├── simple_bot.rs # SimpleBot — basic ABC poker │ ├── kill_simple.rs # KillSimple — slightly smarter baseline │ ├── always_call.rs # AlwaysCall — calls every bet │ └── always_fold.rs # AlwaysFold — folds every hand (except free checks) │ └── data/ # [NEW] Embedded data files ├── mod.rs # Re-exports ├── hu_nash_20bb.rs # include_str!("../../configs/data/hu_nash_20bb.csv") ├── hu_nash_15bb.rs # include_str!("../../configs/data/hu_nash_15bb.csv") └── push_fold_charts.rs # Compiled push/fold chart data ``` ### B.2 Configuration File Structure ``` configs/ ├── bots/ # Bot assembly configurations ├── strategies/ # Strategy component configurations ├── thresholds/ # Threshold configuration files └── data/ # Precomputed data files ``` --- ## Part C: TOML-Based Strategy Assembly Design ### C.1 Bot Assembly Config Schema (`configs/bots/*.toml`) ```toml [bot] name = "sng_gen3_nash" description = "SNG bot with Nash/ICM endgame (Gen 3)" voting_mode = "first_applicable" game_type_filter = "sng" table_size = { min = 2, max = 10 } [[strategies]] type = "steal_from_inactive" enabled = true [[strategies]] type = "fold_micro_stack" config = { threshold_bb = 2.0 } enabled = true [[strategies]] type = "nash_icm" config = "configs/strategies/nash_icm.toml" enabled = true ``` ### C.2 Strategy Factory Architecture StrategyFactory → StrategyRegistry → lookup type name → constructor → ModularStrategy → StrategyBot ### C.3 Rust Implementation Sketch ```rust #[derive(Debug, Deserialize)] pub struct BotConfig { pub bot: BotInfo, pub strategies: Vec, } #[derive(Debug, Deserialize)] pub struct StrategyEntry { pub r#type: String, pub config: Option, pub enabled: Option, } ``` --- ## Part D: Implementation Phases | Phase | Description | Effort | Dependencies | |-------|-------------|--------|-------------| | 1 | TOML Strategy Assembly Framework | 3–5 days | None | | 2 | Port Existing Cash to TOML | 2–3 days | Phase 1 | | 3 | Cash NL Gen 2 (EHS PostFlop) | 1–2 days | Phase 2 | | 4 | SNG Endgame — Nash/ICM (Gen 3) | 5–7 days | Phase 1, 3 | | 5 | HU Strategy (Gen 3) | 3–5 days | Phase 1 | | 6 | SNG/MTT Gen 1+2 Baselines | 2–3 days | Phase 3 | | 7 | FL Cash (Gen 2) | 2–3 days | Phase 3 | | 8 | Opponent Modelling (Gen 4) | 5–7 days | Phase 3 | | 9 | Full Composition Bots (Gen 4) | 7–10 days | All prior | **Critical path:** Phase 1 → 2 → 3 → 4 → 8 → 9 **Parallel tracks after Phase 3:** - Track A: Phase 4 (SNG Nash/ICM) — on critical path - Track B: Phase 5 (HU Strategy) — can start after Phase 1 - Track C: Phase 6 (SNG/MTT Baselines) — can start after Phase 3 - Track D: Phase 7 (FL Cash) — can start after Phase 3 - Track E: Phase 8 (Opponent Modelling) — can start after Phase 3 - Phase 9 requires all prior phases --- ## Part E: Simulation Matrix Cross-generational testing ensures each new generation is strictly better than the last. - **Cash NL:** Gen 2 should show statistically significant edge over Gen 1 over 10K+ hands - **SNG NL:** Each generation should beat previous by significant margin over 1K+ tournaments - **HU NL:** Gen 3 (Nash) beats Gen 2 (EHS) beats Gen 1 (always_call) - **Sanity checks:** Strategies should perform poorly outside their game type --- ## Appendix: Cargo.toml Dependencies ```toml [dependencies] holdem_core = { path = "../holdem_core" } rand = "0.8" rayon = "1.8" serde = { version = "1", features = ["derive"] } # NEW toml = "0.8" # NEW csv = "1.3" # NEW ``` id: fd14e517692c4f2e88dfecb2c8625e8f parent_id: 2c8da247905946c3aa19eb4936e16323 created_time: 2026-05-31T10:36:57.205Z updated_time: 2026-05-31T10:54:50.073Z is_conflict: 0 latitude: 0.00000000 longitude: 0.00000000 altitude: 0.0000 author: source_url: is_todo: 0 todo_due: 0 todo_completed: 0 source: joplin-desktop source_application: net.cozic.joplin-desktop application_data: order: 1780223817205 user_created_time: 2026-05-31T10:36:57.205Z user_updated_time: 2026-05-31T10:54:50.073Z encryption_cipher_text: encryption_applied: 0 markup_language: 1 is_shared: 0 share_id: conflict_original_id: master_key_id: user_data: deleted_time: 0 type_: 1