> 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/scoring-and-leaderboard.md).

# Scoring & Leaderboard

Understand the mathematical ranking formulas, fair play pair selection algorithm, and completed contest leaderboard.

Battle Mode evaluates contenders through competitive matchups and calculates standings using a normalized mathematical rating. This approach guarantees fair outcomes even when entries receive unequal total numbers of views.

***

### The Fair Play Pair Selection Algorithm

In standard pairwise voting systems, purely random pair selection creates major imbalances: early submissions get shown hundreds of times, while submissions added later in the contest get shown only a handful of times.

NorrCompetition eliminates this issue using an **intelligent inverse-weighted pair selection engine**:

#### 1. Candidate Pool Filtering

The system identifies all active, published entries in the contest, sorted by their current display count in ascending order. It limits this group to the number specified in **Battle Pool Size** (`battle_pool_size`, default: 20).

#### 2. Inverse Weighting

Each candidate entry in the pool is assigned an inverse selection weight based on how many times it has already been presented to voters:

$$\text{Weight}\_i = \frac{1}{\text{Display Count}\_i + 1}$$

* An entry with **0 displays** has a weight of $1.0$.
* An entry with **9 displays** has a weight of $0.1$.
* An entry with **19 displays** has a weight of $0.05$.

Entries with fewer impressions have a significantly higher probability of being chosen for the next duel.

#### 3. Weighted Pair Sampling & Evaluation History

The engine samples pairs using the calculated weight distribution:

* It verifies that the prospective pair has not already been evaluated by the current voter.
* It verifies that the pair does not include an entry submitted by the current registered voter (anti-self-vote).
* The algorithm performs weighted random sampling to find fresh pairings. If no unrated pair is found through random sampling, it falls back to a systematic check across the pool.
* Once a pair is chosen, the left and right positions are randomized to eliminate positional bias.

***

### The Normalized Rating Formula

Points are awarded per duel as follows:

| Duel Outcome   | Points Allocated                |
| -------------- | ------------------------------- |
| **Winner**     | `+1.0` point                    |
| **Draw (Tie)** | `+0.5` points to each contender |
| **Loser**      | `+0.0` points                   |

The final standing of each entry is determined by its **normalized rating**:

$$\text{Battle Rating} = \frac{\text{Battle Points}}{\text{Display Count}}$$

#### Why Normalized Rating is Fairer

Consider two entries in a photo contest:

* **Photo A:** Appeared in **10 battles**, won 9 times, lost 1 time.
  * *Points:* $9.0$
  * *Rating:* $9.0 / 10 = \mathbf{0.90}$ (90% win rate)
* **Photo B:** Appeared in **100 battles**, won 70 times, lost 30 times.
  * *Points:* $70.0$
  * *Rating:* $70.0 / 100 = \mathbf{0.70}$ (70% win rate)

Under simple points addition, Photo B would win purely because it had more total appearances. Under NorrCompetition's normalized rating, **Photo A ranks higher** because voters preferred it in a significantly larger proportion of its matchups.

***

### Leaderboard Sorting & Tie-Breaking

When calculating standings, the component applies a strict three-tier hierarchy:

1. **Primary Sort — Highest Battle Rating:** Entries with higher ratings rank above those with lower ratings.
2. **First Tie-Breaker — Most Displays:** If two entries have the identical rating (e.g., both have 0.80), the entry with more displays ranks higher, reflecting greater statistical reliability.
3. **Second Tie-Breaker — Earlier Submission:** If both rating and display count are identical, the entry submitted earlier receives priority.

***

### The Completed Battle Leaderboard

When the contest reaches its end date (`vote_end_date`) or the administrator marks the contest as **Completed**, the contest automatically switches from the Arena to the **Battle Results Leaderboard**:

#### Results Top Percent Cutoff

To keep the public leaderboard focused on the top contenders, NorrCompetition applies the **Results Top Percent** (`battle_results_top_percent`, default: 30%):

$$\text{Displayed Entries} = \max\left(1, ; \left\lceil \text{Total Evaluated Entries} \times \frac{\text{Top Percent}}{100} \right\rceil\right)$$

A summary line at the top of the leaderboard informs visitors:

> *Showing Top 30% ranked entries (Total participants in battles: 42)*

#### Leaderboard Table Elements

The results leaderboard table includes comprehensive performance metrics for each qualifying finalist:

* **Rank:** Visual medal badges for top finishes:
  * 🥇 **1** — First Place
  * 🥈 **2** — Second Place
  * 🥉 **3** — Third Place
  * Muted numerical badges (`#4`, `#5`, etc.) for subsequent ranks.
* **Entry:** The entry's thumbnail image (linking to the full entry page), title link, and author name (if submitter visibility is enabled in contest options).
* **Rating:** A visual progress bar displaying the relative percentage, accompanied by the exact rating value formatted to two decimal places (e.g. `0.88`).
* **Points:** Total cumulative battle points awarded (e.g., `14.5`).
* **Displays:** Total number of times the entry appeared in duels (e.g., `16`).

<figure><img src="https://4110454137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FemWP543OtNCmlHpJBjKV%2Fuploads%2Fgit-blob-ee40bdda00ae8a1105a8a3ac9168810f2bb5d901%2Fbattle-mode-leaderboard-results-light.png?alt=media" alt="NorrCompetition Battle Mode Results Leaderboard"><figcaption><p>The completed battle contest leaderboard featuring podium rankings, ratings, and duel statistics</p></figcaption></figure>

***

### Entry Card Completed State

When a visitor opens an individual entry page for a completed battle contest, the adaptive widget summarizes the entry's final results:

* **Placement Badge:** Displays the medal or badge with overall placement (e.g., `🥈 #2 of 42 participants`).
* **Win Rate Percentage:** Displays the rounded percentage win rate (e.g., `85% Win Rate`).
* **Detailed Breakdown:** Shows the accumulated points and total duel impressions.
