major-domo-v2/commands/gameplay/CLAUDE.md

Gameplay Commands

This directory contains Discord slash commands for live game tracking and scorecard management during gameplay.

Files

scorebug.py

• Commands:
  • /publish-scorecard <url> - Link a Google Sheets scorecard to a channel for live tracking
  • /scorebug [full_length] - Display the current scorebug from the published scorecard
• Description: Main command implementation for scorebug display and management
• Service Dependencies:
  • ScorebugService - Reading live game data from Google Sheets
  • team_service.get_team() - Team information lookup
• Tracker Dependencies:
  • ScorecardTracker - JSON-based persistent storage of scorecard-channel mappings

scorecard_tracker.py

• Class: ScorecardTracker
• Description: JSON-based persistent tracking of published scorecards
• Features:
  • Maps Discord text channels to Google Sheets URLs
  • Persistent storage across bot restarts
  • Automatic stale entry cleanup
  • Timestamp tracking for monitoring

__init__.py

• Function: setup_gameplay(bot)
• Description: Package initialization with resilient cog loading
• Integration: Follows established bot architecture patterns

Background Integration

Live Scorebug Tracker Task

File: tasks/live_scorebug_tracker.py

Schedule: Every 3 minutes

Operations:

1. Update #live-sba-scores Channel

   • Reads all published scorecards from tracker
   • Generates compact scorebug embeds for active games
   • Clears old messages and posts fresh scorebugs
   • Filters out final games (only shows active/in-progress)

2. Update Voice Channel Descriptions

   • For each active scorecard, checks for associated voice channel
   • Updates voice channel topic with live score: "BOS 4 @ 3 NYY"
   • Adds "FINAL" suffix when game completes: "BOS 5 @ 3 NYY - FINAL"
   • Gracefully handles missing or deleted voice channels

Key Features

/publish-scorecard <url>

URL/Key Support:

• Full URL: https://docs.google.com/spreadsheets/d/[KEY]/edit...
• Just the key: [SHEET_KEY]

Validation:

• Checks scorecard accessibility (public read permissions)
• Verifies scorecard has required 'Scorebug' tab
• Tests data reading to ensure valid scorecard structure

Storage:

• Saves mapping in data/scorecards.json
• Persists across bot restarts
• Associates scorecard with text channel ID

User Feedback:

• Confirmation message with sheet title
• Usage instructions for /scorebug command
• Clear error messages for access issues

/scorebug [full_length]

Display Modes:

• full_length=True (default): Complete scorebug with runners, matchups, and summary
• full_length=False: Compact view with just score and status

Data Display:

• Game header and inning information
• Score formatted in table
• Current game status (inning/half)
• Runners on base with positions
• Current matchups (optional)
• Game summary (optional)
• Team colors and thumbnails

Error Handling:

• Clear message if no scorecard published in channel
• Helpful errors for access or read failures
• Graceful handling of missing team data

Live Score Updates (Background Task)

Channel Updates:

• Clears #live-sba-scores channel before each update
• Posts up to 10 scorebugs per message (Discord limit)
• Splits into multiple messages if needed
• Shows only active games (filters out finals)

Voice Channel Integration:

• Looks up voice channel associated with scorecard's text channel
• Updates voice channel topic with formatted score
• Format: "{AWAY_ABBREV} {AWAY_SCORE} @ {HOME_SCORE} {HOME_ABBREV}"
• Adds "- FINAL" when game completes
• Rate limits to avoid Discord API issues

Architecture

Service Layer Integration

ScorebugService (services/scorebug_service.py):

• Extends SheetsService for Google Sheets access
• Returns ScorebugData objects with parsed game information
• Supports both URL and key-based scorecard access
• Reads from 'Scorebug' tab (B2:S20) for game state
• Reads team IDs from 'Setup' tab (B5:B6)

ScorebugData Fields:

{
    'away_team_id': int,
    'home_team_id': int,
    'header': str,           # Game header with inning info
    'away_score': int,
    'home_score': int,
    'which_half': str,       # Top/Bottom inning indicator
    'is_final': bool,
    'runners': list,         # Runner info [position, name] pairs
    'matchups': list,        # Current batter/pitcher matchups
    'summary': list          # Game summary data
}

Tracker Integration

ScorecardTracker stores:

{
  "scorecards": {
    "123456789": {
      "text_channel_id": "123456789",
      "sheet_url": "https://docs.google.com/...",
      "published_at": "2025-01-15T10:30:00",
      "last_updated": "2025-01-15T10:35:00",
      "publisher_id": "111222333"
    }
  }
}

Voice Channel Association:

• Voice tracker updated to store text_channel_id when voice channels created
• New method: get_voice_channel_for_text_channel(text_channel_id)
• Enables background task to update voice channel descriptions

