Skip to content

Latest commit

 

History

History
364 lines (278 loc) · 11.6 KB

TARGETING_SYSTEM_DOCUMENTATION.md

File metadata and controls

364 lines (278 loc) · 11.6 KB

WoW Arena Targeting System Documentation

Overview

The WoW Arena Targeting System is a comprehensive analysis framework that extracts strategic decision intelligence from arena combat logs and video metadata. The system provides realistic coordination metrics and targeting patterns suitable for AI model training.

System Architecture

Core Components

  1. Arena Match Data Model (arena_match_model.py)

    • Complete player and team composition modeling
    • Role-based player classification
    • Team coordination context

  2. JSON Metadata Integration (json_metadata_targeting_system.py)

    • Video metadata parsing for accurate team detection
    • Specialization ID to role mapping
    • Realistic team assignment logic

  3. Enhanced Targeting Analysis (enhanced_targeting_with_model.py)

    • Weighted coordination scoring algorithm
    • Target prioritization pattern recognition
    • Model-based strategic analysis

  4. Development Standards Framework (development_standards.py)

    • Unicode-safe logging and file operations
    • Robust arena boundary detection
    • Production-ready error handling

Data Models

Arena Match Model

@dataclass
class ArenaMatchModel:
    # Basic match information
    filename: str                    # Video filename
    match_id: str                   # Unique identifier
    arena_size: ArenaSize           # 2v2, 3v3, Solo Shuffle
    arena_map: str                  # Arena name
    start_time: datetime            # Match start timestamp
    primary_player: str             # Player being analyzed
    
    # Team compositions
    friendly_team: TeamComposition  # Primary player's team
    enemy_team: TeamComposition     # Opposing team
    
    # Combat log boundaries
    arena_start_time: datetime      # Arena match start
    arena_end_time: datetime        # Arena match end
    combat_log_file: str           # Source combat log

Player Information Model

@dataclass
class PlayerInfo:
    name: str                      # Base player name
    full_name: str                 # Name with server (e.g., "Player-Realm-US")
    guid: str                      # Player GUID from combat log
    class_name: str                # WoW class (Warlock, Priest, etc.)
    specialization: str            # Spec name (Affliction, Holy, etc.)
    role: PlayerRole               # Inferred role (Tank/Healer/DPS)
    team: TeamSide                 # Friendly or Enemy
    pet_name: Optional[str]        # Pet name if applicable
    pet_guid: Optional[str]        # Pet GUID if applicable

Team Composition Model

@dataclass
class TeamComposition:
    players: List[PlayerInfo]      # All team members
    healers: List[PlayerInfo]      # Healer players
    dps: List[PlayerInfo]          # DPS players  
    tanks: List[PlayerInfo]        # Tank players
    
    @property
    def composition_string(self) -> str:
        # Returns format like "1H2D" (1 Healer, 2 DPS)

Specialization to Role Mapping

The system uses WoW specialization IDs for accurate role detection:

SPEC_ID_TO_ROLE = {
    # Healers
    264: PlayerRole.HEALER,     # Restoration Shaman
    270: PlayerRole.HEALER,     # Mistweaver Monk
    256: PlayerRole.HEALER,     # Discipline Priest
    65: PlayerRole.HEALER,      # Holy Paladin
    
    # DPS
    265: PlayerRole.RANGED_DPS, # Affliction Warlock
    72: PlayerRole.MELEE_DPS,   # Fury Warrior
    577: PlayerRole.MELEE_DPS,  # Havoc Demon Hunter
    63: PlayerRole.RANGED_DPS,  # Fire Mage
    
    # Tanks
    250: PlayerRole.TANK,       # Blood Death Knight
    66: PlayerRole.TANK,        # Protection Paladin
    # ... 47 total specialization mappings
}

Coordination Analysis

Weighted Coordination Scoring Algorithm

The system implements role-weighted coordination scoring that reflects arena gameplay priorities:

# Role-based weighting system
DPS_WEIGHT = 2.0    # DPS coordination weighted double
HEALER_WEIGHT = 1.0 # Healer coordination standard weight

# Coordination calculation
coordination_score = coordination_weight / total_possible_weight

# Example for 3v3 (2 DPS + 1 Healer):
# Perfect coordination (all attack same target): 5.0/5.0 = 1.000
# High coordination (both DPS attack): 4.0/5.0 = 0.800
# Medium coordination (1 DPS + Healer): 3.0/5.0 = 0.600
# Low coordination (1 DPS only): 2.0/5.0 = 0.400

Coordination Score Interpretation

Score Range Coordination Level Description
0.800-1.000 Exceptional Pro-level team coordination
0.600-0.800 High Skilled team coordination
0.400-0.600 Good Competitive coordination patterns
0.200-0.400 Basic Casual coordination
0.000-0.200 Poor Minimal coordination

Time Window Analysis

The system analyzes coordination in 3-second time windows:

  1. Event Grouping: Combat events grouped by timestamp
  2. Target Identification: Primary focus target determined by attack frequency
  3. Role Weighting: DPS attacks weighted 2x healer attacks
  4. Score Aggregation: Average coordination across all windows

Target Prioritization Analysis

Priority Target Detection

The system identifies targeting patterns based on:

  • Attack Frequency: Most attacked enemy players
  • Role-Based Targeting: Healer vs DPS vs Tank focus
  • Target Switching: Pattern recognition for strategic switches

Prioritization Strategies

