🐾 Better Pets Paper

A full Paper plugin rewrite of the original Better Pets datapack.

!Minecraft !Java !Platform !Version !Type !License !Languages

---

✨ About

Better Pets Paper is a complete Paper plugin rewrite of the Better Pets datapack.

It does not require datapacks, command functions, minecart menus, or a manual resource pack. Everything is handled directly through the plugin. Optional animated 3D models are handled through BetterModel when that plugin is installed and the (experimental) module is enabled.

---

🆕 What's New in v1.9.3

• 🐉 Flying is less fiddly. Right-clicking your pet while flying no longer dismounts you — hop off by sneaking instead. And starting flight now needs a confirming second right-click, so you never take off by accident.
• 👁️ New commands: /pets visible and /pets invisible (aliases: show / hide) show or hide your active pet from chat, without opening the menu.

---

🆕 What's New in v1.9.2

• 🕊️ No more flight height cap. Pet mounts could only reach the world's build height (~Y 319). You can now fly well above it into open sky — capped only by a generous, configurable safety ceiling (flight-max-height, default 1024).

---

🆕 What's New in v1.9.1

• 🐉 Fix: flying pets no longer clip you into blocks. The mount's collision now samples your whole body (not just the centre), and while flying you can never take suffocation damage from briefly touching a block.
• 🚫 Pets no longer get in your way. Pet hitboxes are now non-attackable and, for pets without a right-click action, tiny — so they never block your mining, attacking, or building. Pets that do use right-click (the Alpaca and the flyable dragons/Phoenix) keep a clickable hitbox; hide any pet with the visibility toggle in /pets if it's ever in the way.

---

🆕 What's New in v1.9.0

⬆️ Minecraft / Paper 26.2

• The plugin now targets Paper 26.2 (api-version: '26.2'), built against paper-api 26.2.build.62-beta and Adventure 5.2.0.
• No gameplay changes — the entire codebase compiled against 26.2 without a single source change; only the build and API target moved.
• build.ps1 now downloads the Paper API and the matching Adventure 5.x jars itself, and orders the classpath so newer Adventure wins over older server libraries.

⚠️ Note: Paper 26.2 is currently an experimental/beta branch (26.1.2 is the stable one). Because api-version is now 26.2, this build requires a 26.2 server — if you are still on 26.1.2, stay on v1.8.1.

---

🆕 What's New in v1.8.1

• 🎰 Fix: the slot machine's featured pet no longer re-rolls every time you open /pets slots. It now stays the same until you actually spin, and is remembered per player.

---

🆕 What's New in v1.8.0

🎰 Slot machine, expanded

• Way more loot in the reels: gold nuggets, coal, iron, copper, redstone, lapis, gold ingots, XP bottles, emeralds, diamonds, netherite scrap & ingots — each with its own chance (netherite stays rare).
• Real slot feel: the three reels now settle left → middle → right.
• A featured pet every spin is shown above the reels — land on the pet symbol to win that pet, with a chat message and an optional server-wide jackpot broadcast. The pet chance was bumped up a little (still rare).
• Spinning now costs just 1 token.
• Admin loot editor: a Configure Loot button inside /pets slots opens a GUI to adjust every reward's chance live (left/right-click ±1, shift ±10, shows the %). Everything is also under tokens: in config.yml.

🎟️ Token commands

• /pets tokens pass <player> <amount> — send some of your tokens to another player (anyone can use it).
• /pets tokens give|remove <player|all> <amount> — admins hand out or take back tokens (works from console too).

---

🆕 What's New in v1.7.0

🎟️ Pet tokens & 🎰 the slot machine

• Duplicate pets are no longer dead weight. Turn any pet item into pet tokens with /pets scrap (the item in your hand) or /pets scrap all (every pet item in your inventory). Check your balance with /pets tokens.
• Tokens by rarity: Common 1 · Rare 2 · Epic 3 · Legendary 4 · Mythical 5 (all configurable).
• /pets slots opens an animated slot machine: spend tokens per spin to pull gold nuggets → iron → gold → diamonds → netherite, or — very, very rarely — another pet (~0.5 %, the pulled pet chosen by spawn weight). Tuned to be a fun sink for duplicates, not a farm.
• Fully configurable under tokens: in config.yml; set tokens.enabled: false to switch the whole feature off.

