strat-gameplay-webapp/backend/app/websocket/X_CHECK_FRONTEND_GUIDE.md

X-Check Frontend Integration Guide

Overview

X-Check defensive plays are now fully integrated into the WebSocket play_resolved event. When a play results in an X-Check (defensive position check), the event will include detailed resolution data that the UI should display to players.

Phase: 3E-Final - WebSocket Integration Date: 2025-11-03 Status: ✅ Complete (Backend), ⏳ Pending (Frontend)

---

What is X-Check?

X-Check is a defensive play resolution system where:

1. Ball is hit to a specific defensive position (SS, LF, 3B, etc.)
2. Server rolls 1d20 (defense range table) + 3d6 (error chart)
3. Defender's range and error ratings determine the outcome
4. Result can be an out, hit, or error with detailed breakdown

Example: Grounder to shortstop → SS range 4 → d20=12 → "Routine groundout" → Out recorded

---

WebSocket Event Structure

Event: play_resolved

This existing event now includes optional X-Check details when applicable.

Full Event Structure:

{
  // Standard fields (always present)
  "game_id": "123e4567-e89b-12d3-a456-426614174000",
  "play_number": 15,
  "outcome": "x_check",          // PlayOutcome enum value
  "hit_location": "SS",           // Position where ball was hit
  "description": "X-Check SS: G2 → G2 + NO = groundball_b",
  "outs_recorded": 1,
  "runs_scored": 0,
  "batter_result": null,          // null = out, 1-4 = base reached
  "runners_advanced": [],
  "is_hit": false,
  "is_out": true,
  "is_walk": false,
  "roll_id": "abc123def456",

  // X-Check details (OPTIONAL - only present for defensive plays)
  "x_check_details": {
    // Defensive player info
    "position": "SS",             // SS, LF, 3B, etc.
    "defender_id": 42,            // Lineup ID of defender
    "defender_range": 4,          // 1-5 (adjusted for playing in)
    "defender_error_rating": 12,  // 0-25 (lower is better)

    // Dice rolls
    "d20_roll": 12,               // 1-20 (defense table lookup)
    "d6_roll": 10,                // 3-18 (error chart lookup)

    // Resolution steps
    "base_result": "G2",          // Initial result from defense table
    "converted_result": "G2",     // After SPD test and G2#/G3# conversion
    "error_result": "NO",         // Error type: NO, E1, E2, E3, RP
    "final_outcome": "groundball_b",  // Final PlayOutcome enum value
    "hit_type": "g2_no_error",    // Combined result string

    // Optional: SPD test (if base_result was 'SPD')
    "spd_test_roll": null,        // 1-20 if SPD test was needed
    "spd_test_target": null,      // Target number for SPD test
    "spd_test_passed": null       // true/false if test was needed
  }
}

---

Frontend Implementation

1. Detecting X-Check Plays

socket.on('play_resolved', (data) => {
  // Check if this play was an X-Check
  if (data.outcome === 'x_check' && data.x_check_details) {
    // This is a defensive play - show X-Check UI
    displayXCheckResult(data);
  } else {
    // Normal play - show standard result
    displayStandardPlayResult(data);
  }
});

2. Displaying X-Check Details

Basic Display (minimum viable):

function displayXCheckResult(data) {
  const xcheck = data.x_check_details;

  console.log(`⚾ X-Check to ${xcheck.position}`);
  console.log(`   Defender Range: ${xcheck.defender_range}`);
  console.log(`   Rolls: d20=${xcheck.d20_roll}, 3d6=${xcheck.d6_roll}`);
  console.log(`   Result: ${xcheck.base_result} → ${xcheck.converted_result}`);
  console.log(`   Error: ${xcheck.error_result}`);
  console.log(`   Outcome: ${data.description}`);

  // Update game UI
  updateGameState({
    outs: data.outs_recorded,
    runs: data.runs_scored,
    description: data.description
  });
}

Enhanced Display (with animations):

function displayXCheckResult(data) {
  const xcheck = data.x_check_details;

  // 1. Show fielder animation
  animateFielder(xcheck.position, xcheck.defender_id);

  // 2. Show dice rolls with delay
  setTimeout(() => {
    showDiceRoll('Defense Roll', xcheck.d20_roll);
    showDiceRoll('Error Roll', xcheck.d6_roll);
  }, 500);

  // 3. Show defensive rating overlay
  setTimeout(() => {
    showDefenderStats({
      position: xcheck.position,
      range: xcheck.defender_range,
      error_rating: xcheck.defender_error_rating,
      defender_id: xcheck.defender_id
    });
  }, 1500);

  // 4. Show result progression
  setTimeout(() => {
    showResultFlow({
      base: xcheck.base_result,
      converted: xcheck.converted_result,
      error: xcheck.error_result,
      final: data.description
    });
  }, 2500);

  // 5. Update game state
  setTimeout(() => {
    updateGameState({
      outs: data.outs_recorded,
      runs: data.runs_scored,
      description: data.description
    });
  }, 3500);
}

