Skip to content
◆ TTS-STUDIO docs Discord

Plugins / CrateForge

Pity System

Pity System

The pity system guarantees that players will receive a prize of at least a certain rarity after a configurable number of opens without getting that rarity. It prevents players from going on very long losing streaks.

How It Works

  1. Every time a player opens a crate, their pity counter increases by 1
  2. If the rolled prize meets or exceeds the guaranteed-min-rarity, the counter resets to 0
  3. If the player reaches the threshold without receiving a qualifying prize, the next open is forced to roll from prizes of at least guaranteed-min-rarity
  4. After the guaranteed prize is given, the counter resets to 0
Player opens 49 crates:
  Opens 1-48: Got COMMON prizes. Counter: 1, 2, 3... 48
  Open 49:    Got RARE prize! ✅ Counter resets to 0

Player opens 50+ crates without RARE:
  Opens 1-49: Got COMMON prizes. Counter: 1, 2... 49
  Open 50:    Pity triggers → forced RARE+ prize! 🎰 Counter resets to 0

Configuration

The pity system is configured per-crate inside the crate's .yml file:

# Inside crates/legendary.yml

pity:
  enabled: true           # Set to false to disable pity for this crate
  threshold: 50           # After 50 opens without a RARE+, guarantee one
  guaranteed-min-rarity: RARE   # Minimum rarity of the guaranteed prize

Field Reference

Field Type Required Description
enabled Boolean Yes Enable or disable pity for this crate
threshold Integer Yes Number of opens before guarantee triggers
guaranteed-min-rarity String Yes Minimum rarity: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY

Rarity Ladder

Pity guarantees prizes at or above the specified rarity:

LEGENDARY  ← highest
  EPIC
  RARE      ← setting guaranteed-min-rarity: RARE guarantees RARE, EPIC, or LEGENDARY
  UNCOMMON
  COMMON    ← lowest
guaranteed-min-rarity Eligible Prizes
COMMON All prizes (essentially no filter)
UNCOMMON UNCOMMON, RARE, EPIC, LEGENDARY
RARE RARE, EPIC, LEGENDARY
EPIC EPIC, LEGENDARY
LEGENDARY LEGENDARY only

Warning: If you set guaranteed-min-rarity: LEGENDARY but the crate has only 1 LEGENDARY prize, every pity trigger will give that exact prize. Make sure there are enough prizes at the guaranteed rarity.

Pity Data Persistence

Pity counters are stored per-player per-crate in the SQLite database (crateforge.db). They persist across: - Server restarts - Player disconnections - Plugin reloads

Note: Pity counters are tied to the crate ID. If you change a crate's ID, all existing pity progress for that crate is lost.

Standard Survival Server

pity:
  enabled: true
  threshold: 50
  guaranteed-min-rarity: RARE

Premium/Legendary Crate

pity:
  enabled: true
  threshold: 100
  guaranteed-min-rarity: EPIC

Common/Cheap Crate

pity:
  enabled: true
  threshold: 20
  guaranteed-min-rarity: UNCOMMON

Disable Pity (pure RNG)

pity:
  enabled: false

Calculating Effective Rates

With pity, the effective rate of getting guaranteed-min-rarity+ is higher than the raw weight suggests:

Without pity: purely based on weight ratios
With pity (threshold=50, 60% natural rate):
  → In the worst case, a player gets the prize every 50 opens
  → Average opens per RARE+ = much lower than 50 due to natural drops

Tip: Be transparent with your players! Display the pity threshold in the crate's display name or use /cf preview to let them see it.

Home | Crate Format | Animations | Commands & Permissions