# Pet System

# Pet System

![kyuubisoft](https://kyuubisoft.com/kyuubisoft_plugins.png)

**KyuubiSoft Companions (the plugin "KyuubiSoft Pets") adds three kinds of companions to a Hytale server: collector pets that pick up your loot, combat pets that fight next to you, and mounts you can ride. Every pet levels up, rolls its own stats and lives in an item you can carry, store or trade.**

---

## How pets work

- Every pet is bound to an item: a **Pet Egg** (collector pet), a **Battle Rune** (combat pet) or a **Mount Horn** (mount). Right-click the item to summon or dismiss the pet.
- The item only carries the pet's ID. Level, XP, stats and name are stored in the plugin's SQLite database (`pets.db`). Hovering the item shows the pet's name, level, rarity and unlocked stats.
- Whoever has the item has the pet. You can trade, sell or store pet items like any other item. A pet counts as owned while its item is in your inventory.
- A blank pet item (for example from a shop, a loot table or `/give`) hatches into a new pet with freshly rolled stats on its first right-click.
- You can have one collector pet, one combat pet and one mount out at the same time. Pets and mounts are sent home when you log out or change worlds; summon them again afterwards.
- Pet items are never dropped on death, whatever the world's death setting, also with KyuubiSoft Graveyard or Item Control installed.

---

## Modules

The three modules can be switched on and off one by one in `config.json` (`modules`). All three are on by default.

### Collector pets

- **26 collector pets** that follow you and pick up dropped items for you ("Baby Duck", "Fox", "Snow Owl", "Fire Dragon", ...).
- Pets earn XP when you kill mobs, break blocks or craft, and when they pick up an item.
- Each pet has 2 to 5 stat slots depending on its rarity (uncommon, rare, epic, legendary). Stats unlock at fixed levels and give you buffs such as damage, armor, crit chance, pickup range, pet XP or **Loot Luck** (a chance to receive an item the pet picks up a second time).
- **Pickup filter** per pet: whitelist or blacklist mode, rules by name, category or quality, and presets.
- Items you dropped yourself, your death drops and the contents of chests you break give no pet XP and no Loot Luck. Admins can exclude items from Loot Luck with the **loot luck blacklist**.

See [Collector Pets](./collector-pets).

### Combat pets

- **13 combat pets** that attack what you attack, defend you when a mob hits you and fight back when they are hit. They only attack NPCs, never players or other pets.
- Damage grows with the pet's level and its Damage stat. Combat pets earn XP and a kill count for their own kills; floating damage numbers show their hits.
- **Optional balance switches** (`combatBalance` in `config.json`, all off by default):
  - **Health, defeat and recovery**: combat pets get HP, can be defeated and then need 15 minutes (default) to recover. The recovery survives relogs, world changes and restarts. A **Battle Pet Revival Scroll** or an admin can end it early.
  - **Damage through Hytale's damage system**: pet hits respect armor, resistances and boss invulnerability phases.
  - **AFK protection**: combat pets stop fighting when their owner has been inactive for 120 seconds (default).

See [Combat Pets](./combat-pets).

### Mounts

- **9 rideable mounts**. Right-click the Mount Horn to summon the mount and ride it; right-click again or press **F** to get off.
- Each mount has its own speed. Other players see the mount move and animate.
- Mounts are dismounted and removed when you log out or change worlds.

See [Mounts](./mounts).

---

## Windows and tools

| Feature | What it does |
|---------|--------------|
| **Pet Compendium** | `/kspet` opens one window for all pets: tabs for collector pets, combat pets and mounts, filters *All / Owned / Missing*, a live 3D preview you can rotate and zoom, details and stats, and one card per owned copy with summon, dismiss, rename and revive. Pets you do not own show a "How to get it" hint. HUD settings sit in the header. |
| **Pet HUD** | A tracker (top left by default) with one card per active collector and combat pet: level, name, XP bar, HP bar (with mortality on), buffs, collected items or kills. A defeated combat pet shows its recovery countdown. Six positions, vertical or horizontal layout. |
| **Pickup filter** | `/kspet filter` or the filter button on a collector pet's card in the compendium. |
| **Reroll dice** | In the compendium every unlocked stat of an owned pet has a dice. One click uses one reroll scroll from your inventory and rerolls that stat; the dice above the stat column rerolls all unlocked stats for one Reroll All Scroll. Stats that grow with the level show their next-level value. |
| **Scrolls** | Reroll, Refine, Reroll All and Refine All scrolls for collector pets (`Pet_*`) and combat pets (`Battle_*`), plus the Battle Pet Revival Scroll. |
| **Restore lost items** | `/kspetadmin restore <player> [type \| id]` lists a player's pets whose item is missing and hands out a replacement egg, rune or horn with the pet's level, stats and name. Every older copy of that item stops working, so a restore cannot duplicate a pet. |
| **Admin window** | `/kspetadmin` opens "Pet Management" with three sections: **Create pet**, **Blacklist** (loot luck blacklist) and **Player pets** (level, XP, reroll, max out, revive, replace item, remove for good). With KyuubiSoft Core installed it is also a tile in the `/ksadmin` hub. |
| **Panel status page** | With the KyuubiSoft Panel plugin (KyuubiSoftAPI 2.1 or newer) installed, the panel's "Mod Status" page shows the active companions per world, the module switches and warnings, with **Reload configuration** and **Remove orphaned pet NPCs** as admin actions. See [Admin Panel](./admin-panel#kyuubisoft-panel-status-page). |

The windows use the KyuubiSoft "Goldfiligran" look. Its textures come from the shared KyuubiSoft UI kit inside the jar, so there is nothing extra to install.

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing the plugin, the files it creates, a first test |
| [Collector Pets](./collector-pets) | Pickup, XP, stats, Loot Luck, pickup filter |
| [Combat Pets](./combat-pets) | Fighting, health, defeat and recovery, AFK protection |
| [Mounts](./mounts) | Riding, speed, mount types |
| [Custom Pets](./custom-pets) | Adding your own pet types with JSON files |
| [Commands](./commands) | Every player and admin command |
| [Permissions](./permissions) | Permission nodes and their defaults |
| [Configuration](./configuration) | Every field of `config.json`, `stat-pool.json` and the blacklist |
| [UI Pages](./ui-pages) | The compendium, HUD, filter and scroll windows |
| [Admin Panel](./admin-panel) | The admin window and the admin tools |
| [Localization](./localization) | Languages and translation files |
| [API & Events](./api-reference) | Events for other plugins |
| [FAQ & Troubleshooting](./faq) | Common questions and problems |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Product** | KyuubiSoft Companions ([BuiltByBit](https://builtbybit.com/resources/kyuubisoft-companions.100098/)) |
| **Plugin** | KyuubiSoft Pets (manifest `kyuubisoft:pets`) |
| **Version** | 1.12.1 (2026-10-23) |
| **Jar** | `KyuubiSoftPets-1.12.1.jar` |
| **Player commands** | `/kspet` (aliases `/pet`, `/pets`), `/kscombatpet` (aliases `/combatpet`, `/cpet`; only with the combat module on), `/ksmount` (alias `/mount`; only with the mount module on), `/kslang` (language selection shared by all KyuubiSoft mods; the first one that loads registers it) |
| **Admin command** | `/kspetadmin` (alias `/petadmin`) |
| **Data folder** | `mods/kyuubisoft_pets/` |
| **Config** | `mods/kyuubisoft_pets/config.json`, `stat-pool.json`, `loot_luck_blacklist.json` |
| **Pet types** | `mods/kyuubisoft_pets/pet-types/{collector,combat,mount}/*.json` |
| **Pet data** | `mods/kyuubisoft_pets/pets.db` (SQLite) |
| **Localization** | `mods/kyuubisoft_pets/localization/<lang>.json` (9 languages, all complete) |
| **Pet counts** | 26 collector pets, 13 combat pets, 9 mounts |
| **Required** | Nothing besides the Hytale server; the SQLite driver is inside the jar |
| **Optional** | KyuubiSoft Core (merges new default fields into `config.json`, adds the admin window to the `/ksadmin` hub), KyuubiSoftAPI (status page in the KyuubiSoft Panel), DynamicTooltipsLib (extra pet details in item tooltips), KyuubiSoft Item Control (declared optional so it loads first; pet death protection is ordered around its death rules and drop prevention), KyuubiSoft Graveyard (pet items stay with the player instead of going into the gravestone) |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0)
- Java 25
- No other plugin is required. KyuubiSoft Core, KyuubiSoftAPI, DynamicTooltipsLib and Item Control are used when they are installed.