3. Defender Stats Display

Show defender's ratings when X-Check is triggered:

function showDefenderStats(stats) {
  const defender = getPlayerById(stats.defender_id);

  return `
    <div class="xcheck-defender">
      <div class="defender-name">${defender.name}</div>
      <div class="defender-position">${stats.position}</div>
      <div class="defender-ratings">
        <div class="rating-range">
          <label>Range:</label>
          <span class="rating-value">${stats.range}/5</span>
          ${renderRatingBars(stats.range, 5)}
        </div>
        <div class="rating-error">
          <label>Error:</label>
          <span class="rating-value">${stats.error_rating}/25</span>
          ${renderRatingBars(25 - stats.error_rating, 25)}
        </div>
      </div>
    </div>
  `;
}

4. Result Flow Visualization

Show the resolution steps:

function showResultFlow(result) {
  return `
    <div class="xcheck-flow">
      <div class="flow-step">
        <div class="step-label">Defense Table</div>
        <div class="step-value">${result.base}</div>
      </div>
      ${result.converted !== result.base ? `
        <div class="flow-arrow">→</div>
        <div class="flow-step">
          <div class="step-label">Converted</div>
          <div class="step-value">${result.converted}</div>
        </div>
      ` : ''}
      <div class="flow-arrow">+</div>
      <div class="flow-step">
        <div class="step-label">Error Check</div>
        <div class="step-value">${result.error}</div>
      </div>
      <div class="flow-arrow">=</div>
      <div class="flow-step final">
        <div class="step-label">Result</div>
        <div class="step-value">${result.final}</div>
      </div>
    </div>
  `;
}

---

Error Result Types

The error_result field can be one of:

Code	Meaning	Effect
NO	No error	Clean play
E1	Minor error	+1 base advancement
E2	Moderate error	+2 base advancement
E3	Major error	+3 base advancement
RP	Rare play	Treat as E3

Important: If base_result was an out (FO, PO) and error_result is E1-E3/RP, the error overrides the out and batter reaches base safely.

---

Base Result Codes

Common result codes from the defense table:

Groundball Results

• G1, G2, G3: Groundball outcomes (1=easy, 3=hard)
• G2#, G3#: Hash results (convert to SI2 if defender holding runner or playing in)

Flyball Results

• F1, F2, F3: Flyball outcomes (1=deep, 3=shallow)
• FO: Flyout
• PO: Popout

Hit Results

• SI1, SI2: Singles (1=standard, 2=enhanced advancement)
• DO2, DO3: Doubles (2=to second, 3=to third)
• TR3: Triple

Special Results

