> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rbxweb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Competition

> Run image-based competitions with reaction voting, automatic winner selection, reminders, and status updates.

A competition is a timed contest where members submit images in a chosen channel and others vote with a reaction emoji. When the timer ends, the bot selects winners automatically (highest vote count) or hands off to a moderator for a manual pick.

Open **Dashboard → Competition**. Multiple cards cover different parts of the flow: core settings, winner announcement, reminder and status updates, and access / premium options.

## Lifecycle

<Steps>
  <Step title="Configure settings">
    Fill in the core settings, winner announcement embed, and optional reminder. Save.
  </Step>

  <Step title="Click Start Competition">
    The bot posts the competition embed in the chosen channel and starts the timer.
  </Step>

  <Step title="Members submit and vote">
    Members upload images to the competition channel. Others react with the configured emoji to vote.
  </Step>

  <Step title="Competition ends">
    When the end time hits, the bot picks winners per the configured mode, posts the winner announcement, optionally runs reminders and random-voter reveals.
  </Step>
</Steps>

Use `/competition_control` in Discord to stop a running competition, check its status, or force-end early.

## Core settings

<ResponseField name="Announcement Message" type="message/embed editor">
  The opening embed posted when the competition starts, composed in the shared message/embed editor and prefilled with a template. The default template links the title to the competition channel (via `{comp_channel_url}`), which is what makes Discord render it as a blue clickable title rather than plain white — clear the title link if you'd rather it stay white. Insert dynamic values from the **Variables** button — `{comp_title}`, `{comp_theme}`, `{comp_ends}`, `{comp_winners}`, `{comp_prize_1}`…, `{reaction_emoji}`, `{mod_bypass_code}`. The settings below always drive the competition, whether or not their tokens appear in the template.
</ResponseField>

<ResponseField name="Competition Title" type="text (required, 256 chars)">
  Headline of the competition. Available in any template as `{comp_title}`.
</ResponseField>

<ResponseField name="Theme" type="text (optional, 256 chars)">
  Guiding theme entries should follow. Available as `{comp_theme}`.
</ResponseField>

<ResponseField name="Prize per winner" type="one optional prize per winner (up to 10)">
  One prize row per winner, matched by place — the **1st-place** prize goes to the top winner, **2nd place** to the runner-up, and so on. The rows automatically follow the **Number of Winners** field, and each is optional (leave a row blank to give that winner no prize). Each prize is available as `{comp_prize_1}` … `{comp_prize_N}`, or use `{winner_prizes}` in the winner announcement to list every winner with their prize automatically.
</ResponseField>

<ResponseField name="Competition Channel" type="channel picker (required)">
  Where entries are submitted, votes are cast, and the opening embed is posted.
</ResponseField>

<ResponseField name="End Date & Time" type="date + time (required)">
  When the competition ends. Interpreted in your local timezone. Shown on its own row.
</ResponseField>

<ResponseField name="Vote Reaction Emoji" type="standard Discord emoji (required)">
  The reaction members use to vote. Only one emoji; only standard Discord emoji (not custom server emoji). Shown on its own row.
</ResponseField>

<ResponseField name="Number of Winners" type="number, 1 to 10 (required)">
  How many winners are picked when the competition ends.
</ResponseField>

### Winner selection mode

<ResponseField name="Winner Selection Mode" type="select">
  **Automatic** — bot picks the top N entries by vote count.
  **Moderator Pick** — after voting ends, a mod selects winners from the top entries via a button.
</ResponseField>

#### Automatic mode sub-settings

<ResponseField name="Tiebreak Mode" type="select">
  **Random** — pick randomly among tied entries.
  **Reaction Poll** — post a new poll for the tied entries and let voters decide the winner.
</ResponseField>

<ResponseField name="Poll Duration (hours)" type="number, 1 to 48">
  Only shown when tiebreak is Reaction Poll. How long the tiebreak poll lasts.
</ResponseField>

<ResponseField name="Tie-Break Ping Roles" type="role list (optional)">
  Roles mentioned when a tiebreak poll starts.
</ResponseField>

#### Moderator-pick mode sub-settings

<ResponseField name="Moderator Ping Role" type="role picker (optional)">
  Role mentioned when the mod-pick prompt appears.