Command Flow

Publishing Flow:

1. User runs /publish-scorecard <url>
2. Bot validates access to Google Sheet
3. Bot verifies Scorebug tab exists
4. Bot reads sample data to ensure valid structure
5. Tracker stores text_channel_id → sheet_url mapping
6. User receives confirmation message

Display Flow:

1. User runs /scorebug in channel
2. Bot looks up scorecard URL from tracker
3. Bot reads current scorebug data from sheet
4. Bot fetches team information from API
5. Bot creates rich embed with game state
6. Bot updates tracker timestamp

Background Update Flow:

1. Task runs every 3 minutes
2. Reads all published scorecards from tracker
3. For each scorecard:
   • Reads current scorebug data
   • Checks if game is active (not final)
   • Creates compact embed for live channel
   • Checks for associated voice channel
   • Updates voice channel description if found
4. Posts all active scorebugs to #live-sba-scores
5. Clears channel if no active games

Configuration

Channel Requirements

• #live-sba-scores - Live scorebug display channel (auto-updated every 3 minutes)

Data Storage

• data/scorecards.json - Published scorecard mappings
• data/voice_channels.json - Voice channel tracking (includes text_channel_id)

Google Sheets Requirements

Scorecards must have:

• Scorebug tab: Live game data (B2:S20)
• Setup tab: Team IDs (B5:B6)
• Public read access: "Anyone with the link can view"

Error Handling

Common Scenarios

• Sheet not accessible: Clear message about public permissions
• Missing Scorebug tab: Error indicating invalid scorecard structure
• No scorecard published: Helpful message to use /publish-scorecard
• Sheet read failures: Graceful degradation with retry suggestions
• Voice channel deleted: Silent skip (no errors to users)
• Missing permissions: Clear permission error messages

Service Dependencies

• Graceful degradation: Commands work without background task
• Rate limiting: 1-second delay between scorecard reads
• API failures: Comprehensive error handling for external service calls
• Discord errors: Specific handling for Forbidden, NotFound, etc.

Voice Channel Enhancement

Text Channel Association

When voice channels are created via /voice-channel:

• Text channel ID stored in voice channel tracking data
• Enables scorebug → voice channel lookup
• Persistent across bot restarts

Description Update Format

Active Game:

BOS 4 @ 3 NYY

Final Game:

BOS 5 @ 3 NYY - FINAL

Implementation:

• Uses voice channel topic field (description)
• Updates every 3 minutes with live scores
• Automatic cleanup when game ends
• No manual user interaction required

Integration Points

Bot Integration

• Package Loading: Integrated into bot.py command package loading sequence
• Background Tasks: Live scorebug tracker started in _setup_background_tasks()
• Shutdown Handling: Tracker stopped in bot.close()

Service Layer

• ScorebugService: Google Sheets data extraction
• TeamService: Team information and logo lookups
• ScorecardTracker: Persistent scorecard-channel mapping

Discord Integration

• Application Commands: Modern slash command interface
• Embed Templates: Consistent styling using EmbedTemplate
• Error Handling: Integration with global application command error handler
• Voice Channels: Bi-directional integration with voice channel system

Usage Examples

Publishing a Scorecard

/publish-scorecard https://docs.google.com/spreadsheets/d/ABC123/edit

Result: Scorecard linked to current channel for live tracking

Using Just Sheet Key

/publish-scorecard ABC123DEF456

Result: Same functionality with cleaner input

Displaying Scorebug

/scorebug

Result: Full scorebug display with all details

Compact Scorebug

/scorebug full_length:False

Result: Just score and status, no runners/matchups/summary

Monitoring and Logs

Structured Logging

self.logger.info(f"Published scorecard to channel {text_channel_id}: {sheet_url}")
self.logger.debug(f"Updated voice channel {voice_channel.name} description to: {description}")
self.logger.warning(f"Could not read scorecard {sheet_url}: {e}")

Performance Tracking

• Background task execution timing
• Google Sheets read latency
• Voice channel update success rates
• Scorecard access failure rates

Future Enhancements

Potential Features

• Scorecard rotation: Multiple scorecard support per channel
• Custom refresh intervals: User-configurable update frequency
• Notification system: Alerts for game events (runs, innings, etc.)
• Statistics tracking: Historical scorebug access patterns
• Mobile optimization: Compact embeds for mobile viewing

Configuration Options

• Per-channel settings: Different update intervals per channel
• Role permissions: Restrict scorecard publishing to specific roles
• Format customization: User-selectable scorebug styles
• Alert thresholds: Configurable notification triggers

---

Last Updated: January 2025 Architecture: Modern async Discord.py with Google Sheets integration Dependencies: discord.py, pygsheets, ScorebugService, ScorecardTracker, VoiceChannelTracker