Customizing & Adding Levels

Relevant source files

The following files were used as context for generating this wiki page:

• levels/level_manager.py
• routes/arena_routes.py
• routes/submit_routes.py
• templates/arena.html
• models/team.py
• README.md

The level system in Debug Arena is a structured framework designed to challenge participants with progressive debugging tasks. Levels are centralized within a manager that defines the code to be fixed, the validation criteria, and the help available to teams. This modular architecture allows developers to easily extend the arena by adding new challenges or modifying existing ones without altering the core routing logic.

The system integrates directly with the scoring engine and the proctoring layer to ensure that every customized level maintains competitive integrity through time-based penalties and hint-usage deductions.

Level Definition Framework

Levels are defined as a dictionary within levels/level_manager.py. Each level is indexed by an integer ID which determines the progression order for teams. A level object contains the metadata required for the UI, the execution engine, and the scoring logic.

Data Structure Schema

Each level entry must contain specific keys to function correctly within the dashboard and arena templates.

Key	Type	Description
title	String	The display name of the level shown in the Dashboard and Arena.
buggy_code	String	The faulty Python snippet presented to the user in the CodeMirror editor.
expected_output	String	The exact string output required for a successful submission.
hint	String	Logical guidance revealed to the user upon request.
penalty	Integer	The score deduction applied if the user reveals the hint.
difficulty	String	Descriptive label (e.g., "Easy", "Hard") used for UI filtering/display.

Sources: [levels/level_manager.py:3-125](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/levels/level_manager.py#L3-L125), [templates/arena.html:15-18](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/templates/arena.html#L15-L18)

Example Level Implementation

# levels/level_manager.py

LEVELS = {
    1: {
        "title": "The Missing Link",
        "buggy_code": (
            "def greet(name):\n"
            "    print(\"Hello, \" + name\n\n"
            "greet(\"Coder\")"
        ),
        "expected_output": "Hello, Coder",
        "hint": "Python requires balanced parentheses.",
        "penalty": 15,
        "difficulty": "Easy"
    }
}

Sources: [levels/level_manager.py:4-16](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/levels/level_manager.py#L4-L16)

Level Progression and Logic Flow

The system uses a sequential progression model. A team's progress is tracked via the current_level field in the Team model. Users are restricted from accessing levels with an ID greater than their current progress.

Progression Sequence

This flow ensures that users cannot skip challenges. When current_level exceeds the maximum key in the LEVELS dictionary, the user is redirected to the victory screen.

Sources: [routes/arena_routes.py:53-73](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/arena_routes.py#L53-L73), [routes/submit_routes.py:41-83](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/submit_routes.py#L41-L83), [models/team.py:14](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/models/team.py#L14)

Scoring and Penalty Configuration

Level customization directly affects team scores through three primary variables: Difficulty, Time, and Hints.

1. Base Points: A standard 100 points is awarded for a correct solution.
2. Time Penalty: 1 point is deducted for every 10 seconds elapsed since the level start time (stored in session['level_start_time']).
3. Hint Penalty: A fixed deduction defined by the penalty key in level_manager.py. The system enforces a minimum score of 30-50 points to ensure progress is still rewarded.

Sources: [routes/submit_routes.py:50-61](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/submit_routes.py#L50-L61), [routes/arena_routes.py:86-90](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/arena_routes.py#L86-L90)

Integrating New Levels into the UI

The UI dynamically adapts to the contents of the LEVELS dictionary. The dashboard route iterates through the keys to generate level cards, while the arena.html template uses Jinja2 to inject level-specific metadata.

Dashboard Integration

The dashboard route sorts the levels by ID to ensure a linear display. It applies CSS classes like grayscale and opacity-50 to locked levels, and active-pulse to the team's current target.

# routes/arena_routes.py
levels_list = []
for level_id, data in LEVELS.items():
    levels_list.append({
        'id': level_id,
        'name': data['title'],
        'difficulty': data['difficulty']
    })
levels_list.sort(key=lambda x: x['id'])

Sources: [routes/arena_routes.py:22-32](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/arena_routes.py#L22-L32), [templates/dashboard.html:48-60](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/templates/dashboard.html#L48-L60)

Final Challenge Handling

The final level (default ID 8) triggers a unique state. In arena.html, the success modal logic checks if the level_id is 8 to change the "Return to Dashboard" button into a "Claim Final Victory" button leading to /victory.

Sources: [templates/arena.html:171-177](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/templates/arena.html#L171-L177), [routes/arena_routes.py:129-137](https://github.com/Priyadharshan-19/python-debug-arena/blob/5d1642f9afac53e43d3bd14af02e6f91c05a54da/routes/arena_routes.py#L129-L137)

Conclusion

Customizing levels involves modifying the LEVELS dictionary in levels/level_manager.py. By defining unique code bugs, expected outputs, and hint penalties, administrators can scale the arena's difficulty from basic syntax errors to complex algorithmic challenges like Matrix Transposition or Fibonacci optimization. The system's decoupling of level data from routing logic ensures that the platform remains highly extensible for various competitive formats.