Pets

Pets Addon

The Pets addon is an optional premium add-on for X-Prison that adds collectible Resource Pets. Each pet is a real item — no database, no per-player storage — that a player carries in their inventory and toggles active to receive a boost. Pets come in configurable rarities (Common → Pristine), each with its own boost band, and are levelled and prestiged by spending currency, turning your economy into a long-term progression sink.

Because a pet is its item, everything about it (rarity, level, prestige, active flag) lives in the item itself. Trade it, store it, drop it — the boost follows the item.

---

Requirements

Requirement	Notes
X-Prison	2026.2.8.2 or newer
Java 17+	Required
Paper / Spigot / Folia	1.16 – latest (custom GUIs require MiniMessage)
Currencies module	Required — pets boost mining income and are upgraded with currency
Pickaxe Levels module	Optional — only needed for the Pickaxe Pet
PlaceholderAPI	Optional — only needed for the placeholders below

Currencies: a currency pet boosts a currency by its internal name (tokens, money, gems, …) and is upgraded with the currency set in its cost-currency. Those currencies must be registered in currencies.yml.

---

Installation

1. Download X-Prison-Pets-*.jar from your purchase platform.
2. Place the JAR inside plugins/X-Prison/addons/.
3. Restart the server (do not use /reload).
4. Default configs are created at plugins/X-Prison/addons/Pets/ (config.yml, pets.yml, gui.yml, messages.yml).
5. Edit them to taste, then run /petsadmin reload to apply changes without restarting.

On upgrade, any new config keys are added to your existing files automatically; your customised values are never overwritten.

---

How It Works

1. Players obtain Pet Eggs (via /petsadmin give-egg, crates, enchant rewards, etc.). Right-clicking an egg hatches it — an animated menu reveals a random pet at a random (weighted) rarity, then the pet drops into the inventory. Hatching can be turned off for an instant grant.
2. Right-click a pet in hand to toggle it active. Active pets are marked with a subtle glint and count toward the active-pet limit (general.max-active-pets, raised per-player with the xprison.pets.active.<n> permission).
3. An active pet applies its boost. A currency pet multiplies that currency's mining income; the Pickaxe Pet multiplies all Pickaxe XP gained from mining (manual breaks, area enchants and AutoMiner — XP granted directly by other addons is untouched). Requires X-Prison 2026.2.9.0+.
4. Open /pets to browse every pet type and its per-rarity boost table, and to open the Pet Upgrades and Pet Prestiges pickers.
5. Upgrade a pet to raise its level from the band minimum toward the band maximum, paying its cost-currency per level (buy one, or bulk-buy as many as you can afford). Prestige a maxed pet to reset its level and gain a permanent boost multiplier that stacks every prestige.

The live boost is:

levelValue     = min + (max - min) * (level - 1) / (maxLevel - 1)
effectiveBoost = levelValue * (1 + prestige * per-prestige-percent)

---

Pets

Four pets ship by default. Add, edit or remove any of them in pets.yml.

Pet	Boosts	Upgrade currency	Max level	Max prestige
Token Pet	Mining Tokens income	tokens	40	10
Money Pet	Mining Money income	money	40	10
Gem Pet	Mining Gems income	gems	40	10
Pickaxe Pet	All mining Pickaxe XP (multiplicative)	tokens	100	15

Rarities

Rarities are fully configurable under rarities: in config.yml. Order = display order; higher weight = more common; weight 0 = never rolled (admin-only).

Rarity	Weight	Colour
Common	600	Gray
Rare	250	Aqua
Legendary	100	Gold
Mythical	40	Light Purple
Masterful	9	Red
Pristine	1	Dark Red

Each pet defines a {min, max} boost band per rarity, so higher rarities are simply stronger versions of the same pet.

---

Configuration (config.yml)

general:
  max-active-pets: 1
  maxed-text: "<gradient:#f7971e:#ffd200>Maxed</gradient>"

pet-egg:
  material: GHAST_SPAWN_EGG
  glow: true
  hatching:
    enabled: true            # false = grant the pet instantly, no menu
    animation-ticks: 60
    close-delay-ticks: 40    # auto-close the menu after the reveal (0 = stay open)
    frames: [WHITE_STAINED_GLASS_PANE, LIGHT_BLUE_STAINED_GLASS_PANE, YELLOW_STAINED_GLASS_PANE, LIME_STAINED_GLASS_PANE, PINK_STAINED_GLASS_PANE]
    animation-sound: BLOCK_NOTE_BLOCK_HAT
    reveal-sound: ENTITY_PLAYER_LEVELUP
    reveal-particles: TOTEM_OF_UNDYING

effects:
  upgrade-sound: ENTITY_EXPERIENCE_ORB_PICKUP
  upgrade-particles: HAPPY_VILLAGER
  prestige-sound: UI_TOAST_CHALLENGE_COMPLETE
  prestige-particles: TOTEM_OF_UNDYING

