Scoring System & Leaderboard
Relevant source files
The following files were used as context for generating this wiki page:
The Scoring System and Leaderboard in the Python Debug Arena provide a real-time competitive framework for evaluate team performance. The system calculates scores based on speed of resolution and level difficulty, while applying specific penalties for the use of the hint system ("Oracle").
The Leaderboard serves as a central hub for viewing global rankings, displaying live updates of team progress across all levels. It ensures transparency and engagement by ranking teams based on their current level completion and cumulative points earned.
Sources: README.md:27-35, routes/leaderboard_routes.py:1-12
Scoring Logic & Calculation
Scores are calculated dynamically upon the successful submission of a level's solution. The system balances base points against time elapsed and hint usage to determine the final score_earned for a specific level.
Point Calculation Components
The final score for a level is determined using the following logic:
- Base Points: Every level starts with a base value of 100 points.
- Time Penalty: A penalty of -1 point is applied for every 10 seconds taken to solve the level.
- Hint Penalty: If a team accesses the hint for a level, a predefined penalty (ranging from 10 to 30 points) is deducted from the level score.
- Minimum Score Floor: The system enforces a hard minimum of 30 points for a successfully completed level, regardless of penalties.
Sources: routes/submit_routes.py:53-65, levels/level_manager.py:5-156
Score Update Workflow
The following diagram illustrates the sequence of events during a successful code submission and the subsequent score update.
Sources: routes/submit_routes.py:46-95
Leaderboard Architecture
The leaderboard is a real-time data representation of the Team model, sorted by competitive priority. Rankings are determined first by the current_level (highest level reached) and then by the total_score as a secondary tie-breaker.
Data Model for Rankings
| Field | Type | Description |
|---|---|---|
team_name | String | Unique identifier for the team. |
college | String | Academic institution name. |
current_level | Integer | The level the team is currently attempting or has reached. |
total_score | Integer | Cumulative points earned from all previous levels. |
Sources: models/team.py:7-20, routes/leaderboard_routes.py:10-11
Ranking Logic Implementation
The leaderboard route fetches all teams and orders them using a dual-column descending sort.
# routes/leaderboard_routes.py:10-11
teams = Team.query.order_by(Team.current_level.desc(), Team.total_score.desc()).all()
The frontend uses an auto-refresh mechanism to ensure the board stays current during live events.
// templates/leaderboard.html:62-64
setTimeout(function(){
window.location.reload(1);
}, 30000); // Refreshes every 30 seconds
Level-Specific Penalties
Penalties for hint usage are defined per level in the level_manager.py. These values represent the amount of points deducted if the "Oracle" system is accessed.
| Level ID | Level Title | Difficulty | Hint Penalty |
|---|---|---|---|
| 1 | The Missing Link | Easy | 15 |
| 2 | Range Rover | Easy | 10 |
| 4 | The String Stumbler | Easy-Medium | 15 |
| 5 | Broken Username Logic | Medium | 20 |
| 7 | The Fibonacci Timeout | Hard | 25 |
| 8 | Matrix Transpose | Hard | 30 |
Sources: levels/level_manager.py:4-156
Data Persistence & Submissions
Every successful scoring event is recorded in the Submission table, providing an audit trail of how scores were achieved.
The Submission model captures the exact state of the scoring calculation, including the time_taken and score_earned at the moment of completion.
Sources: models/submission.py:4-15, routes/submit_routes.py:75-82
Summary
The Scoring System & Leaderboard module integrates time-tracking, penalty application, and persistent database updates to maintain a fair competitive environment. By rewarding both accuracy and speed while discouraging over-reliance on hints, the system effectively distinguishes the performance levels of different teams within the Debug Arena.