Crystals

Crystals Addon

The Crystals addon is an optional premium add-on for X-Prison that adds a persistent, collectible boost to your server. A crystal boosts the gains of one currency, and its power comes from two things: a tier, which sets a value band, and a random roll inside that band made once when the crystal is created and then frozen forever.

That roll is what makes crystals interesting. Two Tier 7 crystals are not equal — one might be +72% and the next +88% — so "is this one better than the one I already have equipped?" is a real question every time a player opens a crate.

Players hold far more crystals than they can equip, so every loadout is a trade-off about which currency matters right now. Duplicates are never dead weight: they fuse upward into the next tier.

Crystals are never mined or dropped by the addon. Everything is handed out by you — through crates, ranks, votes, store purchases or /crystals give — which makes Crystals a high-value, endlessly re-giftable reward payload rather than another grind.

---

Requirements

Requirement	Notes
X-Prison	2026.3.4.0 or newer
Java 17+	Required
Paper / Spigot / Folia	1.16 – latest
Currencies module	Required — a crystal boosts a currency by its internal name
PlaceholderAPI	Optional — only needed for the placeholders below

Storage: crystals are saved in your existing X-Prison database, following your database_type setting. H2, SQLite and MySQL all work with no extra configuration and no second connection pool.

---

Installation

1. Download X-Prison-Crystals-*.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/Crystals/crystals.yml.
5. Edit it to taste, then run /crystals reload to apply changes without restarting.

The default file ships with three crystal types — Tokens, Gems and Money — and ten tiers.

---

How It Works

1. A crystal is created by an admin command or a crate. At that moment it rolls a random value inside its tier's band and keeps it for life.
2. The player either receives it as a physical item (--item) or straight into their pouch (--store). Clicking a physical crystal in your inventory deposits it into the pouch; switching the menu to Withdraw mode turns a stored crystal back into an item.
3. In /crystals, the player equips crystals into their loadout. There is a fixed number of equip slots and at most one crystal per currency.
4. While equipped, a crystal multiplies that currency's income: amount × (1 + value). A 0.82 roll pays +82%.
5. Crystals stack on top of X-Prison's rank, global and personal multipliers rather than being consumed by them — the crystal boost is applied last.
6. Spare crystals of the same tier and currency can be fused: consume N of tier X to create one of tier X+1, with a fresh roll in the new, higher band.

All boost maths is done in exact BigDecimal, so OP-scale income above nine quadrillion is never rounded away.

---

Tiers

Tiers are defined under tiers: and you can add as many as you like. Numbers may have gaps — fusing always moves to the next tier listed.

Key	Meaning
min	Lowest bonus this tier can roll, as a multiplier bonus (0.7 → +70%)
max	Highest bonus this tier can roll
display-name	Name shown in the tier table (MiniMessage)

Default tiers

Tier	Band	Tier	Band
1	0.01x – 0.1x	6	0.5x – 0.7x
2	0.1x – 0.2x	7	0.7x – 0.9x
3	0.2x – 0.3x	8	0.9x – 1.2x
4	0.3x – 0.4x	9	1.2x – 1.5x
5	0.4x – 0.5x	10	1.5x – 2.0x

The in-game info book prints this table straight from your config, so players always see the real numbers.

---

Fusing

fuse:
  enabled: true
  confirm: true          # ask before consuming
  consume: LOWEST        # LOWEST | HIGHEST | OLDEST
  default-ratio: 3       # 3 of a tier make 1 of the next
  ratios:
    9: 5                 # per-tier override - keeps the top tiers rare

• consume decides which duplicates are eaten first: the lowest rolled, the highest rolled, or the oldest owned. LOWEST is the friendly default.
• Only stored crystals are consumed — an equipped crystal is never eaten by a fuse.
• Fusing is always a tier upgrade, but the new value is a fresh gamble inside the new band. That is the point.
• Shift-click any stored crystal in the menu to fuse its tier.