</ResponseField>

<ResponseField name="Allowed Moderators" type="role list (optional)">
  Roles allowed to click the winner-pick button. Leave empty to allow all admins.
</ResponseField>

## Winner announcement

The winner announcement is composed in the shared message/embed editor, prefilled with a ready-made template you can edit or replace. The default template uses `{winner_prizes}`, so each winner and their prize show up automatically — no manual token wiring needed. Insert dynamic values from the **Variables** button — the bot fills them in when winners are announced:

| Token                               | Value                                                                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `{winner}` / `{winner_name}`        | Mentions / names of all winners                                                                                                   |
| `{winner_prizes}`                   | A formatted list pairing every winner with their place-based prize (medal · mention · votes · 🎁 prize) — in the default template |
| `{winner_image}`                    | The top winner's submitted image — drop it in the editor's image slot                                                             |
| `{votes}`                           | The top winner's vote count                                                                                                       |
| `{rankings}`                        | A formatted medal / vote / submission-link list of every winner (no prizes)                                                       |
| `{comp_title}` / `{comp_theme}`     | Competition title / theme                                                                                                         |
| `{comp_prize_1}` … `{comp_prize_N}` | Prize for the N-th place winner (matches Number of Winners)                                                                       |
| `{competition}`                     | Link back to the competition                                                                                                      |

<ResponseField name="Custom identity" type="toggle (Booster / Premium)">
  Post the announcement under a custom name & avatar via a webhook, instead of the bot's normal identity. Requires the **Manage Webhooks** permission.
</ResponseField>

<ResponseField name="Announcement Channel" type="channel picker (optional)">
  Where the announcement is posted. Defaults to the competition channel if left empty.
</ResponseField>

<ResponseField name="Add Role to Winner" type="role list (up to 4)">
  Roles assigned to each winner when the competition ends. Useful for giving winners a badge or access role.
</ResponseField>

## Pre-end reminder and status updates

These are two independent messages, each on its own tab of the card. A reminder is a single embed posted N minutes before the end. Status updates are periodic standings posted at a regular interval while the competition runs. Both timings are in minutes and are checked against the **End Date & Time** — a value longer than the competition itself is rejected. Each tab has its own enable toggle and its own message editor — you can run status updates without a reminder, and vice versa.

### Reminder

The reminder is composed in the shared message/embed editor, prefilled with a template. Insert dynamic values from the **Variables** button — `{hours}` (hours left), `{comp_ends}`, `{comp_title}`, `{comp_theme}`, `{comp_winners}`, `{comp_prize_1}`…, `{competition}`. Set the reminder image in the editor's image slot.

<ResponseField name="Enable reminder" type="toggle">
  Master switch for the reminder embed.
</ResponseField>

<ResponseField name="Custom identity" type="toggle (Booster / Premium)">
  Post the reminder under a custom name & avatar via a webhook. Requires the **Manage Webhooks** permission.
</ResponseField>

<ResponseField name="Minutes Before End" type="number, minimum 1 (default 120)">
  How many **minutes** before the competition ends to post the reminder — 120 = 2 hours. It must be shorter than the competition itself: a reminder set further back than the competition is long would fire before it even starts. The field turns red and the competition won't start if it doesn't fit the **End Date & Time**.
</ResponseField>

<ResponseField name="Reminder Channel" type="channel picker (optional)">
  Where the reminder is posted. Defaults to the competition channel.
</ResponseField>

### Status updates

The status update is composed in the shared message/embed editor, prefilled with a template that reproduces the standings embed the bot posted before it was configurable. Insert dynamic values from the **Variables** button:

| Token                               | Value                                                                                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `{entry_count}`                     | How many entries have been submitted so far                                                                                                            |
| `{entries}`                         | The standings — one line per entry with the member, their vote count and a link to their submission (capped at the top 20, with an "…and N more" line) |
| `{competition}`                     | Link back to the competition / rules                                                                                                                   |
| `{reaction_emoji}`                  | The vote reaction emoji                                                                                                                                |
| `{comp_id}`                         | The competition's ID, zero-padded (`012`) — every default footer starts with `[ID:#{comp_id}]`                                                         |
| `{comp_title}` / `{comp_theme}`     | Competition title / theme                                                                                                                              |
| `{comp_winners}`                    | Number of winners                                                                                                                                      |
| `{comp_ends}` / `{hours}`           | End time / hours left                                                                                                                                  |
| `{comp_prize_1}` … `{comp_prize_N}` | Prize for the N-th place winner                                                                                                                        |

