Prison Pets

PrisonPets gives your players pets that float around them and boost their mining. Players hatch pets from eggs, level them up by mining, and make them stronger with fusion, stickers, traits and upgrades. Every boost goes through PinnaPrison's boosters, so it stacks with your other boosts and shows in /boosters.

The short version

Upload the prisonpets jar to your plugins folder and restart the server, so it creates its files and menus. Then join as an operator and run:

/pets admin give <your name> egg common_egg
/pets
/pets formation halo
/pets admin debug

1. give ... egg common_egg puts a Common Egg in your inventory. Hold it and right-click to hatch it. The new pet goes into your pet storage.
2. /pets opens the pets menu. Click the green empty slot, then right-click your new pet in the list to equip it. It appears and starts circling you.
3. /pets formation halo changes how your pets float. Run /pets formation on its own to pick from every formation.
4. /pets admin debug shows the boosts your equipped pets are giving right now. Mine a few blocks and your pet starts earning XP.

What you need

Pets, tiers and rarity

Each pet type is one file in plugins/prisonpets/pets/, and the file name is the pet's id. Four come bundled: pig, bee, enderman and dragon. This is the pig, trimmed:

display-name: 'Pig'
color: '&d'
rarity: common
egg-weight: 1.0
visual:
  texture: 'eyJ0ZXh0dXJlcyI6...'
  glow: ''
max-level: 100
xp:
  formula: '120 * level ^ 1.45'
max-tier: 0
boosts:
  - { channel: tokens, name: '&6Tokens', formula: '0.02 + 0.0015 * level' }

• boosts: one line per boost. The formula gives a fraction worked out at the pet's level, so 0.02 is +2%. The channel is a PinnaPrison currency id (such as tokens or gems), enchants (the proc chance of every enchant), blocks (PinnaPrison's blocks multiplier), armor-xp or a single enchant's id. The console warns on start-up about any channel PinnaPrison doesn't know.
• xp: the XP needed to go from each level to the next. Formulas can use level, maxLevel, tier and mastery; you can also give a levels: list instead.
• texture: the head's base64 "Value" from a site such as minecraft-heads.com. The bundled file says to replace it with your own.
• glow: blank, or one of the 16 vanilla colour names such as GOLD or AQUA. Anything else is switched off with a console warning.
• max-tier: the highest tier fusion can take this pet to. 0 means the last tier in tiers.yml.

Rarity and tier are different things, even though the default names overlap. rarity is a fixed label on the pet type, and eggs use it to decide which pets they can hatch. A pet's tier comes from tiers.yml (Common, Uncommon, Rare, Epic and Legendary by default, first one is tier 1) and goes up through fusion. Each tier makes the pet stronger:

  rare:
    boost-multiplier: 1.8
    max-level-bonus: 20
    xp-cost-multiplier: 1.5
    enhancement-slots: 2
    fusion-cost: { currency: tokens, amount: 750000 }
    bin-candy-multiplier: 1.5

To add a pet, copy a file in pets/, rename it (the new file name is the new id), change its name, texture, rarity and boosts, then run /pets admin reload. Eggs that hatch pet: random include it straight away if its rarity matches, picked by egg-weight against the other pets.

How pets follow players

Only equipped pets show, give boosts and earn XP; the rest sit in storage. A player can equip up to four. Their slot count is the higher of slots.base-equip (1) and their prisonpets.slots.<n> permission, plus any slots from vouchers or the shop, capped at slots.max-equip (1 to 4).

Outside a mine, only the owner sees their pets. Inside a PinnaPrison mine, everyone in that mine sees them too, such as co-op members and visitors. /pets toggle hides a player's pets; hidden pets still give their boosts.

formations.yml sets how pets arrange themselves. Each entry uses one of 14 built-in shapes as its type (orbit, halo, double_orbit, wheel, helix, figure_eight, sphere, star, march, v_wing, row, guard, tower, wave) and tunes it with settings such as radius, height and speed. Add permission: '<node>' to an entry to lock it behind a permission. New players start on mover.default-formation from config.yml.

Levels, boosts and upgrades

