.. include:: ../variables.rst
.. _challenges-badge-auto-rules:

Badge Auto-Award Rules
======================

Auto-award rules grant a badge automatically when a participant crosses a threshold, without
having to attach the badge to a specific challenge. They are evaluated immediately after every
challenge close for each winner of that challenge.

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

|br|

Why use them
------------

Per-challenge rewards handle "who won this specific contest". Auto-rules handle **career
milestones** -- the patterns that only become visible over many challenges:

* *"Award the Silver Medal after a participant wins their 5th challenge."*
* *"Award the Gold Medal after the 10th."*
* *"Award the Streak Star on a three-in-a-row winning streak."*
* *"Award a Century badge after reaching 100 lifetime points."*

Rule types
----------

.. list-table::
   :header-rows: 1
   :widths: 15 20 65

   * - Code
     - Rule type
     - Threshold meaning
   * - ``0``
     - Challenge win count
     - Number of distinct challenges the participant has won.
   * - ``1``
     - Consecutive wins
     - Number of wins in a row. Currently approximates as total wins until the MySQL window-function
       rewrite lands -- treat as a minimum.
   * - ``2``
     - Lifetime points
     - Total ``SUM(points)`` across the participant's ledger (earned minus spent).

Creating a rule
---------------

From the :ref:`challenges-badges` list, open the :blue:`Auto-Rules` panel (or the
``/badges/auto-rules`` endpoint). Provide:

* **Badge** -- which badge to grant.
* **Rule type** -- one of the three codes above.
* **Threshold** -- the numeric trigger.

Thresholds must be positive integers. Duplicate rules (same badge + rule type for the same
corporation) are coalesced by an ``ON DUPLICATE KEY UPDATE`` -- creating "the same rule" twice
simply updates the threshold.

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

|br|

When rules fire
---------------

Auto-rules are evaluated:

* **On challenge close** -- for every winner of that challenge.

In the future they will also be evaluated nightly via cron. For now, a participant who crosses a
threshold outside of winning a challenge will not receive the badge until the next time they win
one.

Evaluation is **idempotent**: the same badge cannot be granted twice to the same participant,
even if the rule fires repeatedly, because of the ``uniq_badge_award`` unique key on
``challenge_badges_awarded``.

Deactivating a rule
-------------------

Set ``active = 0`` or delete the rule row. Deleting a rule does **not** revoke any badges already
granted through it -- those remain on the participant's profile.

Relationship to per-challenge rewards
-------------------------------------

Per-challenge reward badges and auto-rule badges are stored in the same table but use
``challengeid`` differently:

* **Per-challenge reward** -- ``challengeid`` points to the challenge that granted the badge.
* **Auto-rule grant** -- ``challengeid = 0`` (rule-driven grants are not tied to a single
  challenge).

This means a participant who wins a challenge that rewards the Gold badge, and who also triggers
a Gold auto-rule, can receive the Gold badge twice (once per route) -- the unique key is
``(challengeid, participanttype, participantid, badgeid)``, and the two grants have different
``challengeid`` values. If this matters to you, pick a different badge for the rule than for the
challenge reward.