strat-gameplay-webapp/.claude/implementation/02-game-engine.md

Phase 2: Game Engine Core

Duration: Weeks 4-6 Status: Not Started Prerequisites: Phase 1 Complete

---

Overview

Build the core game simulation engine with in-memory state management, play resolution logic, and database persistence. Implement the polymorphic player model system and league configuration framework.

Key Objectives

By end of Phase 2, you should have:

• ✅ In-memory game state management working
• ✅ Play resolution engine with dice rolls
• ✅ League configuration system (SBA and PD configs)
• ✅ Polymorphic player models (BasePlayer, SbaPlayer, PdPlayer)
• ✅ Database persistence layer with async operations
• ✅ State recovery mechanism from database
• ✅ Basic game flow (start → plays → end)

Major Components to Implement

1. Game Engine (backend/app/core/game_engine.py)

• Game session initialization
• Turn management (defensive → stolen base → offensive → resolution)
• Action processing and validation
• State update coordination
• Event emission to WebSocket clients

2. State Manager (backend/app/core/state_manager.py)

• In-memory game state dictionary
• State CRUD operations
• State lifecycle management
• Cache eviction for idle games
• State recovery from database

3. Play Resolver (backend/app/core/play_resolver.py)

• Cryptographic dice rolling
• Result chart lookup (league-specific)
• Play outcome determination
• Runner advancement logic
• Score calculation

4. Dice System (backend/app/core/dice.py)

• Secure random number generation
• Roll logging and verification
• Distribution testing

5. Polymorphic Player Models (backend/app/models/player_models.py)

• BasePlayer abstract class
• SbaPlayer implementation
• PdPlayer implementation
• Lineup factory method
• Type guards for league-specific logic

6. League Configuration (backend/app/config/)

• BaseGameConfig class
• SbaConfig and PdConfig subclasses
• Result charts (d20 tables) for each league
• Config loader and versioning
• Config validation

7. Database Operations (backend/app/database/operations.py)

• Async play persistence
• Game metadata updates
• Lineup operations
• State snapshot management
• Bulk recovery queries

8. API Client (backend/app/data/api_client.py)

• HTTP client for league REST APIs
• Team data fetching
• Roster data fetching
• Player/card data fetching
• Error handling and retries
• Response caching (optional)

Implementation Order

1. Week 4: State Manager + Database Operations

   • In-memory state structure
   • Basic CRUD operations
   • Database persistence layer
   • State recovery mechanism

2. Week 5: Game Engine + Play Resolver

   • Game initialization flow
   • Turn management
   • Dice rolling system
   • Basic play resolution (simplified charts)

3. Week 6: League Configs + Player Models

   • Polymorphic player architecture
   • League configuration system
   • Complete result charts
   • API client integration
   • End-to-end testing

Testing Strategy

Unit Tests

• State manager operations
• Dice roll distribution
• Play resolver outcomes
• Player model instantiation
• Config loading

Integration Tests

• Full game flow from start to end
• State recovery from database
• Multi-turn sequences
• API client with mocked responses

E2E Tests

• Play a complete 9-inning game
• Verify database persistence
• Test state recovery mid-game

Key Files to Create

backend/app/
├── core/
│   ├── game_engine.py       # Main game logic
│   ├── state_manager.py     # In-memory state
│   ├── play_resolver.py     # Play outcomes
│   ├── dice.py              # Random generation
│   └── validators.py        # Rule validation
├── config/
│   ├── base_config.py       # Base configuration
│   ├── league_configs.py    # SBA/PD configs
│   ├── result_charts.py     # d20 tables
│   └── loader.py            # Config utilities
├── models/
│   ├── player_models.py     # Polymorphic players
│   └── game_models.py       # Pydantic game models
└── data/
    └── api_client.py        # League API client

Reference Documents

• Backend Architecture - Complete backend structure
• Database Design - Schema and queries
• WebSocket Protocol - Event specifications
• PRD Lines 378-551 - Polymorphic player architecture
• PRD Lines 780-846 - League configuration system

Deliverable

A working game backend that can:

• Initialize a game with teams from league APIs
• Process a complete at-bat (decisions → dice roll → outcome)
• Update game state in memory and persist to database
• Recover game state after backend restart
• Handle basic substitutions

Notes

• Focus on getting one at-bat working perfectly before expanding
• Test dice roll distribution extensively
• Validate all state transitions
• Use simplified result charts initially, expand in Phase 3
• Don't implement UI yet - test via WebSocket events or Python scripts

---

Implementation Approach

Key Decisions (2025-10-22)

1. Development Order: SBA First → PD Second

   • Build each component for SBA league first
   • Learn lessons and apply to PD implementation
   • Ensures simpler case works before tackling complexity

2. Testing Strategy: Automated Python Tests

   • Unit tests for each component
   • Integration tests for full workflows
   • No WebSocket UI testing in Phase 2
   • Python scripts to simulate game flows

3. Result Selection Models:

   • SBA: Players see dice roll, then select outcome from available results
   • PD: Flexible approach
     • Human players can manually select results
     • AI/Auto mode uses scouting model to determine results automatically
   • Initial implementation uses placeholder/simplified charts

4. Build Philosophy: One Perfect At-Bat

   • Focus on completing a single defensive decision → dice roll → offensive decision → resolution flow
   • Validate all state transitions work correctly
   • Expand features in Phase 3

Detailed Weekly Plans

Detailed implementation instructions for each week:

• Week 4: State Management & Persistence
• Week 5: Game Logic & Play Resolution
• Week 6: League Features & Integration

---

Status: In Progress - Planning Complete (2025-10-22) Next Phase: 03-gameplay-features.md