• SPD: Speed test (requires batter's speed rating)

---

Example Scenarios

Scenario 1: Clean Out

{
  "outcome": "x_check",
  "description": "X-Check SS: G2 → G2 + NO = groundball_b",
  "x_check_details": {
    "position": "SS",
    "d20_roll": 8,
    "d6_roll": 10,
    "defender_range": 4,
    "defender_error_rating": 8,
    "base_result": "G2",
    "converted_result": "G2",
    "error_result": "NO",
    "final_outcome": "groundball_b"
  }
}

UI Display: "Grounder to shortstop. Clean play. Batter out."

---

Scenario 2: Error on Out

{
  "outcome": "error",
  "description": "X-Check 3B: PO → PO + E2 = error",
  "outs_recorded": 0,
  "batter_result": 2,  // Reached 2nd base
  "x_check_details": {
    "position": "3B",
    "d20_roll": 15,
    "d6_roll": 16,
    "defender_range": 3,
    "defender_error_rating": 18,
    "base_result": "PO",
    "converted_result": "PO",
    "error_result": "E2",
    "final_outcome": "error"
  }
}

UI Display: "Pop up to third base. Error! Ball dropped. Batter advances to second."

---

Scenario 3: Hit with Error

{
  "outcome": "single_2",
  "description": "X-Check RF: SI2 → SI2 + E1 = single_2_plus_error_1",
  "outs_recorded": 0,
  "runs_scored": 1,
  "batter_result": 2,  // Batter to 2nd (single + error)
  "x_check_details": {
    "position": "RF",
    "d20_roll": 18,
    "d6_roll": 15,
    "defender_range": 2,
    "defender_error_rating": 12,
    "base_result": "SI2",
    "converted_result": "SI2",
    "error_result": "E1",
    "final_outcome": "single_2"
  }
}

UI Display: "Single to right field. Fielding error! Batter advances to second. Runner scores from 2nd."

---

Scenario 4: Hash Conversion

{
  "outcome": "single_2",
  "description": "X-Check 2B: G3# → SI2 + NO = single_2_no_error",
  "x_check_details": {
    "position": "2B",
    "d20_roll": 19,
    "d6_roll": 8,
    "defender_range": 4,  // Was 3, but playing in (+1)
    "defender_error_rating": 5,
    "base_result": "G3#",
    "converted_result": "SI2",  // Converted because defender holding runner
    "error_result": "NO",
    "final_outcome": "single_2"
  }
}

UI Display: "Grounder to second base. Defender holding runner. Batter beats the throw. Single."

---

Testing X-Check UI

Manual Testing Steps

1. Start a game and get to a play with runners on base
2. Submit X-Check outcome: outcome: "x_check", hit_location: "SS"
3. Verify event received with x_check_details field
4. Check UI displays:
   • Defender's name and ratings
   • Dice roll values
   • Resolution steps (base → converted → + error → final)
   • Final game state update

Test Cases

// Test 1: Clean out
testXCheck({
  outcome: "x_check",
  hit_location: "SS",
  expected: {
    hasXCheckDetails: true,
    errorResult: "NO",
    outsRecorded: 1,
    runsScored: 0
  }
});

// Test 2: Error on out
testXCheck({
  outcome: "x_check",
  hit_location: "3B",
  expected: {
    hasXCheckDetails: true,
    errorResult: "E2",
    outsRecorded: 0,
    batter_result: 2  // Batter reached 2nd on error
  }
});

// Test 3: Hit with error
testXCheck({
  outcome: "x_check",
  hit_location: "RF",
  expected: {
    hasXCheckDetails: true,
    errorResult: "E1",
    batter_result: 2,  // Single + error = 2nd base
    runsScored: 1      // Runner scored from 2nd
  }
});

---

League Differences

SBA League

• Uses default ratings (range=3, error=15) for all defenders
• X-Check still works, just with generic ratings
• UI should still display X-Check details

PD League

• Uses actual player ratings from PD API
• Range: 1-5 (varies by player and position)
• Error: 0-25 (varies by player and position)
• Ratings loaded at game start and cached
• UI should highlight superior/poor defensive ratings

---

UI Components Checklist

Minimum Viable (Phase 1)

• Detect X-Check plays in play_resolved event
• Display defender's name and position
• Show dice roll results (d20, 3d6)
• Display final outcome description
• Update game state (outs, runs, bases)

Enhanced (Phase 2)

• Animated fielder sprites
• Defender rating bars (range, error)
• Result flow visualization (base → converted → + error → final)
• Error type indicators (E1/E2/E3/RP with color coding)
• SPD test display (when applicable)

Polish (Phase 3)

• Sound effects for different outcomes
• Particle effects for errors
• Detailed play-by-play log with X-Check breakdowns
• Hover tooltips explaining ratings
• Mobile-optimized compact view

---

Common Pitfalls

❌ Don't Assume X-Check Details Exist

// BAD: Will crash if not an X-Check
const position = data.x_check_details.position;

// GOOD: Check first
if (data.x_check_details) {
  const position = data.x_check_details.position;
}

❌ Don't Ignore Error Overrides

// BAD: Assumes outcome matches base_result
if (xcheck.base_result === 'PO') {
  showOut();  // Wrong if error_result is E1-E3!
}

// GOOD: Use final_outcome or check error_result
if (data.is_out) {
  showOut();
}

❌ Don't Hardcode Position Labels

// BAD: Doesn't handle all positions
const positionName = xcheck.position === 'SS' ? 'Shortstop' : 'Unknown';

// GOOD: Use position map
const POSITION_NAMES = {
  'P': 'Pitcher', 'C': 'Catcher',
  '1B': 'First Base', '2B': 'Second Base', '3B': 'Third Base',
  'SS': 'Shortstop', 'LF': 'Left Field',
  'CF': 'Center Field', 'RF': 'Right Field'
};
const positionName = POSITION_NAMES[xcheck.position];

---

Questions?

Backend Developer: See app/websocket/handlers.py lines 369-388 X-Check Logic: See app/core/play_resolver.py lines 590-785 Data Models: See app/models/game_models.py lines 242-289

Phase 3E-Final Docs: See .claude/implementation/NEXT_SESSION.md

---

Last Updated: 2025-11-03 Author: Claude (Phase 3E-Final) Status: ✅ Backend Complete, ⏳ Frontend Pending