Timer & Client State
Relevant source files
The following files were used as context for generating this wiki page:
The Timer & Client State system in the Debug Arena manages real-time competitive metrics and session-based progression tracking. It ensures that participant performance is accurately timed for scoring purposes while maintaining a secure, persistent state across different levels of the arena.
This system is integrated with the Proctoring & Anti-Cheat System to enforce environment integrity and the Evaluation Engine to calculate time-based penalties during code submission.
Timer Implementation
The platform utilizes two distinct timing mechanisms: a client-side visual timer for user feedback and a server-side session timer for high-precision scoring and validation.
Client-Side Visual Timer
The UI provides a live "Elapsed" time display within the arena. This is managed by a simple interval-based JavaScript function that updates every second to show minutes and seconds.
let seconds = 0;
const timerDisplay = document.getElementById('timer-display');
setInterval(() => {
seconds++;
let mins = Math.floor(seconds / 60);
let secs = seconds % 60;
timerDisplay.innerText = `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
}, 1000);
Sources: static/js/timer.js:1-10, templates/arena.html:15-18
Server-Side Session Timing
To prevent client-side manipulation, the actual level_start_time is stored in the Flask session when a user enters a specific level. This timestamp is used upon submission to calculate the total duration spent on a challenge.
| Variable | Location | Description |
|---|---|---|
level_start_time | Flask Session | Unix timestamp set when a level route is initialized. |
current_level_id | Flask Session | Tracks which level the timer is currently active for to prevent reset on page refresh. |
time_taken | Submission Logic | Calculated as current_time - level_start_time during submission. |
Sources: routes/arena_routes.py:65-68, routes/submit_routes.py:46-49
Client State Management
Client state is maintained through a combination of browser sessionStorage and Flask server-side sessions. This state is critical for controlling navigation flow and enforcing security protocols.
Navigation and Initialization Flags
The platform uses sessionStorage to distinguish between legitimate internal navigation (e.g., moving from the dashboard to a level) and unauthorized environment exits (e.g., closing the tab or refreshing).
arena_initialized: Set totruewhen the user clicks "ENTER ARENA" on the dashboard. It hides the fullscreen entry overlay for the remainder of the session.is_navigating: A temporary flag set during thebeforeunloadevent. It instructs the proctoring script to ignore the subsequent loss of focus or fullscreen exit during page transitions.
Sources: templates/dashboard.html:112-125, static/js/proctor.js:7-10, static/js/proctor.js:70-74
State Workflow Diagram
The following diagram illustrates how client state and timers are initialized and transitioned during a challenge.
The diagram shows the transition from the Dashboard initialization to the calculation of time-based penalties during the submission phase.
Sources: templates/dashboard.html:103-110, routes/arena_routes.py:65-68, routes/submit_routes.py:46-55
Scoring & Time Penalties
The time recorded by the server-side state is a primary factor in the base scoring logic for every level.
- Base Points: Each level starts with a baseline of 100 points.
- Decay Logic: For every 10 seconds elapsed (as determined by the session timer), 1 point is deducted.
- Score Floor: The level score cannot drop below 50 points based on time alone, though hint penalties can reduce this further to a hard minimum of 30 points.
# BASE SCORING
base_points = 100
time_penalty = time_taken // 10 # -1 point per 10 seconds
level_score = max(50, base_points - time_penalty)
Sources: routes/submit_routes.py:51-55
Summary
The Timer & Client State system provides a robust framework for competitive integrity. By combining server-side session timestamps with client-side state flags (is_navigating, arena_initialized), the platform accurately calculates performance-based scores while differentiating between user-driven navigation and potential security violations.