---

🆕 What's New in v1.6.0

🌍 Localization — English / Deutsch / Polski

• All player-facing text now lives in plugins/BetterPets/lang/<code>.yml (bundled: en, de, pl). Pick one with language: in config.yml, or switch live with /pets language <en|de|pl>.
• Upgrade-safe: new message keys are merged into your language files on every start, so your custom text survives updates. A legacy messages: block in config.yml is migrated automatically.
• Messages support MiniMessage formatting (<gradient:#a:#b>, <bold>, colours). Substituted values are escaped, so a player-chosen pet name can never inject formatting.

🎨 Nicer look

• Gradient GUI titles and a gradient [BetterPets] broadcast prefix.
• Prettier level-up, Phoenix revive, booster and convert messages.
• config.yml reorganized into numbered, documented sections.

🙂 Quality of life

• Convert To Item now asks for a confirming second click and keeps the pet's level and in-level XP on the item, so nothing is lost on a misclick.
• /pets mute — hide discovery/booster broadcasts (text and sound) just for yourself; persists across relogs.
• Middle-click a pet in the Spawn Chances menu (or the XP Multiplier) to type an exact value in chat.
• A one-time /pets help hint the first time you open the menu.

🛠️ Fixes & performance

• Phoenix revive no longer fires (and wastes its cooldown) on a hit fully soaked by absorption hearts.
• Experience-orb XP is no longer double-counted toward the active pet.
• The auto-updater is now config-driven and opt-in (update.repo / update.enabled) — no more placeholder repository.
• Interactive saves are coalesced, the XP multiplier is cached, the Penguin container scan interval is configurable, and debug-logging now defaults to off.

🔒 Permissions

• The XP Multiplier control and the /pets drop (Pet Sources) menu now require betterpets.admin (previously betterpets.chances).

🧑‍💻 Under the hood

• Per-pet data and behaviour moved into a single PetAbilities registry, and the menu holders and updater were split out of the main class — adding a new pet is now far less work.
• Added a small dependency-free test suite (test.ps1).

---

🆕 What's New in v1.5.3

• 🐉 Fix: Shadow Dragon no longer crashes the server. Its on-hit AoE burst damaged nearby mobs as the player, which re-fired the damage event and triggered the burst again — an infinite loop that spammed the console with StackOverflowError. The burst now guards against re-entry, so it fires exactly once per hit.

---

🆕 What's New in v1.5.2

• 🐧 Fix: Penguin container glow no longer blocks chests. The glow used an invisible Shulker, whose hitbox intercepted your clicks (you couldn't open the container) and could even be attacked. It now uses a BlockDisplay, which has no hitbox — clicks pass straight through to the container and it cannot be attacked or killed. Same owner-only through-wall glow, now in cyan.

---

🆕 What's New in v1.5.1

• ⚔️ Shadow Dragon AoE is now on-hit. The burst only fires when you attack and the cooldown is ready; after firing, the boss bar counts down and the next hit triggers it again (instead of pulsing on a timer). The bar now reads "Shadow Dragon AOE ready — attack!" when charged.
• 👛 Goblin steal notification. When your Goblin snatches the emeralds back from a villager, you now get a clear player-only chat message (plus the action-bar flash), so you actually notice the free trade.
• 🐧 Penguin Treasure Sense is now a glow. Instead of particle markers, nearby containers a player has never opened now glow through walls, for you only — chests, trapped chests, barrels and chest minecarts. It also catches worlds that pre-generate loot (where the container looks "opened" but nobody touched it): a container stops glowing only once a player actually opens it. Reach grows with level (up to 24 blocks).

---

🆕 What's New in v1.5.0

🎨 Rarity overhaul

• Epic is now pink and the old Extraordinary tier is renamed to Mythical (dark purple). Every pet you already own updates automatically — rarity is read live from the pet list, nothing is stored per pet.
• Goblin promoted to Mythical. All six former Extraordinary pets (Herobrine, Phoenix, Reaper, Ender Dragon, Shadow Dragon, Ancient Elf) plus the Goblin are now Mythical. (extraordinary still works as a config/legacy alias.)

✨ Particle effects

• Every Epic-and-above pet now has a fitting ambient particle aura while it is visible — Pixie fae sparkles, Lich souls, Goblin emerald glints, Phoenix embers, Warden sculk, and more. Dragons and the Unicorn keep their existing trail/glitter.

🐾 Ability reworks

• Shadow Dragon — its aura became a cooldown AoE burst: a ring of shadow particles briefly appears, nearby hostiles take damage, and a boss bar shows "Cooldown to AOE Damage". The cooldown shrinks as it levels (~12s → 4s).
• Ender Dragon — now deals bonus damage in every dimension, not just The End.
• Mole — now saves durability on any block you break with an axe, pickaxe or shovel (was dirt/sand/gravel only).
• Goblin — dropped the coin-on-kill perk; instead a small level-scaled chance that a villager purchase refunds its emerald cost (a free buy). Cheaper trades stay.
• Penguin — new Treasure Sense: client-side markers only you can see on nearby unlooted structure chests/barrels, radius growing with level.
• Chicken — keeps Slow Falling and now lays eggs over time, more often and more at once as it levels.
• Pixie — grants more simultaneous random buffs at higher amplifiers as it levels.
• Pufferfish — same undead wither aura, now wider and stronger with level.
• Koala — same tree-rest heal, Regeneration I → III with level.
• Bee — fixed: standing next to plain flowers (poppy, dandelion, …) now correctly grants Regeneration.

⚡ Performance

• Penguin's chest scan only checks loaded chunks via a cheap container filter; ambient particles and scans are throttled; the Shadow Dragon boss bar reuses the existing tick loop.

---

🆕 What's New in v1.3.2

• 📢 Fix: pre-generated chest broadcasts. When a chest's loot was rolled before it was opened (e.g. at world/chunk generation), the pet was placed but the find message never fired. Now the pet is marked at loot time and the broadcast fires when a player opens the container (or picks the item up), crediting whoever opened it.

---

What's New in v1.3.1

• /pets xpboost give <x2-x5> <time> [player]: gives Pet XP Booster items with flexible times like 30m, 1h, 1h30m, or 1d (permission: betterpets.give).
• Custom pet names survive item conversion: converting a renamed pet back into an item now stores and restores the name.
• Safer items: Better Pets items and XP Boosters cannot be renamed through anvils.
• Booster broadcasts and sounds: XP Booster drops and activations now announce which booster appeared/was used.
• Cleaner lore/help: Booster and pet item lore plus /pets help now match the newer menu style.

---

🆕 What's New in v1.3.0

• ⚡ Pet XP Boosters! Hostile mobs can rarely drop a Pet XP Booster (x2-x5) that lasts 15/30/45/60 minutes. Right-click to activate; it speeds up pet leveling only (never your own XP), does not stack, and its timer only counts down while you are online. Boosters are stackable as items but a second one won't add more effect. Drop chance is configurable in /pets drop and config.yml. The main menu shows your booster status (for admins, next to the XP Multiplier).
• ✏️ Rename pets: /pets set name <name> renames your summoned pet (keeps all level/XP/abilities), /pets restore name restores the default. The custom name shows on the hologram — for head pets and BetterModel pets.
• 📖 Catalogue: now shows each pet's rarity and default drop weight, plus clearer level-milestone rewards.
• 🛟 Safer data: corrupted pets.yml is quarantined (never silently wiped), one broken pet no longer drops a whole player's data, and there are daily backups (storage.backup, kept for keep-days).
• 🗄️ Storage settings + SQLite seam: new storage config (type: yaml default, plus backup options). sqlite is a documented opt-in for a later build; selecting it now safely stays on YAML.
• 🧰 Config: every option is now commented, and missing options are repaired automatically on start (your values are kept).
• 🧱 BetterModel: model validation warnings (flags synced .bbmodel files BetterModel didn't load, or models without animations) and clearer head-fallback reasons.

---

🆕 What's New in v1.2.7

• 📢 Reliable chest broadcasts everywhere: find notifications now fire for all containers, including chests in custom/data-pack structures (e.g. strongholds) where the previous opener lookup could miss. The opener is resolved via the loot event's entity, then the recorded interaction, and finally the nearest player to the container.

---

🆕 What's New in v1.2.6

• 🗝️ Vault & Trial Spawner sources: pets can now also drop from Vaults and Trial Spawners — both vanilla and data-pack ones — added straight into their dispensed loot.
• 🌀 Ominous bonus: when the Vault/Trial Spawner is ominous (any Ominous Bottle / Bad Omen level 1-5), a configurable ominous-bonus-percent is added on top of the base chance, so harder runs reward pets more often.
• 📢 Broadcasts: Player found a … Pet in a Vault! / … in a Trial Spawner!.
• ⚙️ Both new sources are fully configurable in /pets drop and config.yml, like every other source.
• 🪥 Fix: brushing now replaces the item inside the suspicious sand/gravel, so the pet is brushed out of the block naturally instead of popping in above it.
• 📢 Fix: Trial Spawner pets now broadcast — since the dispense has no triggering player, the find message fires when the pet is picked up.

---

🆕 What's New in v1.2.5

• 🎣 New pet sources! Pets can now also be obtained from fishing, Wandering Traders, and brushing suspicious sand/gravel — on top of the existing chest loot.
• 🧰 /pets drop GUI: toggle each source on/off and tune its chance, just like chest spawn chances. (Permission: betterpets.chances.)
• 🐟 Fishing: a small chance (lower than chests) to fish out a pet, with a Player fished out a … Pet! broadcast.
• 🧳 Wandering Trader: a spawning trader can carry a one-time deal to buy a pet; the price scales with rarity and uses emeralds plus other valuables (gold, diamonds, netherite). Buying it broadcasts Player bought a … Pet from a Wandering Trader!.
• 🪥 Brushing: a small chance to brush a pet out of suspicious sand/gravel, with a Player brushed out a … Pet! broadcast.
• ⚙️ Every source has its own configurable chance and on/off toggle, just like chests.
• 🧰 Fix: a double chest can no longer hand out two pets — both halves now share a single roll.

---

🆕 What's New in v1.2.4

• 👀 Pets look at you again: fixed the recurring bug where pets faced the player's gaze direction instead of looking at the player (a regression from 1.2.2). Documented in code so it cannot be flipped again.
• ⬇️ /pets update: downloads the latest release jar straight from GitHub into the server's update folder; it is applied automatically on the next server restart. Admin only.
• 📢 Double-chest discovery broadcasts: fixed missing find notifications when opening double chests (and other containers) — the opener is now matched against both halves of a double chest, so the broadcast no longer gets lost.

---

🆕 What's New in v1.2.3

• ⛏️ Mending-proof XP: pet XP now counts the full value of every experience orb (mining, mobs, furnaces, fishing, trading…) before Mending diverts any of it to tool repair — so ore XP always counts.
• ⚡ Lighter saving: the storage file is no longer written on every single XP gain; XP is persisted by the periodic autosave and on quit/disable.
• 🔎 /pets version: shows the plugin version, which modules are on, and checks GitHub Releases for a newer version (asynchronously).
• 🎞️ Animation-driven movement: a model is grounded or flying based on its own animations (walking vs flying), or forced by a model-name suffix (ant_grounded / ant_flying). The model-movement-mode config option was removed.
• 🚀 Performance: grounded models cache their ground height per block column instead of ray-casting every tick.

---

🎯 Target

Requirement	Version / Info
Minecraft / Paper	26.1.2
Java	21 (Java 25 recommended when using BetterModel 3.x)
Optional Dependency	LuckPerms for permission assignment
Optional Dependency	BetterModel 3.x for animated .bbmodel pets

---

🌟 Features

• 🐾 /pets inventory GUI for owned pets
• 📖 Pet catalogue with per-level milestone pages
• 🎲 Per-pet chest spawn chance GUI
• 📢 Discovery broadcast GUI by rarity, with rarity-based sounds
• ✨ Pet XP multiplier GUI
• 💾 Persistent player pet storage with backups
• 🦙 Owner-only Alpaca storage using Paper item byte serialization
• 📦 Dynamic Alpaca storage size based on level
• 🐉 Dragon mount flight unlocked from level 50
• 🏛️ Chest loot integration for vanilla and custom structure containers
• 🧩 Optional 3D pet rendering through BetterModel, with a clean head fallback

---

💬 Commands

Command	Description
/pets	Opens the main pet menu
/pets version	Shows version, active modules, updates
/pets update	Downloads the latest version (admin)
/pets help	Shows command help
/pets info	Opens the pet catalogue
/pets chances	Opens spawn chance settings
/pets notify	Opens discovery broadcast settings
/pets drop	Choose pet sources (chest/fishing/...)
/pets modules	Opens optional module settings
/pets reload	Reloads config, modules, models, pets
/pets give <pet|all> [level] [player]	Gives test pet items
/pets xpboost give <x2-x5> <time> [player]	Gives Pet XP Booster items

---

🔐 Permissions

Permission	Description
betterpets.command.pets	Allows opening the main pet menu
betterpets.info	Allows opening the pet catalogue
betterpets.chances	Allows editing spawn chances, broadcasts, and XP multiplier
betterpets.give	Allows giving test pet items
betterpets.admin	Grants all admin actions, including /pets modules and /pets reload

---

⚙️ Important Config

max-pets-per-player: 45
chest-pet-chance-percent: 2.5
pet-xp-multiplier: 1.0
dragon-flight-speed: 1.5
dragon-flight-lift: 0.55
debug-loot-rolls: false

# External modules (BetterModel) are experimental and disabled by default.
experimental-modules: false

# Model rendering (only used when the BetterModel module is enabled)
model-ground-offset: 0.05
model-nametag-height: 2.6
model-facing-yaw-offset-degrees: 0.0

discovery-broadcasts:
  common: true
  rare: true
  epic: true
  legendary: true
  mythical: true

model-overrides: {}

---

🧩 Optional Modules

⚠️ Experimental. External modules (such as BetterModel) are experimental and disabled by default. While experimental-modules: false in config.yml, the /pets modules command is blocked and no external module is activated, even if it is enabled in modules.yml. Set experimental-modules: true to opt in.

Module state is stored in:

plugins/BetterPets/modules.yml

Modules are toggled in /pets modules (once experimental-modules is enabled). A module can only be enabled when its required plugin is installed and enabled. If a module is enabled in modules.yml but the required plugin is missing, Better Pets keeps the flag and skips activation until the dependency becomes available.

---

🪄 BetterModel Module

The bettermodel module requires the BetterModel plugin. When enabled, pets render as animated 3D .bbmodel models instead of floating pet heads.

Model folder:

plugins/BetterPets/models/

File naming (the name without .bbmodel is matched case-insensitively to the pet id/name):

ant.bbmodel
bat.bbmodel
blue_dragon.bbmodel

Override model names per pet in config.yml:

model-overrides:
  Ant: tiny_ant
  Blue Dragon: blue_dragon_variant

🎞️ Animations & movement

Better Pets reads the animations declared inside each .bbmodel and drives them automatically:

Animation	When it plays
idle	The owner is standing still
walking	The owner is moving and the model is grounded
flying	The owner is moving and the model is flying
idle2 … idle9	Optional random idle variants while standing still

Whether a model is grounded or flying is decided automatically: a flying animation means it flies, a walking animation (without flying) means it walks on the ground. You can also force it through the model name: a model ending in _grounded always walks, and _flying always flies (e.g. ant_grounded.bbmodel).

🔄 Reloading models

When the module is enabled or /pets reload is run, Better Pets scans plugins/BetterPets/models/, copies changed .bbmodel files into BetterModel's models/ folder, and reloads BetterModel. It first tries the BetterModel API reload and falls back to the console command:

bettermodel reload

If BetterModel is missing, disabled, or has no matching loaded model, Better Pets falls back to the pet-head rendering.

📦 Resource pack note

BetterModel generates its own resource pack from the .bbmodel files and embedded textures. Vanilla clients still need BetterModel's auto-send / host resource-pack option enabled on the server.

---

🦙 Alpaca Storage

Alpaca storage is owner-only and saved inside:

plugins/BetterPets/pets.yml

Items are stored with ItemStack.serializeItemsAsBytes, preserving modern item data such as custom enchantments, PersistentDataContainer values, plugin metadata, and Paper item data.

Alpaca Level	Storage Size
Level 1	9 slots
Level 30	18 slots
Level 50	27 slots
Level 70	36 slots
Level 100	54 slots

An Alpaca with stored items cannot be switched away, despawned, or converted into an item until its storage is empty.

---

🛠️ Building

With Maven:

mvn clean package

Local fallback build script:

.\build.ps1

The output jar is created at:

target/better-pets-26.1.2-plugin.jar

---

📦 Installation

1. Build the jar (or download it from the latest release).
2. Put better-pets-26.1.2-plugin.jar into the Paper server's plugins folder.
3. Install BetterModel only if you want animated 3D models.
4. Start the server once to generate config and storage files.
5. Use LuckPerms or paper-plugin.yml defaults to assign permissions.
6. (Optional) Put .bbmodel files into plugins/BetterPets/models/, set experimental-modules: true, enable the module in /pets modules, then run /pets reload.

---

🏛️ Chest Loot Notes

Pet rolls happen when Minecraft generates container loot for unopened generated containers (chests, double chests, barrels, and other block containers), including custom structures from data packs.

• Existing opened containers will not reroll.
• Each generated container can get at most one Better Pets item.
• Enable debug-loot-rolls: true to see loot roll attempts in the console.

---

🐾 Pet Sources

Pets can drop from four sources, each toggleable and tunable in /pets drop (or config.yml under pet-sources):

Source	How	Default chance
Chests	Generated container loot (chests, double chests, barrels, custom structures)	chest-pet-chance-percent (2.5%)
Fishing	Fish one out (replaces the catch)	1.0%
Wandering Trader	A spawned trader carries a one-time pet deal priced by rarity	25% per trader
Brushing	Brush one out of suspicious sand/gravel	1.5%

Each find shows a broadcast (e.g. Player fished out a Rare Pet: Axolotl!), gated by the same per-rarity toggles as /pets notify.

---

🗒️ Previous Releases

• v1.2.4 — Pets look at the player again (facing fix), /pets update, double-chest discovery broadcasts.
• v1.2.3 — Mending-proof XP, lighter saving, /pets version, animation-driven model movement, ground-height caching.
• v1.2.2 — Optional module system (experimental) + BetterModel module; particles stop when the pet is hidden.
• v1.2.1 — Owner-only glow reveal (through walls) for Bat / Red Parrot / Warden.
• v1.2.0 — Multiplayer fixes: personal Herobrine weather, Allay no longer takes others' items, crash-safe join cleanup, double chests + barrels.
• v1.1.0 — Three new pets (Mole, Allay, Cursed Plushie), reworked Phoenix revive, rarity broadcast sounds, EXP: MAXED.

---

📜 Credits

This project is a Paper plugin rewrite inspired by the original Better Pets datapack.

🔗 Better Pets on Modrinth

All rights to the original project, name, concepts, assets, and related content belong to their respective rights holders.

---

⚠️ Disclaimer

This project is not an official update, not an official continuation, and not directly affiliated with the original Better Pets project, unless explicitly stated otherwise. It does not claim ownership of the original project. If the original author or rights holder wants specific content removed, changed, or credited differently, please contact the repository owner.

---

📄 License

The source code of this Paper plugin rewrite is released under the MIT License — see LICENSE.

This covers the plugin's own code only. The original Better Pets name, concepts, and assets remain with their respective rights holders (see Credits and Disclaimer above).