# Phase 3: Complete Game Features

**Duration**: Weeks 7-9
**Status**: Not Started
**Prerequisites**: Phase 2 Complete

---

## Overview

Implement all strategic decisions, complete result charts for both leagues, substitution system, pitching changes, AI opponent, and async game mode support. Complete the frontend game interface.

## Key Objectives

By end of Phase 3, you should have:
- ✅ All strategic decision types implemented
- ✅ Complete substitution system (pinch hitters, defensive replacements)
- ✅ Pitching change logic with bullpen management
- ✅ Full result charts for both SBA and PD leagues
- ✅ AI opponent integration
- ✅ Async game mode with notifications
- ✅ Complete frontend game interface (mobile + desktop)
- ✅ Play-by-play history display
- ✅ Game creation and lobby UI

## Major Components to Implement

### Backend Features

#### 1. Strategic Decisions
- Defensive positioning (standard, infield in, shifts)
- Stolen base attempts (per runner)
- Offensive approach (swing away, bunt, hit-and-run)
- Intentional walk
- Defensive substitutions mid-inning

#### 2. Substitution System
- Pinch hitter logic
- Pinch runner logic
- Defensive replacement
- Double switches (if applicable)
- Validation (eligibility, roster constraints)
- Lineup reordering after substitution

#### 3. Pitching Changes
- Relief pitcher selection
- Pitcher eligibility validation
- Pitcher statistics tracking
- Mound visit limits (optional)
- Auto-pitcher fatigue (optional)

#### 4. Complete Result Charts
- SBA league d20 tables (all situations)
- PD league d20 tables (all situations)
- Hit location logic
- Runner advancement scenarios
- Fielding errors (if applicable)
- Extra-inning rules

#### 5. AI Opponent
- Integration with existing AI logic
- Decision-making algorithms
- Timing simulation (avoid instant responses)
- Difficulty levels (optional)
- AI substitution logic

#### 6. Async Game Mode
- Turn-based notification system
- Email/Discord notifications
- Turn timeout handling
- "Your turn" indicator
- Game pause/resume

### Frontend Features

#### 1. Game Creation Flow
- Team selection
- Opponent selection (human or AI)
- Game mode selection (live, async, vs AI)
- Visibility settings
- Lineup confirmation
- Game start

#### 2. Game Lobby
- Pre-game waiting room
- Lineup display for both teams
- Ready/not ready status
- Chat (optional)
- Countdown to start

#### 3. Game Interface (Mobile)
- Baseball diamond visualization
- Score display (by inning)
- Current situation (count, outs, runners)
- Decision cards (bottom sheet)
- Play-by-play feed (collapsible)
- Action buttons (substitutions, pitching change)

#### 4. Game Interface (Desktop)
- Two/three column layout
- Expanded play-by-play
- Statistics sidebar
- Hover states for additional info
- Keyboard shortcuts

#### 5. Decision Workflows
- Defensive positioning selector
- Stolen base attempt interface
- Offensive approach selector
- Substitution modal with roster
- Pitching change modal with bullpen

#### 6. Play-by-Play Display
- Scrollable history
- Play descriptions
- Score updates
- Substitution notifications
- Inning summaries

## Implementation Order

1. **Week 7**: Complete Backend Strategic Decisions
   - All decision types
   - Complete result charts
   - Validation logic
   - WebSocket handlers

2. **Week 8**: Substitutions + Frontend Game Interface
   - Substitution system (backend + frontend)
   - Pitching changes
   - Game interface UI (mobile-first)
   - Decision workflows

3. **Week 9**: AI + Async + Polish
   - AI opponent integration
   - Async game mode
   - Game creation + lobby UI
   - Play-by-play display
   - Integration testing

## Frontend Component Structure

```
shared-components/src/components/
├── Game/
│   ├── GameBoard.vue
│   ├── ScoreBoard.vue
│   ├── PlayByPlay.vue
│   ├── CurrentSituation.vue
│   └── BaseRunners.vue
├── Decisions/
│   ├── DefensivePositioning.vue
│   ├── StolenBaseAttempt.vue
│   ├── OffensiveApproach.vue
│   └── DecisionTimer.vue
├── Actions/
│   ├── SubstitutionModal.vue
│   ├── PitchingChange.vue
│   └── ActionButton.vue
└── Display/
    ├── PlayerCard.vue
    ├── DiceRoll.vue
    ├── PlayOutcome.vue
    └── ConnectionStatus.vue
```

## Testing Strategy

### Backend Tests
- Test all strategic decision combinations
- Validate substitution rules
- Test AI decision making
- Verify async turn handling

### Frontend Tests
- Component testing with Vitest
- Mobile responsiveness testing
- Decision workflow testing
- WebSocket event handling

### E2E Tests
- Complete game with all decision types
- Game with substitutions
- AI opponent game
- Async game (simulated)

## Key Files to Create

**Backend**:
- `backend/app/core/substitutions.py`
- `backend/app/core/ai_opponent.py`
- `backend/app/websocket/handlers.py` (expand)
- `backend/app/config/result_charts.py` (complete)

**Frontend**:
- All shared components listed above
- `frontend-{league}/pages/games/create.vue`
- `frontend-{league}/pages/games/[id].vue`
- `frontend-{league}/store/game.ts`
- `frontend-{league}/composables/useGameActions.ts`

## Reference Documents

- [Frontend Architecture](./frontend-architecture.md) - Component structure
- [WebSocket Protocol](./websocket-protocol.md) - All event types
- [PRD Lines 186-276](../prd-web-scorecard-1.1.md) - Strategic decisions and game modes

## Deliverable

A fully playable game system with:
- All strategic options available
- Complete substitution capabilities
- AI opponent functional
- Mobile and desktop UI complete
- Async game mode operational

## Notes

- Prioritize mobile UI - 60%+ of users will play on mobile
- Test result charts thoroughly for both leagues
- Validate all substitution rules against baseball logic
- AI should make "reasonable" decisions, not perfect ones
- Async notifications critical for user engagement

---

**Status**: Placeholder - to be expanded during implementation
**Next Phase**: [04-spectator-polish.md](./04-spectator-polish.md)