<Note>
  Status updates always post through a webhook. When **Custom identity** is off (or the server isn't Booster/Premium), the bot hands the webhook its own name and avatar, so the message looks exactly as it always has. Without the **Manage Webhooks** permission the bot falls back to a normal send.
</Note>

<ResponseField name="Enable status updates" type="toggle">
  Master switch for status updates. Independent of the reminder toggle.
</ResponseField>

<ResponseField name="Custom identity" type="toggle (Booster / Premium)">
  Post the status update under a custom name & avatar. Requires the **Manage Webhooks** permission.
</ResponseField>

<ResponseField name="Interval (minutes)" type="number, minimum 1 (default 120)">
  How often the standings are posted during the competition — 120 = every 2 hours. It must be shorter than the competition itself, or no update would ever post. The field turns red and the competition won't start if it doesn't fit the **End Date & Time**.
</ResponseField>

<ResponseField name="Updates Channel" type="channel picker (optional)">
  Where standings are posted. Defaults to the competition channel.
</ResponseField>

## Other settings

<ResponseField name="Allowed Participant Roles" type="role list (optional)">
  Only members with at least one of these roles can submit entries or vote. Leave empty to allow everyone.
</ResponseField>

<ResponseField name="Banned Roles" type="role list">
  Members with any of these roles are blocked from entering or voting. Admins are exempt.
</ResponseField>

<ResponseField name="Image Only During Competition" type="toggle">
  While the competition is running, non-image messages are deleted from the competition channel.
</ResponseField>

<ResponseField name="Bypass Code" type="text (optional)">
  A code like `$novote` that mods can include in a message to bypass the image-only filter. Only works for moderators and above.
</ResponseField>

<ResponseField name="Lock channel on End" type="toggle">
  After the competition ends, the channel is locked so members can no longer post.
</ResponseField>

<ResponseField name="Lock Bypass Roles" type="role list (optional)">
  Roles that can still post after the channel is locked. Admins are always exempt.
</ResponseField>

<ResponseField name="Minimum Server Age Gate" type="toggle + number">
  Require members to have been in the server for at least N days before voting or entering. Useful against raid accounts.
</ResponseField>

<ResponseField name="Votes Log" type="toggle + channel picker">
  When on, every vote cast or removed is logged to the chosen channel. Useful for auditing fairness.
</ResponseField>

<ResponseField name="Random Voter Selection" type="toggle">
  After the winner is announced, the bot picks a random voter from the winning entry's reactions and reveals their identity in a 3-step animated sequence. Good for a second prize.
</ResponseField>

### Private threads

<ResponseField name="Create private thread for the winner" type="toggle + sub-settings">
  When a competition ends, the bot creates a private thread for the winner(s) inside a chosen parent channel.

  Sub-settings:

  * **Thread parent channel** — where the thread is created.
  * **Thread archive duration** — 1 hour, 1 day, or 3 days.
  * **Thread layout** — single shared thread for all winners, or one thread per winner.
  * **Extra users to invite** — paste user IDs of staff who should also have access (the server owner is added automatically).
</ResponseField>

<ResponseField name="Private thread for random voter" type="toggle + sub-settings">
  Same pattern as the winner thread, but for the random voter chosen by Random Voter Selection. Requires Random Voter Selection to also be enabled at runtime.
</ResponseField>

<Warning>
  Threads inherit permissions from the parent channel. Make sure the parent channel is visible to the winner(s) / voter and allows them to send messages, or they won't see the thread.
</Warning>

## Presets

If your plan includes preset quota, the **Load Preset** and **Save as Preset** cards appear at the top and bottom of the page. Save a fully-configured competition once, then fill the entire form with a single click the next time. Presets are per-server.

## Control from Discord

`/competition_control` has sub-commands for:

* `status` — show time remaining, entry count, top entries.
* `stop` — end the competition immediately (picks winners as if time had expired).
* `cancel` — stop and discard without picking winners.