def _infer_strategy(self, target_ranking, role_attacks):
    healer_focus_ratio = healer_attacks / total_attacks
    
    if healer_focus_ratio > 0.6:
        return "Healer Focus"      # Priority on enemy healers
    elif ranged_dps_attacks > melee_dps_attacks:
        return "Ranged Priority"  # Focus on ranged damage dealers
    else:
        return "Balanced Targeting" # Mixed targeting approach

JSON Metadata Integration

Video Metadata Structure

The system parses JSON metadata from video files:

{
  "category": "3v3",
  "zoneID": 572,
  "zoneName": "Ruins of Lordaeron",
  "duration": 121,
  "result": true,
  "combatants": [
    {
      "_GUID": "Player-53-0D5553B6",
      "_teamID": 0,              // Team identifier (0 or 1)
      "_specID": 265,            // Specialization ID
      "_name": "Phlargus",       // Player name
      "_realm": "Eredar"         // Server realm
    }
  ]
}

Team Detection Logic

# Accurate team assignment using JSON metadata
for combatant in json_data['combatants']:
    if combatant['_teamID'] == primary_player_team_id:
        player.team = TeamSide.FRIENDLY
    else:
        player.team = TeamSide.ENEMY

Performance Metrics

System Validation Results

  • JSON Metadata Integration: 100% functional
  • Team Detection Accuracy: 5/5 matches with correct team assignment
  • Coordination Analysis: 100% coverage with realistic scoring
  • Processing Efficiency: 9,780+ events processed without timeouts
  • Role Detection: 90% accuracy with specialization ID mapping

Coordination Score Results

Recent validation shows realistic coordination patterns:

Match Player Arena Weighted Score Windows
Match 1 Phlargus Ruins of Lordaeron 0.496 27
Match 2 Phlargus Ashamane's Fall 0.552 21
Match 3 Phlargus Cage of Carnage 0.571 14
Average 0.540 20.7

Production Usage

Core Analysis Functions

# Create enhanced match model with JSON metadata
match_model = create_enhanced_match_model_with_json(match_row)

# Run targeting analysis with weighted coordination
analyzer = ModelBasedTargetingAnalyzer(match_model)
coordination_analysis = analyzer.analyze_team_coordination(combat_events)
prioritization_analysis = analyzer.analyze_target_prioritization(combat_events)

Output Data Format

{
    'match_filename': str,
    'json_metadata_used': bool,
    'team_composition': {
        'friendly': int,           # Number of friendly players
        'enemy': int,             # Number of enemy players
        'friendly_roles': List[str], # Role descriptions
        'enemy_roles': List[str]     # Role descriptions
    },
    'coordination_analysis': {
        'available': bool,
        'score': float,           # Weighted coordination score
        'windows_analyzed': int,  # Number of time windows
        'weighted_coordination': bool,
        'dps_weight_multiplier': 2.0,
        'healer_weight_multiplier': 1.0
    },
    'prioritization_analysis': {
        'available': bool,
        'primary_targets': List[str],
        'target_priority_ranking': List[Tuple[str, int]],
        'healer_focus_ratio': float,
        'prioritization_strategy': str
    }
}

Development Standards

Unicode-Safe Operations

All file operations use Unicode-safe methods:

class SafeLogger:
    @staticmethod
    def success(message: str):
        print(f"SUCCESS: {message}")  # ASCII-safe output
    
    @staticmethod
    def info(message: str):
        print(f"INFO: {message}")

Error Handling

Robust error handling with graceful degradation:

def safe_operation():
    try:
        # Primary operation
        return primary_method()
    except SpecificError:
        # Fallback method
        return fallback_method()
    except Exception as e:
        SafeLogger.error(f"Operation failed: {e}")
        return None

Arena Boundary Detection

Multi-stage arena boundary detection with verification:

  1. Death Correlation: Verify deaths match between combat log and video metadata
  2. Duration Verification: Confirm match duration consistency
  3. Time Proximity: Use timestamp matching as fallback

Future Development Opportunities

Immediate Enhancements

  1. Solo Shuffle Round-by-Round Analysis: Track coordination across individual rounds
  2. Enhanced Target Prioritization: More sophisticated switching pattern recognition
  3. Strategic Decision Context: Include cooldown and positioning awareness

Advanced Features

  1. Dynamic Role Weighting: Adjust weights based on team composition
  2. Target Priority Weighting: Weight coordination by target importance (healer > DPS > tank)
  3. Timing Synchronization: Bonus scoring for synchronized attacks
  4. Spell Coordination: Recognize CC + damage combinations

AI Training Integration

The system produces structured data suitable for machine learning:

  • Consistent Schema: Standardized output format across all matches
  • Realistic Metrics: Coordination scores reflect actual gameplay quality
  • Rich Context: Team composition and role information included
  • Scalable Processing: Handles large datasets efficiently

File Organization

Core Production Files

  • arena_match_model.py - Complete data model definitions
  • json_metadata_targeting_system.py - JSON integration and realistic analysis
  • enhanced_targeting_with_model.py - Weighted coordination algorithm
  • development_standards.py - Production-ready utilities

Validation and Testing

  • test_weighted_coordination.py - Algorithm validation
  • targeting_system_final_validation.py - Comprehensive system validation
  • weighted_coordination_summary.py - Results analysis

Documentation and Reports

  • TARGETING_SYSTEM_DOCUMENTATION.md - This comprehensive reference
  • targeting_system_final_validation_report.json - Validation results
  • weighted_coordination_summary_report.json - Algorithm performance data

The WoW Arena Targeting System represents a complete, production-ready framework for extracting meaningful strategic intelligence from arena combat data, with realistic coordination metrics and comprehensive player/team modeling suitable for AI training applications.