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](./backend-architecture.md) - Complete backend structure
- [Database Design](./database-design.md) - Schema and queries
- [WebSocket Protocol](./websocket-protocol.md) - Event specifications
- [PRD Lines 378-551](../prd-web-scorecard-1.1.md) - Polymorphic player architecture
- [PRD Lines 780-846](../prd-web-scorecard-1.1.md) - 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](./02-week4-state-management.md)
- [Week 5: Game Logic & Play Resolution](./02-week5-game-logic.md)
- [Week 6: League Features & Integration](./02-week6-league-features.md)

---

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