> 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/arena-experience.md).

# Arena Experience

Explore the Battle Arena interface, interactive controls, transitions, hotkeys, and the undo mechanism.

When a contest is configured with **Voting Mode** set to **Battle**, navigating to the contest on the frontend automatically opens the dedicated **Battle Arena**.

***

### The Battle Arena Interface

The Battle Arena displays contenders side-by-side in a responsive, two-column matchup view:

* **Left & Right Candidate Cards:** Each card showcases the entry's primary photo or video player, entry title, submitter name (if enabled in contest options), and assigned custom fields.
* **Side Randomization:** The positioning of entries (which entry is placed on the left vs. right) is randomized during pair generation to prevent positional bias.
* **Responsive Layout:** On desktop screens, entries sit side-by-side in equal-height cards; on mobile devices, cards stack seamlessly with large touch-friendly action buttons.

<figure><img src="https://4110454137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FemWP543OtNCmlHpJBjKV%2Fuploads%2Fgit-blob-983d29f035a631ac730f05e50b4ac6536a14999b%2Fbattle-mode-arena-duel-cards-light.png?alt=media" alt="NorrCompetition Battle Arena Matchup View"><figcaption><p>The Battle Arena matchup view with side-by-side contender cards, voting actions, and hotkeys</p></figcaption></figure>

***

### Voting Actions & Controls

The Arena provides three primary voting actions arranged across the voting bar:

| Action Button    | Points Awarded                                                         | Description                                     |
| ---------------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
| **Choose Left**  | <p><strong>Left:</strong> 1.0 pt<br><strong>Right:</strong> 0.0 pt</p> | Casts a win for the left contender.             |
| **Tie**          | <p><strong>Left:</strong> 0.5 pt<br><strong>Right:</strong> 0.5 pt</p> | Declares an equal draw between both contenders. |
| **Choose Right** | <p><strong>Left:</strong> 0.0 pt<br><strong>Right:</strong> 1.0 pt</p> | Casts a win for the right contender.            |

#### Secondary Actions

* **Skip:** Visible when **Skip Pairs** (`battle_allow_skip`) is enabled in contest options. Clicking Skip instantly loads a new pair without casting a vote, creating a record, or changing contender display counters.
* **Finish Voting:** Provides an exit link that takes the user back to the main contests directory.

***

### Keyboard Shortcuts (Hotkeys)

To enable rapid comparisons, the Arena includes built-in keyboard navigation:

| Key Shortcut                         | Action         | Condition          |
| ------------------------------------ | -------------- | ------------------ |
| `1` or `←` (Left Arrow)              | Choose Left    | Voting enabled     |
| `2`, `Spacebar`, or `↓` (Down Arrow) | Declare Tie    | Voting enabled     |
| `3` or `→` (Right Arrow)             | Choose Right   | Voting enabled     |
| `S`                                  | Skip Pair      | Skip Pairs enabled |
| `Z` or `Ctrl + Z`                    | Undo Last Vote | Undo window active |

A contextual hint displaying available keyboard shortcuts is shown above the arena cards so visitors know they can use hotkeys.

***

### Seamless Transitions Without Page Reload

All interactions in the Arena take place in real time without refreshing the page:

1. Clicking an action button registers the decision instantly in the background.
2. Contender scores and impression counters are updated immediately.
3. The Arena smoothly transitions to the next pair of contenders, creating a continuous voting experience.

***

### Floating Undo Notification (Undo Toast)

When a vote is cast and **Vote Cancel Duration** is greater than 0, a floating notification appears at the bottom of the arena:

* Displays a live countdown timer: `Vote registered. [ Unvote (5) ]`.
* Clicking **Unvote** (or pressing `Z` / `Ctrl+Z`) cancels the decision immediately.
* The system deducts the awarded points and reverts the display counts for both contenders.
* The notification automatically disappears once the countdown reaches zero.

<figure><img src="https://4110454137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FemWP543OtNCmlHpJBjKV%2Fuploads%2Fgit-blob-93d596a971594096e4541e8a39ae793bfdb2d072%2Fbattle-mode-arena-undo-toast-light.png?alt=media" alt="NorrCompetition Battle Arena Floating Undo Toast"><figcaption><p>Floating undo notification with a live countdown timer</p></figcaption></figure>

***

### Arena States & Notices

The Arena dynamically displays status notices based on the voter's context:

#### 1. Live Vote Counter

If **Votes per Contest** (`competition_allowed_votes`) is configured with a limit, a blue informational banner displays the voter's current usage:

> *Guest mode: 2 of 5 votes used.*

#### 2. Voting Limit Reached (Lockout State)

When a voter reaches the contest limit, the cards are replaced with a lockout notice:

* **Guests:** Displays a message prompting the user to log in or register to cast further votes.
* **Registered Users:** Informs the user that their maximum allocated votes have been reached, with a button to return to the contests list.

#### 3. All Evaluated State

If a registered voter has evaluated every possible pair combination in the candidate pool:

> *You have evaluated all available pairs! Check back later.*

#### 4. Insufficient Participants State

If a battle contest has fewer than 2 approved, published entries, the arena notifies visitors:

> *Not enough active entries to generate a battle pair.*

***

### Adaptive Single Entry View Widget

When a visitor opens the individual details page of an entry belonging to an active Battle Mode contest:

* The standard single-click vote button or star rating widget is automatically hidden.
* It is replaced by an adaptive **Battle Mode Widget** featuring a clear call to action:
  * Title: **Battle Mode Active ⚔️**
  * Description: Explains that entries in this contest are evaluated through pairwise duels in the arena.
  * Button: **Go to Battle Arena ⚔️**, directing visitors directly to the contest arena.
  * Social sharing buttons (if enabled in contest options) allowing visitors to share the entry.
