Level Progression System
Relevant source files
The following files were used as context for generating this wiki page:
The Level Progression System is a core component of the Debug Arena platform designed to manage the sequential advancement of teams through a series of debugging challenges. It enforces linear progress, ensuring that participants cannot skip levels, and integrates real-time performance tracking through score calculations based on time and hint usage. The system serves as the gatekeeper between the user's current standing and the unlocking of more advanced technical hurdles.
Sources: README.md:14-18, routes/arena_routes.py:61-71
System Architecture
The progression system relies on a central level configuration and persistent database states to track team advancement.
Level Configuration
All levels are defined in a centralized dictionary which contains the challenge metadata, buggy code, and validation requirements.
| Field | Description |
|---|---|
title | The descriptive name of the level. |
buggy_code | The initial faulty Python code provided to the team. |
expected_output | The exact string output required for a successful submission. |
hint | Logical guidance available to teams at a score penalty. |
penalty | The point deduction applied if the hint is revealed. |
difficulty | The qualitative complexity rating (e.g., Easy, Medium, Hard). |
Sources: levels/level_manager.py:3-109
State Management
Progress is tracked via the Team model, specifically using the current_level field. This integer acts as a pointer to the next level the team is authorized to attempt.
The diagram above illustrates the relationship between a team's persistent state and their individual level completions.
Sources: models/team.py:7-26, models/submission.py:4-16
Navigation and Gatekeeping
The system employs middleware-style checks within routes to prevent unauthorized access to future levels.
Dashboard Logic
The dashboard dynamically renders levels based on the team's current_level.
- Unlocked: If
team.current_level >= level.id, the team can launch the arena for that level. - Locked: If
team.current_level < level.id, the level is marked as "System Encrypted" and access is disabled. - Completed: If
team.current_level > level.id, the level is marked as completed but remains revisitable.
Sources: routes/arena_routes.py:12-36, templates/dashboard.html:56-110
Access Control Flow
When a user attempts to access /arena/<int:level_id>, the system validates the request against the database.
This flowchart details the multi-stage validation process for level entry.
Sources: routes/arena_routes.py:45-71
Progression Logic and Scoring
Level advancement occurs only when a team successfully submits code that produces the expected_output.
Submission Workflow
- Code Execution: The submitted code is executed via
execute_python_code. - Output Validation: The result is compared against
LEVELS[level_id]['expected_output']. - Score Calculation: Points are awarded based on a base value minus time penalties and hint penalties.
- Database Update: If the submission is for the team's
current_level, thecurrent_levelis incremented, and thetotal_scoreis updated.
Sources: routes/submit_routes.py:27-80
Scoring Formulas
The system utilizes dynamic scoring to reward speed and independent problem-solving.
| Component | Logic |
|---|---|
| Base Points | 100 points per level. |
| Time Penalty | -1 point for every 10 seconds elapsed (time_taken // 10). |
| Hint Penalty | A fixed deduction (e.g., 10-30 points) if the hint_used flag is set in the session. |
| Score Floor | A hard minimum of 30 points is enforced regardless of penalties. |
Sources: routes/submit_routes.py:44-55, levels/level_manager.py:107
Final Victory
The progression ends when the team completes the final level (Level 8). At this point, team.current_level exceeds the maximum key in the LEVELS configuration, triggering a redirect to the /victory route.
Sources: routes/arena_routes.py:65-67, templates/arena.html:158-164