Equipped pets earn XP from every block their owner breaks. The xp section of config.yml sets how much: base-per-block, a global-multiplier, and source-multipliers that by default make blocks from enchants, bombs, drills, autominers and AFK blocks worth less than mining by hand. With split-between-equipped: true the XP is shared between equipped pets instead of each getting the full amount.

A pet's boosts grow with its level, and these all multiply on top:

• its tier's boost-multiplier
• its mastery, +10% each (mastery.boost-per-mastery)
• its Buff sticker, and its Level sticker's extra levels
• traits and account upgrades aimed at that channel or at all

Its level cap is the pet's max-level, plus its tier's max-level-bonus, plus 10 per mastery (mastery.levels-per-mastery).

• Candy gives a pet XP straight away. Players get it from the bin, while mining with the Forager trait or Candy Finder upgrade, or from /pets admin give. With candy.feed-mode: select, right-clicking candy opens a pet picker; all-equipped feeds every equipped pet. A candy backpack stores candy until it's needed.
• Mastery is a pet prestige. At max level, a player can master the pet from its details menu for mastery.cost (by default 250000 * (mastery + 1) * tier tokens). By default the pet goes back to level 1 with a higher cap and stronger boosts, up to mastery.max (10) times.
• Stickers add a grade from F to SSS (boosts.yml) to a pet's Level, Buff or XP slot. A sticker always replaces the grade already there, so a random one can roll lower.
• Traits come from enhancements.yml. An enhancement ticket rolls a trait into a free slot (the tier's enhancement-slots); a reroll ticket replaces one. The comment at the top of the file lists every effect. Candy chance, bonus XP chance and egg luck are capped under extras in config.yml.
• Account upgrades from upgrades.yml apply to every pet a player owns. Players buy them in /pets upgrades, and level in the cost formula is the level they already have:

  token_affinity:
    max-level: 10
    effect: BOOST
    channel: tokens
    per-level: 0.05
    cost: { currency: tokens, formula: '75000 * 2 ^ level' }

The upgrades menu has one button per upgrade, so a new upgrade also needs its own pets-upgrade item in pets-upgrades.yml.

Fusion, the bin and storage

Fusion (/pets fuse) turns two pets of the same type and tier into one pet of the next tier, for the fusion-cost of their current tier. The fusion section of config.yml decides what the new pet keeps: keep-boosts (the best stickers by default), keep-enhancements (both pets' traits, trimmed to the new tier's slots), keep-mastery and reset-level. The Resilient trait keeps the level anyway. Set require-max-level: true to only allow fusing maxed pets.

The bin turns a pet into one candy worth bin.refund-rate (half) of the XP put into it, times its tier's bin-candy-multiplier, and never less than min-candy-xp. Quick bin does the same for every stored, unlocked pet at or below quick-bin.max-level and quick-bin.max-tier. Bulk delete removes every stored pet of one tier with no refund. Right-clicking a pet in its details menu locks it, which protects it from the bin, fusion and bulk delete.

Storage holds slots.base-storage (27) pets, or more with prisonpets.storage.<n>, vouchers or the shop, up to slots.max-storage (500). Equipped pets count towards it.

How players get pets

Eggs are the main way. Each egg in eggs.yml hatches one reward, picked by weight:

  rare_egg:
    permission: ''
    luck-threshold: 2
    animation: { enabled: true, ticks: 40 }
    rewards:
      - { weight: 65, pet: random, rarities: [rare], tier: 1, level: '3-8', boosts: { xp: 'F-C' } }
      - { weight: 25, pet: random, rarities: [rare], tier: 2, level: '1-5', boosts: { buff: 'E-B' } }
      - { weight: 9,  pet: random, rarities: [epic], tier: 1, level: '1-5' }
      - { weight: 1,  pet: random, rarities: [epic], tier: 2, level: 1, boosts: { buff: 'C-A', level: 'D-A' }, broadcast: true }

• pet is a pet id, or random to pick from the pets whose rarity is listed in rarities (any pet if you leave it out).
• tier and level (a number or a range) set the pet it hatches as, and boosts gives it sticker grades from a range.
• broadcast: true announces the hatch to everyone, and commands: runs console commands, with %player% for the player.
• luck-threshold: rewards of this tier or higher get more likely with egg luck from the Lucky trait and Fortune upgrade.
• permission makes the egg need a permission to open. If the player doesn't have it, or their storage is full, they keep the egg.

Check the odds with /pets admin egg simulate rare_egg 10000. Players can also get pets and eggs in these ways:

• The pet shop (/pets shop) sells pet slots, storage space and eggs. Each listing is a pets-shop item in the menu file pets-shop.yml, with a kind (slot, storage or egg), an amount, an egg id for eggs, a currency and a cost. In the cost, level is how many of that listing the player already has, counting redeemed vouchers (always 0 for eggs).
• Crates, the battle pass and other rewards. Anything that runs a console command can give an egg, for example pets admin give {player} egg rare_egg 1. In PrisonCrates that's a command: action on a reward, and PrisonPass ships with egg rewards already set up. The player must be online.
• Pet items from /pets admin give <player> pet <type>. Right-clicking one adds the pet to storage. Players can't turn a stored pet back into an item.

Commands

/pet and /prisonpets work in place of /pets.

The admin commands also work from the console. Players named in them must be online.

Permissions

When a player has several of the numbered permissions, the highest number counts. Formations and eggs can also need a permission of your choice, set with permission: in formations.yml and eggs.yml.

Files

/pets admin reload applies changes to every file in plugins/prisonpets/ and refreshes everyone's pets, except the storage section of config.yml, which needs a restart. Switching between SQLite and MySQL doesn't copy existing pets across.

The default files are only written when they're missing. The four example pets are only written when the whole pets folder is missing, so you can delete the ones you don't want.

The menu files use PinnaPrison's own GUI format and reload with /pinna reload, not /pets admin reload. They're written on first start and never overwritten, so your edits survive updates. To get a default back, delete the file and restart the server. The comment at the top of each file explains its buttons and tokens. See the PinnaPrison docs for the GUI format.

Placeholders

PinnaPrison registers these as variables. Use them as %pinnaprison_variable_<name>% wherever PinnaPrison's placeholders work, for example %pinnaprison_variable_pets_equipped%.

pets_boost_<currency> only exists for the currencies PinnaPrison has when the server starts.

Troubleshooting

Pets show, but they don't boost anything. Look in the console. "PinnaPrison boosters are disabled" means boosters are turned off in PinnaPrison's boosters.yml, and pets can't boost anything until you turn them on. A line saying a boost channel "is not a PinnaPrison currency" means a pet file uses a currency id your server doesn't have; fix it and run /pets admin reload. Also check the pet is equipped, not just in storage.

PrisonPets doesn't start. Read the console from the top of the start-up. Errors about downloading libraries mean the server had no internet access; Paper needs it once to fetch the database drivers. "Could not open the pet database" means the database couldn't be reached, so check the MySQL details under storage in config.yml or switch back to type: sqlite. "PinnaPrison API is not available" means PinnaPrison didn't start properly; fix its errors first.

A player is told their storage is full, but the menu shows free space. Equipped pets count towards the limit, but the storage numbers in the menu and pets_storage_used leave them out. Raise the player's storage, or have them bin some pets.

A shop listing is missing, and the console says Bad pets-shop item: Unknown egg 'mythic_egg'. The bundled shop has a Mythic Egg listing, but the default eggs.yml has no mythic_egg. Add an egg with that id, or delete the mythic-egg item from pets-shop.yml and run /pinna reload. While you're there, check the egg lore in the shop matches your pets: it names pets that aren't in the bundled set, and the price lines say "Tokens" whatever currency is set to.

Menu changes don't show up. Menus belong to PinnaPrison, so run /pinna reload. /pets admin reload doesn't touch them. If a menu is broken beyond repair, delete its file and restart to get the default back.

A slot or storage voucher did nothing. Vouchers are used up even when the player is already at slots.max-equip or slots.max-storage, so check the player's limits before handing them out. Also, /pets admin slots and /pets admin storage replace a player's bonus rather than adding to it, which wipes slots they bought in the shop.