.. include:: ../variables.rst
.. _challenges-badges:

Badges
======

Badges are the visible trophies winners earn. Each badge has a name, icon, colour, and optional
tier. Badges live in a catalogue that is shared across the corporation (or globally, if
``corporation = 0``).

.. figure:: /images/challenges/lightmode/badge-list.png
   :align: center
   :width: 100 %

|br|

Opening the page
----------------

Left menu: :blue:`Challenges` ▸ :blue:`Badges`.

Creating a badge
----------------

Click :blue:`+ New Badge`. The editor asks for:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Meaning
   * - **Name**
     - Displayed on the participant's profile, in notifications, and on the leaderboard.
   * - **Description**
     - Short explanation -- helpful on the participant profile tooltip.
   * - **Icon**
     - Any Bootstrap Icon class, e.g. ``bi-trophy-fill``, ``bi-award-fill``, ``bi-star-fill``.
       Preview appears next to the field as you type.
   * - **Colour**
     - Hex colour for the icon. Pick something that matches your corporate palette.
   * - **Tier**
     - 0 = none, 1 = Bronze, 2 = Silver, 3 = Gold, 4 = Platinum. Used for visual sorting on
       profile pages and to drive "rank up" auto-award rules.
   * - **Status**
     - Active or Inactive. Inactive badges are hidden from challenge-reward dropdowns but remain
       attached to whoever has already won them.

.. figure:: /images/challenges/lightmode/badge-editor.png
   :align: center
   :width: 80 %

|br|

Assigning a badge to a challenge
--------------------------------

Open the :ref:`challenges-detail` editor, set **Reward badge** to the one you want, and save.
When the challenge is closed every winner receives one copy of the badge.

Global versus corporation badges
--------------------------------

A badge with ``corporation = 0`` is **global** -- available to every corporation on the server.
The default seed data ships with five global badges:

* Gold Winner (`bi-trophy-fill`, amber)
* Silver Medal (`bi-award-fill`, slate)
* Bronze Medal (`bi-patch-check-fill`, brown)
* Streak Star (`bi-star-fill`, green)
* Most Improved (`bi-graph-up-arrow`, blue)

Badges created from the UI are scoped to the current corporation.

Deleting (soft delete)
----------------------

:blue:`Delete` on a badge does **not** remove it from the database. It flips the ``active`` flag
to 0. This protects the audit trail: if a badge has already been awarded to winners, those
awards remain intact and still render correctly on the profile page.

To see inactive badges in the list, toggle :blue:`Include inactive` in the toolbar.

Next step
---------

Badges get far more interesting when combined with **auto-award rules** -- see
:ref:`challenges-badge-auto-rules`.