config.yml

Global settings. After editing, run /battlepassadmin reload. The top of the file is behavior, the rest is icon theming.

Settings

Settings:
  Save-Interval: 60

Key	Default	Description
Save-Interval	60	Seconds between write-behind flushes of player data to SQLite. Claims, purchases and tier-ups are always flushed immediately regardless of this.

Experience

How pass EXP is earned.

Experience:
  Chance: 100.0
  Min-Amount: 1
  Max-Amount: 1
  Ignore-Creative: true
  Worlds: []
  Blocks: []
  Events:
    Block-Break: true
    Block-Place: false
    Mob-Kill: false
    PinnaPrison: false
    EdDungeons: false
    RivalHarvesterHoe: false

Key	Default	Description
Chance	100.0	Percent chance per event to award EXP. Rolled first, so lowering it is the cheapest way to slow the pass down.
Min-Amount	1	Lower bound of the award. Clamped to at least 1.
Max-Amount	1	Upper bound, inclusive. Clamped to at least Min-Amount. Equal bounds skip the roll.
Ignore-Creative	true	Skips players in creative mode.
Worlds	[]	World whitelist, case-insensitive. Empty means every world.
Blocks	[]	Block whitelist, resolved through XSeries. Empty means every block. An invalid name fails the load.

The rolled amount is then scaled by the player’s multiplier (see probabilistic rounding).

Events

Each key toggles one EXP source. Toggles are read at fire time, so /battlepassadmin reload applies changes without a restart.

Key	Default	Source
Block-Break	true	Bukkit BlockBreakEvent, MONITOR priority, cancelled events ignored.
Block-Place	false	Bukkit BlockPlaceEvent.
Mob-Kill	false	EntityDeathEvent where a player is the killer and the victim is not a player. No material, so Blocks doesn’t apply.
PinnaPrison	false	PinnaPrison’s BlockMineEvent.
EdDungeons	false	EdDungeons’ EdDungeonsSwingSwordEvent. No material either.
RivalHarvesterHoe	false	RivalHarvesterHoes’ RivalBlockBreakEvent.

The last three are hooked purely by reflection: they register only when their plugin is enabled and log a severe line if that plugin’s API changed. Turning one on without the plugin installed does nothing.

Multiplier

The purchasable personal EXP multiplier.

Multiplier:
  Purchasable: true
  Economy: RivalCredits
  Price: 250
  Step: 0.1
  Max: 1.5

Key	Default	Description
Purchasable	true	false denies the purchase with MULTIPLIER-NOT-PURCHASABLE. The multiplier still applies to EXP; only buying is off.
Economy	RivalCredits	Currency provider: Vault, PlayerPoints or RivalCredits.
Price	250	Charged per step.
Step	0.1	Added per purchase. Must be above 0.
Max	1.5	Cap. Clamped to at least 1.0. A purchase never overshoots it.

Every player starts at 1.0x. Steps are rounded to four decimals, and the “already maxed” check uses an epsilon so floating-point drift can’t leave a player one hundredth short.

Probabilistic rounding

EXP is an integer, so a fractional multiplier is applied by chance rather than truncation. The scaled amount’s whole part is always paid; its fraction is the chance of one extra EXP.

1 EXP × 1.1  →  2 EXP 10% of the time, 1 EXP otherwise
1 EXP × 1.5  →  2 EXP 50% of the time
3 EXP × 1.25 →  3.75  →  4 EXP 75% of the time, 3 EXP otherwise

Over a session it averages out exactly to the multiplier, which a plain round would not.

Premium-Pass

Premium-Pass:
  Purchasable: true
  Economy: RivalCredits
  Price: 2500
  Free-Status: "&fFree"
  Premium-Status: "&bPremium"

Key	Default	Description
Purchasable	false in code, true in the shipped file	false denies with PREMIUM-NOT-PURCHASABLE. Use it when you sell the pass on a webstore instead and grant it with /battlepassadmin premiumpass give.
Economy	RivalCredits	Currency provider. May differ from the multiplier’s.
Price	2500	One-off cost.
Free-Status	&fFree	Fills {status} for a player without the pass.
Premium-Status	&bPremium	Fills {status} for a player with it.

Only purchasable products pre-warm their economy hook at load. An unresolvable provider logs a warning and its purchases deny with PURCHASE-UNAVAILABLE rather than erroring.

Progress-Bar

The bar rendered into {progress-bar} on the progression icons.

Progress-Bar:
  Length: 30
  Symbol: "|"
  Complete-Color: "&a"
  Remaining-Color: "&c"

Key	Default	Description
Length	20	Number of symbols. Clamped to at least 1.
Symbol	|	The character repeated.
Complete-Color	&a	Color prefix for the filled part.
Remaining-Color	&c	Color prefix for the empty part.