---

Crystal Types

Nothing exists in-game unless it is declared here. Each entry maps a crystal to one currency from currencies.yml.

crystals:
  tokens:
    enabled: true
    currency: tokens
    display-name: '<gold>Tokens'
    material: SUNFLOWER
    custom_model_data: 0
    slot: 29                # button slot in the main menu, -1 hides it
    max-total-boost: 0      # 0 = uncapped

max-total-boost is an optional ceiling on the total boost a player can hold for that currency, expressed the same way as a tier band (5.0 = +500%). It is off by default.

---

Other Settings

Key	Default	Meaning
storage.max-crystals	500	How many crystals one player may keep. Give and deposit fail cleanly once reached
equip.slots	7	How many crystals can be equipped at once (still one per currency)
boost.causes	MINING, MINING_OTHERS	Which currency gains are boosted. Any X-Prison ReceiveCause works, addon causes included
give.default-mode	STORE	What /crystals give does with no --item / --store flag
item.deposit-on-click	true	Whether clicking a physical crystal in your inventory stores it
placeholders	true	Register the PlaceholderAPI expansion

Every menu, the crystal item and all messages are fully templated in crystals.yml using MiniMessage.

---

Commands & Permissions

Command	Permission	Description
/crystals	xprison.crystals (configurable)	Opens your crystal pouch
/crystals open <player>	xprison.menu.other	Opens the menu on another player's screen (NPC-friendly)
/crystals give <player> <currency> <tier> [amount] [--item|--store]	xprison.crystals.admin	Creates crystals. --store works on offline players; --item needs them online
/crystals take <player> <currency> <tier> [amount]	xprison.crystals.admin	Removes crystals of a tier
/crystals clear <player>	xprison.crystals.admin	Removes every crystal a player owns
/crystals reload	xprison.crystals.admin	Reloads crystals.yml

Aliases /crystal and /cr are configurable under command.aliases.

Crate example — give a random-rolled Tier 7 tokens crystal as a physical item:

crystals give %player% tokens 7 1 --item

---

Placeholders

All placeholders use the xprisoncrystals identifier and require PlaceholderAPI.

Placeholder	Returns
%xprisoncrystals_boost_<currency>%	Total equipped boost as a decimal (0.82)
%xprisoncrystals_boost_percent_<currency>%	The same boost as a percentage (82)
%xprisoncrystals_tier_<currency>%	Tier of the equipped crystal, 0 if none
%xprisoncrystals_equipped_<currency>%	true / false
%xprisoncrystals_stored_<currency>%	How many crystals of that currency are in the pouch
%xprisoncrystals_best_tier_<currency>%	Highest-rolled stored crystal's tier
%xprisoncrystals_stored_total%	Total crystals held
%xprisoncrystals_storage_max%	Storage cap
%xprisoncrystals_slots_used%	Equip slots in use
%xprisoncrystals_slots_total%	Equip slots available

---

Frequently Asked Questions

Can players mine crystals? No — and that is deliberate. The addon never mints a crystal on its own, so the drop rate stays entirely in your hands via crates, ranks, votes and store commands.

Do crystals stack with /multiplier? Yes. The crystal boost is applied after X-Prison's own multipliers, so the two compound instead of one swallowing the other.

Can a player equip two crystals for the same currency? No. One crystal per currency, always — that is what makes a loadout a decision.

What happens to a crystal I withdraw? It becomes a real item carrying its own tier and roll, so it can be traded, stored in a chest or put in a crate. Click it in your inventory to put it back in the pouch.

Are two crystals of the same tier identical? No. Each one rolled its own value inside the tier band when it was created, and that value never changes.

Is fusing safe? It consumes the crystals it lists and always produces the next tier up, but the new roll is random inside the new band. Leave fuse.confirm: true on so players see exactly what they are spending first.

Do crystals survive a restart? Yes. Pouches and equipped loadouts are stored in your X-Prison database.