# Getting Started # 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](https://wiki.kyuubisoft.com/hytale/pets/#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/.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 `.json.backup-v`, so you can copy your own changes back. See [Localization](./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`: ```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](./configuration) and [Combat Pets](./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](./permissions)). 1. **Get a pet item.** Run `/kspetadmin give 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 wolf_combat` gives "Battle Rune: Wolf" (the combat pet "Kriegswolf"); right-click it and attack a mob. `/kspetadmin give 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](./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](./custom-pets).