Getting Started

Installation

1. Stop the server.
2. Put KyuubiSoftPets-1.12.1.jar into the server’s mods/ folder. When you update, remove the old KyuubiSoftPets-*.jar first.
3. Start the server. The plugin creates its data folder mods/kyuubisoft_pets/ and fills it with the default files.

Nothing else is required: the SQLite driver and the UI textures are inside the jar. KyuubiSoft Core, DynamicTooltipsLib and KyuubiSoft Item Control are used when they are installed (see Requirements).

---

Files after the first start

mods/
  KyuubiSoftPets-1.12.1.jar
  kyuubisoft_pets/
    config.json               main configuration
    stat-pool.json            stats, value ranges and rarity rules
    loot_luck_blacklist.json  items excluded from Loot Luck (empty by default)
    pet-types/
      collector/              26 collector pets + _template.json
      combat/                 13 combat pets + _template.json
      mount/                  9 mounts + _template.json
    localization/             en-US.json, de-DE.json, fr-FR.json, es-ES.json, pt-BR.json,
                              it-IT.json, pl-PL.json, tr-TR.json, ru-RU.json
    npc-roles/                NPC roles of pets and mounts (rewritten on every start)
    pets.db                   SQLite database with every pet (level, XP, stats, name, filter)
    pet_state.json            pet and mount NPCs to clean up after a crash
    data/players/<uuid>.json  per player: active pets, bestiary, HUD settings, totals
  kslang/                     language choice shared by all KyuubiSoft mods

Some files only appear once they are first written (for example data/players/ after the first player joins). While the server runs, SQLite also keeps pets.db-wal and pets.db-shm next to the database.

Caution

Do not edit npc-roles/: the plugin deletes and rewrites those files on every start.

What happens to your files on an update

• config.json, stat-pool.json, loot_luck_blacklist.json and the pet type files are never overwritten. A shipped pet type file is only written when it is missing, so delete a file if you want the shipped version back.
• New config sections are added for you: with KyuubiSoft Core installed, new default fields are merged into config.json; without Core, the plugin adds missing combatBalance and ui blocks and the 1.11.1 keys maxPetsEverywhere and combatBalance.levelUpCombatStatsOnly itself. Both new keys default to false, so nothing changes until you switch them on.
• Localization files are replaced when the jar ships a newer version. The old file is kept as <lang>.json.backup-v<old version>, so you can copy your own changes back. See Localization.
• New database columns are added to pets.db automatically.

---

Turning modules on and off

All three modules are on by default. Switch them in config.json:

{
  "enabled": true,
  "modules": {
    "collector": true,
    "combat": true,
    "mount": true
  }
}

Restart the server after changing modules: the module systems and the /kscombatpet and /ksmount commands are only registered at startup. A disabled module keeps its pets in the database. Its tab is hidden in the compendium, and its runes or horns refuse to summon.

Combat pet health, defeat and AFK protection are separate switches under combatBalance and are all off by default. See Configuration and Combat Pets.

Tip

/kspetadmin reload (or “Reload” in the admin window) reloads config.json, the pet types, stat-pool.json, the loot luck blacklist and the languages without a restart. Module switches still need a restart.

---

First test

You need the ks.pet.admin permission for the admin command (see Permissions).

1. Get a pet item. Run /kspetadmin give <yourname> duck. You receive a “Baby Duck Egg”. Instead of the command you can open the admin window with /kspetadmin, pick a pet in Create pet, leave the recipient empty (that means yourself) and create it.
2. Summon it. Hold the egg and right-click. The Baby Duck appears and follows you, and the pet HUD shows its card (top left unless hudPosition in config.json says otherwise).
3. Watch it collect. Mine a few blocks: the pet picks up the drops and earns XP. Items you drop yourself are collected too, but give no pet XP.
4. Open the compendium. Run /kspet. Your duck is listed under Collector pets with its level, stats and the live 3D preview.
5. Try the other modules. /kspetadmin give <yourname> wolf_combat gives “Battle Rune: Wolf” (the combat pet “Kriegswolf”); right-click it and attack a mob. /kspetadmin give <yourname> horse_mount gives “Mount Horn: Horse”; right-click it to ride and press F to get off.

The type name is the id from the pet type file; for the shipped pets it is the file name without .json (duck, wolf_combat, horse_mount, …). /kspetadmin give only works for players who are online, delivers the item into their inventory and refuses when the player already has maxPetsPerPlayer pets (default 5). See Commands for all admin commands.

Note

The shipped combat pets and mounts have German display names (“Kriegswolf”, “Pferd”, …). You can rename any pet type by changing its displayName in the pet type file.

---

Adding a pet type

1. Copy _template.json in the matching folder (pet-types/collector/, combat/ or mount/) and give the copy its own name. Files that start with _ are ignored.
2. Set at least a new id, a displayName and the entity model.
3. Restart the server. If the pet’s summon item does not exist yet, the plugin writes one into mods/KyuubiSoftPets_CustomItems/ and tells you in the log to restart once more so the item is loaded.

The full guide with every field is in Custom Pets.