20.1.6. 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.

20.1.6.1. 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.”

20.1.6.2. Rule types

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).

20.1.6.3. Creating a rule

From the Badges list, open the 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.

20.1.6.4. 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.

20.1.6.5. 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.

20.1.6.6. 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.