PetCompanions

Pets are found by playing. Every source has its own pool, chance and cooldown, all under discovery.sources in config.yml — and all printable in game with /petadmin balance, which is the honest answer to "what is this server actually doing" rather than what the file says.

Mining, breaking any block, killing mobs, fishing, opening a container underwater, earning an advancement, enchanting, sleeping, dying, and talking in chat each roll their own pool. So do the deep dark and the End, on the blocks unique to them.

Five more match on what a player TYPED — shop and auction commands, banking and /pay, homes and spawn, teleports, cosmetic commands. They work with whichever plugins you happen to run, and simply never fire if you run none.

Duplicates convert to shards, which buy mystery eggs at /pet eggs. A pity counter guarantees a find after discovery.pity.threshold failed rolls, so nobody is unlucky forever.

Twenty pets — ascendant_1 through ascendant_10 and paragon_1 through paragon_10 — are deliberately not obtainable in play. They exist to be awarded.

/petadmin give %player% ascendant_4

That runs from console or a command block, so any rank plugin, crate, vote listener or prestige system can award one. Rarity and stats escalate across each ten, and the two ladders are matched in value, so they can back two parallel tracks without one being obviously better.

The numbers worth touching first are the per-player pet limit, the discovery odds, and the gather trip length.

pets:
  max-per-player: 25
  passive-tick-interval: 40   # ticks between passive buff refreshes
  combat-tick-interval: 10    # ticks between pet combat checks
gather:
  trip-minutes: 15
discovery:
  pity:
    threshold: 1200           # failed rolls before a find is guaranteed
economy-yield:
  sell-boost: 1.10            # multiplier from the economy_yield passive

After any edit, /petadmin reload re-reads everything, and /petadmin balance prints the result so you can check the change actually landed rather than assuming it did.

New config keys are copied in from the jar on start, and the file is only rewritten when something was genuinely missing — your comments and formatting survive otherwise. The log names what was added.

The one thing that cannot be merged is a new entry inside a LIST you already have, such as a pet pool or a rarity table. Yours is present, so yours wins. New list entries are called out in the release notes so you can merge them by hand if you want them.

With PlaceholderAPI installed: %petcompanions_active%, %petcompanions_active_type%, %petcompanions_active_level%, %petcompanions_active_bond%, %petcompanions_active_rarity%, %petcompanions_owned%, %petcompanions_limit%, %petcompanions_shards%, %petcompanions_discovered%, %petcompanions_total_types%.

Every one returns a printable value even for a player who is offline or has no pet out. None of them will leave raw %petcompanions_...% text sitting in a scoreboard.

Permanent buffs are claimed in the player's own persistent data rather than assumed. PetCompanions will only remove an infinite effect whose strength matches its own claim, and if another plugin still wants that effect it is handed back at their strength instead of being stripped. Two plugins that both do this settle on the strongest rather than taking turns cancelling each other.

Pet heals are proposed as real EntityRegainHealthEvents, so a combat or difficulty plugin can see, scale or refuse them.

Every pet body carries its owner's UUID at petcompanions:pet_owner. Most of the 230 are not tameable mob types, so that tag is the only reliable way for another plugin to tell a companion from wildlife.