The fill is exp ÷ required for that tier, capped at 100%. {percent} is the same ratio as a two-decimal number (42.50), without a % sign.

Reward-Icons

The three state templates used for every free and premium reward slot.

Reward-Icons:
  Free-Label: "&8Free Reward"
  Premium-Label: "&8Premium Reward"
  Unclaimed:
    Material: CHEST_MINECART
    Primary: "&e"
    Secondary: "&6"
    Name: "{primary}&lTier {secondary}&l{tier}"
    Lore:
      - "{type}"
      - ""
      - "{primary}Rewards:"
      - "{reward-lore}"
      - ""
      - "{primary}&lUNCLAIMED"
  Locked:  { … }
  Claimed: { … }

State	Shown when
Unclaimed	The tier is reached and the reward is not claimed.
Locked	EXP is below the tier’s requirement.
Claimed	Already claimed.

Key	Default	Description
Free-Label / Premium-Label	&8Free Reward / &8Premium Reward	Fills {type}, so one template serves both tracks.
Material	required	Any material name, resolved through XSeries.
Primary / Secondary	&f / &7	Fill {primary} and {secondary} across the icon and the expanded reward lore.
Name, Lore, Base64, Custom-Model-Data, Glow		Standard item fields.

Tokens: {tier}, {type}, {primary}, {secondary}, {exp}, {required}, plus {reward-lore} - a lore line equal to exactly {reward-lore} expands into that tier’s own Lore list. That is how a single tier lore line recolors itself per state.

Progression-Icons

The middle row: one icon per tier showing progress toward it.

Progression-Icons:
  Complete:
    Material: LIME_STAINED_GLASS_PANE
    Name: "&a&lTier &2&l{tier}"
    Lore:
      - "&8Tier Progression"
      - " "
      - "&a&lCOMPLETE"
  Locked:
    Material: RED_STAINED_GLASS_PANE
    Name: "&c&lTier &4&l{tier}"
    Lore:
      - "&8Tier Progression"
      - ""
      - "&cProgress:"
      - "&4 - &7EXP: &a{exp}&8/&c{required}"
      - "&4 - &7{progress-bar} &7({percent}%)"
      - ""
      - "&c&lLOCKED"

Both are required. Tokens: {tier}, {exp}, {required}, {progress-bar}, {percent}. The stack size is the tier number, capped at 64.

Temporary-Icons

Icons that flash for about two seconds in the clicked slot when a click is refused, then restore the real item. While a slot is flashing it is inert, so the deny sound can’t be spammed.

All eight are optional - remove one and that refusal just plays its sound and message. Each is a standard item definition.

Key	Flashed when	Tokens
Locked	A reward below its EXP requirement is clicked.	{tier}, {required}, {exp}
Already-Claimed	An already-claimed reward is clicked.	none
Premium-Required	A premium reward is clicked without the pass.	none
Insufficient-Funds	A purchase is attempted without the funds.	{price}
Multiplier-Maxed	The multiplier is bought at the cap.	{max}
Premium-Owned	The premium pass is bought when already owned.	none
No-Previous-Page	Previous page is clicked on page 1.	none
No-Next-Page	Next page is clicked on the last page.	none

Insufficient-Funds, Multiplier-Maxed and Premium-Owned also flash on the confirm button inside the confirmation menu.

Inventories-Sounds

Named sounds in "NAME;volume;pitch" form. Names are XSound names, stable across Minecraft versions. Set a key to "" to silence it.

Inventories-Sounds:
  "MENU-OPEN": "ENTITY_BAT_TAKEOFF;1;0.5"
  "EXP-GAINED": ""
  "TIER-UP": "UI_TOAST_CHALLENGE_COMPLETE;1;1"
  "CLAIM": "ENTITY_PLAYER_LEVELUP;1;1.5"
  "PURCHASE": "ENTITY_PLAYER_LEVELUP;1;1.5"
  "PAGE-CHANGED": "ENTITY_CHICKEN_EGG;1;1"
  "NO-PAGE-FOUND": "BLOCK_NOTE_BLOCK_PLING;1;0.5"
  "DENY": "ENTITY_VILLAGER_NO;1;0.5"

Key	Played when
MENU-OPEN	Either menu opens.
EXP-GAINED	EXP is awarded. Ships blank - the default is 100% chance per block.
TIER-UP	A tier is crossed.
CLAIM	A reward is claimed.
PURCHASE	A purchase completes.
PAGE-CHANGED	A page turn succeeds.
NO-PAGE-FOUND	A page turn is refused at either edge.
DENY	Any refused click.