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

---

**Status**: Placeholder - to be expanded during implementation
**Next Phase**: [03-gameplay-features.md](./03-gameplay-features.md)