Momentum

Momentum Addon

The Momentum addon is an optional premium add-on for X-Prison that rewards active mining. As a player breaks blocks they build a streak that climbs through configurable tiers — On Fire, Unstoppable, Rampage, … — and each tier grants a currency multiplier on their mining income. The current tier, streak and multiplier are shown on a live bossbar that fills toward the next tier.

Stop mining and momentum decays: after a grace period the player drops one tier at a time until it is lost. Momentum is never saved — a server restart wipes everyone's momentum, so it only ever rewards players who are mining right now.

---

Requirements

Requirement	Notes
X-Prison	2026.2.6.3 or newer
Java 17+	Required
Paper / Spigot / Folia	1.13 – latest (the bossbar requires a 1.9+ client)
Currencies module	Required — momentum multiplies mining income for the currencies you list
PlaceholderAPI	Optional — only needed for the placeholders below

Currencies: momentum boosts a currency by its internal name. money is boosted by default; add tokens, gems, etc. under boosted-currencies. Those currencies must be registered in currencies.yml.

---

Installation

1. Download X-Prison-Momentum-*.jar from your purchase platform.
2. Place the JAR inside plugins/X-Prison/addons/.
3. Restart the server (do not use /reload).
4. A default config is created at plugins/X-Prison/addons/Momentum/config.yml.
5. Edit it to taste, then run /momentum reload to apply changes without restarting.

---

How It Works

1. A player mines blocks. Each block adds to their streak (streak.per-block, default 1).
2. The streak unlocks tiers in order. The moment the streak reaches a tier's streak-required, the player is in that tier and receives its multiplier on mining income.
3. A bossbar shows ➷ <Tier> <streak> streak · +<multiplier> money. It fills based on how far the streak has progressed from the current tier toward the next tier's threshold. The highest tier is always full.
4. The multiplier is applied only to mining income (selling mined blocks) for the currencies in boosted-currencies, and it stacks on top of X-Prison's normal rank/global/personal multipliers.
5. If the player stops mining for afk.threshold-seconds, momentum starts to decay — dropping one tier every afk.decay-interval-seconds — until it is lost entirely.

Momentum is transient: it lives only in memory and is wiped on server restart.

---

Tiers

Tiers are defined under tiers: and you can add as many as you like. Each tier:

Key	Meaning
name	Display name shown on the bossbar
streak-required	Streak (blocks) needed to reach this tier — the lowest tier should be 0
multiplier	Bonus percent, e.g. 150.0 → +150% income (a 2.5x multiplier)
suffix	Text after the multiplier number ("%" or "x")
color	Bossbar colour: PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
style	SOLID or SEGMENTED_6 / SEGMENTED_10 / SEGMENTED_12 / SEGMENTED_20
title	(optional) per-tier bossbar title override (MiniMessage)

Default tiers

Tier	Streak	Multiplier	Colour
On Fire	0	+50%	Yellow
Unstoppable	500	+150%	Red
Rampage	5,000	+400%	Pink
Cataclysm	25,000	+1200%	Purple
TRANSCENDENT	100,000	+5000%	Pink (segmented, always full)

These are just example values — edit, delete, or add your own freely.

---

Configuration (config.yml)

enabled: true
prefix: "<gradient:#f7971e:#ffd200><bold>MOMENTUM</bold></gradient> <dark_gray>» </dark_gray>"

command:
  name: "momentum"
  aliases: ["mom"]
  admin-permission: "xprison.momentum.admin"

# Currencies whose MINING income is multiplied (internal names, case-insensitive).
boosted-currencies:
  - money

streak:
  per-block: 1                # streak gained per block broken

afk:
  threshold-seconds: 30       # no-mining time before momentum starts to decay
  decay-interval-seconds: 15  # once decaying, drop one tier every N seconds

bossbar:
  enabled: true
  # Placeholders: {tier}, {streak}, {multiplier}
  title: "➷ <yellow>{tier}</yellow> <gray>{streak} streak</gray> <dark_gray>·</dark_gray> <green>+{multiplier} money</green>"

tiers:
  on-fire:      { name: "On Fire",     streak-required: 0,     multiplier: 50.0,   suffix: "%", color: YELLOW, style: SOLID }
  unstoppable:  { name: "Unstoppable", streak-required: 500,   multiplier: 150.0,  suffix: "%", color: RED,    style: SOLID }
  rampage:      { name: "Rampage",     streak-required: 5000,  multiplier: 400.0,  suffix: "%", color: PINK,   style: SOLID }
  cataclysm:    { name: "Cataclysm",   streak-required: 25000, multiplier: 1200.0, suffix: "%", color: PURPLE, style: SOLID }
  transcendent:
    name: "TRANSCENDENT"
    streak-required: 100000
    multiplier: 5000.0
    suffix: "x"
    color: PINK
    style: SEGMENTED_10
    title: "➷ <gradient:#ff5ff2:#ff9ff3><bold>{tier}</bold></gradient> <gray>{streak} streak</gray> <dark_gray>·</dark_gray> <light_purple>+{multiplier} money</light_purple>"

All text is MiniMessage.

---

Commands & Permissions

Command	Description	Permission
/momentum	Show your current momentum tier, streak and multiplier	(open to everyone)
/momentum reload	Reload the config	xprison.momentum.admin

Aliases: /mom (configurable).

---

Placeholders

Requires PlaceholderAPI. Identifier xprisonmomentum:

Placeholder	Returns
%xprisonmomentum_tier%	Current tier name (empty if inactive)
%xprisonmomentum_streak%	Abbreviated streak, e.g. 4.33M
%xprisonmomentum_streak_raw%	Exact streak count
%xprisonmomentum_multiplier%	Headline multiplier with suffix, e.g. 150%
%xprisonmomentum_multiplier_raw%	Applied factor, e.g. 2.5
%xprisonmomentum_progress%	Fill percent toward the next tier (0–100)

---

FAQ

Does momentum survive a restart? No — it is intentionally wiped on restart so it only rewards active mining sessions.

Does the multiplier affect /pay, admin /give, or enchant currency rewards? No. Only income with the mining cause (selling mined blocks) is boosted, and only for the currencies you list.

Does it stack with events / rank / global multipliers? Yes. Momentum applies before X-Prison's own multipliers, so they compound.

Can I have more than five tiers? Yes — add as many as you like under tiers:; they are ordered automatically by streak-required.