Feat: Performance Analytics & Comparison Implementation

[manlikeHB]

Overview

Implement performance analytics and player comparison functionality for RoundPlayer. This issue covers performance summary generation and player ranking comparison logic.

Requirements

Functions to Implement

get_performance() - Generate Performance Summary

fn get_performance(self: @RoundPlayer, total_cards: u64) -> RoundPlayerPerformance

• Create comprehensive performance summary for display
• Aggregate multiple performance metrics
• Calculate derived statistics
• Note: is_leading field set externally by comparison logic
• Used for leaderboards and player dashboards

outperforms() - Compare Player Performance

fn outperforms(self: @RoundPlayer, other: @RoundPlayer) -> bool

• Compare this player's performance against another player
• Multi-tier ranking system for fair comparison
• Determine who is performing better overall
• Used for leaderboard sorting and ranking

Business Logic

Performance Summary Components

• Accuracy Percentage: Player's correct answer rate (0-100)
• Wrong Answers: Total number of incorrect responses
• Completion Percentage: Progress through total cards (0-100)
• Cards Remaining: Number of cards left to answer
• Is Leading: External flag for leaderboard position (set by caller)

Player Comparison Hierarchy

1. Primary: Total Score (higher wins)
2. Secondary: Accuracy Percentage (higher wins)
3. Tertiary: Best Time (lower wins, 0 = no best time)
4. Quaternary: Average Time (lower wins)

Comparison Logic Rules

• Higher total score always wins
• If scores equal, higher accuracy wins
• If accuracy equal, faster best time wins
• If best times equal, faster average time wins
• Players with no best time (0) lose to those with times
• All factors considered for comprehensive ranking

Acceptance Criteria

• Performance summary generation working correctly
• All performance metrics included and accurate
• Player comparison logic implemented properly
• Multi-tier ranking system functioning correctly
• Score-based primary comparison working
• Accuracy-based secondary comparison working
• Time-based tertiary and quaternary comparisons working
• Edge cases handled properly (zero values, ties)
• Complete test coverage including complex scenarios

Dependencies

• Depends on performance metric functions from Issue Feat: Performance Metrics Implementation #138

Note

Target Branch

• refac/modular-architecture

File Location

• src/models/round/round_player.cairo

Target Trait

• RoundPlayerTrait

[emarc99]

Would love to do this!

[Henrichy]

Define RoundPlayerPerformance struct

We’ll need a clean struct to hold all summary metrics:

struct RoundPlayerPerformance {
score: u64,
accuracy_percentage: u64,
wrong_answers: u64,
completion_percentage: u64,
cards_remaining: u64,
best_time: u64,
avg_time: u64,
is_leading: bool, // set externally
}

2. get_performance Implementation

Generate the performance summary:

impl RoundPlayerTrait of RoundPlayer {
fn get_performance(self: @roundplayer, total_cards: u64) -> RoundPlayerPerformance {
let answered = self.correct_answers + self.wrong_answers;
let cards_remaining = total_cards - answered;

    // avoid division by zero
    let accuracy_percentage = if answered > 0 {
        (self.correct_answers * 100) / answered
    } else {
        0
    };

    let completion_percentage = if total_cards > 0 {
        (answered * 100) / total_cards
    } else {
        0
    };

    RoundPlayerPerformance {
        score: self.score,
        accuracy_percentage,
        wrong_answers: self.wrong_answers,
        completion_percentage,
        cards_remaining,
        best_time: self.best_time,
        avg_time: self.avg_time,
        is_leading: false, // to be set externally by leaderboard logic
    }
}

}

3. outperforms Implementation

Multi-tier comparison logic for fair ranking:

impl RoundPlayerTrait of RoundPlayer {
fn outperforms(self: @roundplayer, other: @roundplayer) -> bool {
// Primary: higher score
if self.score != other.score {
return self.score > other.score;
}

    // Secondary: higher accuracy
    let self_accuracy = self.get_accuracy();
    let other_accuracy = other.get_accuracy();
    if self_accuracy != other_accuracy {
        return self_accuracy > other_accuracy;
    }

    // Tertiary: best time (lower wins, 0 loses)
    if self.best_time != other.best_time {
        if self.best_time == 0 { return false; }
        if other.best_time == 0 { return true; }
        return self.best_time < other.best_time;
    }

    // Quaternary: average time (lower wins)
    if self.avg_time != other.avg_time {
        return self.avg_time < other.avg_time;
    }

    // Tie
    return false;
}

}

Helper for accuracy (keeps things clean):

impl RoundPlayer {
fn get_accuracy(self: @roundplayer) -> u64 {
let answered = self.correct_answers + self.wrong_answers;
if answered == 0 {
return 0;
}
(self.correct_answers * 100) / answered
}
}

✅ Edge Cases Covered

Zero answered cards → accuracy = 0, completion = 0

Zero best time → loses to players with actual times

Exact ties → returns false (not outperforming)

Large numbers → safe with u64

🧪 Testing Scenarios

Player with higher score always wins

Equal score → check accuracy winner

Equal score + accuracy → check best time winner

One player has best_time = 0 → loses to any non-zero best time

Equal across all → returns false (tie case)

[emarc99]

Would love to do this!

[Henrichy]

Plan of Action:

get_performance() Implementation

Aggregate all relevant performance metrics (accuracy %, wrong answers, completion %, cards remaining).

Ensure the performance summary is comprehensive and matches the RoundPlayerPerformance structure.

Expose is_leading as an externally settable field (kept separate from calculation logic for leaderboard integration).

outperforms() Comparison Logic

Implement the full multi-tier ranking system:

Primary: Total Score (higher wins).

Secondary: Accuracy % (higher wins).

Tertiary: Best Time (lower wins, 0 treated as no time and losing to valid times).

Quaternary: Average Time (lower wins).

Properly handle edge cases (e.g., ties, zero values, no best time).

Testing & Validation

Add comprehensive test coverage to validate performance summary calculations and comparison logic.

Include complex scenarios where players tie on certain metrics to ensure fallbacks work correctly.

Outcome:
This will provide accurate performance analytics, ensure fair player ranking comparisons, and support leaderboard functionality.

I’m confident I can deliver this aligned with the modular architecture in src/models/round/round_player.cairo under the RoundPlayerTrait.