strat-gameplay-webapp/.claude/implementation/03-gameplay-features.md

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 - Component structure
• WebSocket Protocol - All event types
• PRD Lines 186-276 - 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