> For the complete documentation index, see [llms.txt](https://docs.norrnext.com/norrcompetition/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.norrnext.com/norrcompetition/battle-mode/overview.md).

# Overview

Learn about the pairwise Battle Mode in NorrCompetition for interactive duel voting and fair contestant evaluation.

**Battle Mode** is an interactive voting mode built natively into NorrCompetition (available in version 3.1.0 and higher). Instead of traditional single-click voting or numerical star ratings, Battle Mode presents site visitors with head-to-head pairs of entries side-by-side in a dynamic duel arena.

Voters compare two contenders at a time, selecting their preferred entry or declaring a tie. Each comparison updates scores and immediately loads a new pair without reloading the page.

***

### Key Capabilities

* **Pairwise Duel Format:** Visitors compare two entries at a time, creating an engaging experience that drives higher voting participation.
* **Universal Contest Compatibility:** Works across all supported contest types: **Photo**, **Video** (with responsive video players and thumbnails), and **Simple** (text-based entries and custom fields).
* **Fair Play Algorithm:** Uses an inverse display-count weighting system to prioritize entries that have been displayed fewer times, ensuring all participants receive balanced exposure regardless of when they entered the contest.
* **Normalized Rating Metric:** Ranks participants by the quality of user preferences rather than raw volume of impressions, calculating the final rating as: $$\text{Rating} = \frac{\text{Battle Points}}{\text{Display Count}}$$
* **Instant Interactivity & Hotkeys:** Instant pair replacement with zero full-page reloads, supported by full keyboard navigation (number keys, arrow keys, spacebar, skip, and undo).
* **Vote Undo Mechanism:** A configurable floating notification allows voters to quickly cancel accidental choices within a defined time window.
* **Automated Lifecycle Transitions:** While voting is open, the contest displays the active duel **Arena**. Once voting ends, the contest automatically transitions to the ranked **Leaderboard** displaying the top percentage of finalists.
* **Adaptive Entry View:** Individual entry pages automatically adapt to Battle Mode: showing a call-to-action button directing visitors to the Arena during active voting, and presenting rank and performance statistics once the contest is completed.

***

### Contest Lifecycle in Battle Mode

Battle Mode seamlessly integrates into the standard NorrCompetition contest timeline using existing date parameters:

```
[Submission Period] ──▶ [Active Battle Arena] ──▶ [Completed Leaderboard]
  (start_time /           (vote_start_date /        (vote_end_date reached /
   end_time)               vote_end_date)            status = Completed)
```

1. **Submission Period:** Contestants submit entries according to standard contest options, category assignments, and moderation rules.
2. **Voting Period (Active Battle Arena):** When the voting window opens, visiting the contest renders the pairwise Arena interface. Visitors evaluate pairs until they reach their voting limit or evaluate all available matchups.
3. **Completed Contest (Results Leaderboard):** Once the voting window closes or the administrator marks the contest as completed, the view automatically switches to the results layout, displaying the ranked Leaderboard for the configured top percentage of contenders.