sounds:
  gui-open:         { name: BLOCK_CHEST_OPEN,             volume: 0.5, pitch: 1.2 }
  gui-click:        { name: UI_BUTTON_CLICK,              volume: 0.5, pitch: 1.0 }
  purchase-success: { name: ENTITY_EXPERIENCE_ORB_PICKUP, volume: 0.7, pitch: 1.4 }
  purchase-fail:    { name: ENTITY_VILLAGER_NO,           volume: 0.7, pitch: 1.0 }

rarities:
  common:    { name: "Common",    color: "<gray>",         weight: 600 }
  rare:      { name: "Rare",      color: "<aqua>",         weight: 250 }
  legendary: { name: "Legendary", color: "<gold>",         weight: 100 }
  mythical:  { name: "Mythical",  color: "<light_purple>", weight: 40 }
  masterful: { name: "Masterful", color: "<red>",          weight: 9 }
  pristine:  { name: "Pristine",  color: "<dark_red>",     weight: 1 }

commands:
  pets:      { name: pets,      aliases: [pet] }
  petsadmin: { name: petsadmin, aliases: [petadmin] }

Pet definitions (pets.yml)

Each pet has one boost target and a per-rarity {min, max} band:

pets:
  token_pet:
    display-name: "<gradient:#f7971e:#ffd200>Token Pet</gradient>"
    description: "increases the <yellow>Tokens</yellow><gray> you earn while mining"
    boost-target: tokens          # a currency name, or "pickaxe_xp"
    boost-display: "Token"
    material: PLAYER_HEAD
    head-texture: "<base64 skin value>"
    max-level: 40
    max-prestige: 10
    per-prestige-percent: 0.25    # +25% permanent boost per prestige
    cost-currency: tokens
    cost-formula: "5000 * pow(1.18, level)"   # exp4j; variable: level = cost of NEXT level
    rarities:
      common:    { min: 0.045, max: 0.19 }
      # rare / legendary / mythical / masterful / pristine ...

The gui.yml and messages.yml files are fully configurable too (menu titles, slots, materials, all lore, sounds and every player-facing string). All text is MiniMessage — gradients, hex and legacy & codes all work, and item text is rendered non-italic by default.

---

Commands & Permissions

Command	Description	Permission
/pets	Open the pet catalog + Upgrade/Prestige pickers	xprison.pets.use
/petsadmin give <player> <type> <rarity> [amount]	Give a pet	xprison.pets.admin
/petsadmin give-egg <player> [rarity] [amount]	Give Pet Egg(s)	xprison.pets.admin
/petsadmin reload	Reload the configs	xprison.pets.admin

Aliases: /pet, /petadmin (configurable).

Permission	Effect
xprison.pets.active.<n>	Raise a player's active-pet limit to <n>
xprison.pets.active.* / xprison.pets.limit.bypass	Unlimited active pets

---

Placeholders

Requires PlaceholderAPI. Identifier xprisonpets:

Placeholder	Returns
%xprisonpets_active_count%	Number of active pets
%xprisonpets_active_name%	First active pet's name
%xprisonpets_active_target%	What it boosts (e.g. Token)
%xprisonpets_active_rarity%	Its rarity
%xprisonpets_active_level%	Its level
%xprisonpets_active_maxlevel%	Its max level
%xprisonpets_active_prestige%	Its prestige
%xprisonpets_active_boost%	Its effective boost, e.g. 0.42

---

Extending Boost Targets

Out of the box a pet's boost-target is either pickaxe_xp or any currency name (optionally currency:<name>). The boost-target system is a small registry, so a developer can register a new target id and pair it with a listener — no changes to existing pets.

Candidate targets to build on top of this seam: a sell-multiplier on shop/AutoSell income, a flat gem/beacon/mob-coin drop bonus, an enchant proc-chance ("crit") boost, a vanilla-XP boost, or per-source currency variants (mining vs. sell vs. all). Currency pets currently boost mining income only.

---

FAQ

Where is pet data stored? Nowhere — the pet is the item. Rarity, level, prestige and the active flag are baked into the item, so there is no database and pets are fully tradeable.

Do currency pets boost /pay, sell-shop, or enchant currency rewards? No. Currency pets boost mining income only. The Pickaxe Pet grants bonus Pickaxe XP per block mined.

How many pets can a player have active? general.max-active-pets (default 1), raised per-player with xprison.pets.active.<n> or made unlimited with xprison.pets.active.*.

Can I turn off the hatching animation? Yes — set pet-egg.hatching.enabled: false and eggs grant their pet instantly.

Can I add my own pets or rarities? Yes — add entries under pets: and rarities:. A pet may define bands for any subset of rarities; it can only roll at rarities it has a band for.

Do prestige boosts stack? Yes — each prestige adds a permanent +per-prestige-percent multiplier on top of the level boost, forever.