> 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/contest-configuration.md).

# Contest Configuration

How to configure and customize Battle Mode parameters, candidate pools, voting limits, and anti-flood options.

Battle Mode is configured directly at the contest level, allowing you to run standard voting contests, rating contests, and pairwise battle contests alongside each other on the same website.

***

### Enabling Battle Mode

To activate Battle Mode for a contest:

1. Navigate to **NorrCompetition > Contests** in the Joomla administrator area and edit an existing contest (or create a new one).
2. Go to the **Basic Options** tab and locate the **Voting Options** section.
3. Set **Voting Mode** (`vote_mode`) to **Battle** (`battle`).

{% hint style="info" %}
**Global Component Defaults:**\
You can also configure global default values for all new contests by going to **NorrCompetition > Options** and opening the **Contests** tab.
{% endhint %}

***

### Battle Parameters

When **Voting Mode** is set to **Battle**, the form dynamically displays dedicated battle configuration parameters:

| Parameter                | Field Name                   | Values / Range | Default     | Description                                                                         |
| ------------------------ | ---------------------------- | -------------- | ----------- | ----------------------------------------------------------------------------------- |
| **Battle Pool Size**     | `battle_pool_size`           | 2 – 100        | `20`        | Number of lowest-displayed entries to randomly pick comparison pairs from.          |
| **Results Top Percent**  | `battle_results_top_percent` | 1 – 100%       | `30`        | Percentage of top-ranked entries to display in the public results leaderboard.      |
| **Skip Pairs**           | `battle_allow_skip`          | *Yes* / *No*   | *Yes* (`1`) | Allow voters to skip the current pair without voting.                               |
| **Vote Cancel Duration** | `battle_undo_duration`       | 1 – 60 seconds | `5`         | Duration in seconds to show the vote cancel notification (Undo toast) after voting. |

<figure><picture><source srcset="https://4110454137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FemWP543OtNCmlHpJBjKV%2Fuploads%2Fgit-blob-f2bec118b79589e09163425de54d61750ca0cb59%2Fbattle-mode-contest-voting-options-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://4110454137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FemWP543OtNCmlHpJBjKV%2Fuploads%2Fgit-blob-03a10bbe3938f009a62940fac417ce20d744b25e%2Fbattle-mode-contest-voting-options-light.png?alt=media" alt="NorrCompetition Battle Mode Contest Voting Options"></picture><figcaption><p>Contest Voting Options fieldset configured with Battle Mode parameters</p></figcaption></figure>

#### 1. Battle Pool Size (`battle_pool_size`)

Controls the candidate sampling window used by the pairing algorithm:

* The system identifies the active, approved entries that currently have the lowest display counts.
* From this candidate pool, the weighted algorithm samples pairs for voters.
* A smaller pool (e.g., 10–15) balances exposure rapidly by focusing duels on the least-shown entries. A larger pool (e.g., 30–50) increases pair variety across the participant roster.

#### 2. Results Top Percent (`battle_results_top_percent`)

Determines which entries qualify for the public Leaderboard table when the contest concludes:

* Calculated using the formula: $$\text{Cutoff Count} = \left\lceil \text{Total Evaluated Entries} \times \frac{\text{Top Percent}}{100} \right\rceil$$
* For example, with 100 evaluated entries and a 30% setting, the top 30 participants appear on the final leaderboard. There is a guaranteed minimum of at least 1 entry displayed.

#### 3. Skip Pairs (`battle_allow_skip`)

* When enabled, a **Skip** button appears in the arena interface.
* Clicking Skip requests a fresh candidate pair without casting a vote, creating a log record, or incrementing candidate display counters.

#### 4. Vote Cancel Duration (`battle_undo_duration`)

* Sets the lifetime (in seconds) of the floating notification shown after each cast vote.
* Requires the general **Unvote Period** (`vote_unvote_period`) setting to be greater than 0 and the user to hold the `core.unvote` permission.

***

### Voting Limits & Rules

Battle Mode uses NorrCompetition's unified vote limiting and anti-flood system:

#### Votes per Contest (`competition_allowed_votes`)

Located under **Contest Voting Options**:

* **0 (Unlimited):** Voters can continue comparing pairs until all possible pair combinations have been evaluated.
* **Positive integer (e.g. 10):** Limits each voter (registered user or guest) to the specified number of duels in that contest.
* When active, voters see a live counter in the arena (e.g., *Guest mode: 3 of 10 votes used*). Once the limit is reached, the arena presents a friendly lockout card prompting guests to log in or register to participate further.

#### Registered User Protections

* **Anti-Self-Vote:** The pair selection algorithm automatically suppresses any pair that includes an entry authored by the currently logged-in user.
* **Duplicate Pair Prevention:** The system remembers already evaluated pairs for each user. A registered user will never be presented with the same pair twice.

#### Guest Identification & Security

Unauthenticated guest voters are identified through a secure multi-factor verification system:

* **Persistent Cookie & Storage:** A secure persistent cookie (`nc_battle_voter`) valid for 365 days, automatically mirrored in browser local storage to prevent accidental data loss.
* **IP Address Checking (`vote_check_ip`):** When enabled in contest options, the client's IP address is bound to the voter verification key.
* **Fingerprint Checking (`vote_check_fingerprint` / `vote_track_data`):** When enabled, device and browser characteristics are incorporated into verification.
* **Cryptographic Verification:** The system computes a secure cryptographic hash across all active verification factors to accurately enforce guest vote limits and prevent voting manipulation.
