Configuration

Configuration

The main configuration is in plugins/Pets/config.json.

Full Config Structure

{
  "enabled": true,
  "modules": {
    "collector": true,
    "combat": true,
    "mount": true
  },
  "maxPetsPerPlayer": 5,
  "pickupTickIntervalMs": 1000,
  "followTickIntervalMs": 2000,
  "autoSaveIntervalSeconds": 300,
  "petDespawnOnDisconnect": true,
  "petTeleportDistance": 30,
  "hudPosition": "top-left",
  "hudLayout": "vertical",
  "xpSources": {
    "mobKill": 25,
    "blockBreak": 2,
    "crafting": 10,
    "itemPickup": 2,
    "passivePerMinute": 1
  },
  "defaultFilterMode": "blacklist",
  "defaultBlacklist": ["Dirt", "Sand", "Gravel", "Cobblestone"]
}

Field Reference

General

Field	Type	Default	Description
enabled	boolean	true	Master switch for the entire pet system
modules.collector	boolean	true	Enable pickup pets (follow + auto-collect)
modules.combat	boolean	true	Enable combat pets (battle companions)
modules.mount	boolean	true	Enable rideable mounts
maxPetsPerPlayer	int	5	Maximum number of pets a player can own
petDespawnOnDisconnect	boolean	true	Remove the pet NPC when the owner disconnects

Tick Intervals

Field	Type	Default	Description
followTickIntervalMs	int	2000	How often the follow service checks pet distance (ms)
pickupTickIntervalMs	int	1000	How often the pickup system scans for items (ms)
petTeleportDistance	int	30	Distance (blocks) before pet teleports to owner
autoSaveIntervalSeconds	int	300	Auto-save interval for player data

HUD Settings

These are the server defaults. Players can override their HUD position and layout via the /kspet menu at any time.

Field	Type	Default	Description
hudPosition	string	"top-left"	Default position of the Pet Tracker HUD
hudLayout	string	"vertical"	Default layout direction of the HUD

hudPosition values:

Value	Description
top-left	Upper-left corner
top-right	Upper-right corner
middle-left	Center-left edge
middle-right	Center-right edge
bottom-left	Lower-left corner
bottom-right	Lower-right corner

hudLayout values:

Value	Description
vertical	Pet info stacks vertically (default)
horizontal	Pet info lays out horizontally

Pickup Filter Defaults

Field	Type	Default	Description
defaultFilterMode	string	"blacklist"	Default filter mode for new pets (blacklist or whitelist)
defaultBlacklist	string[]	["Dirt", "Sand", "Gravel", "Cobblestone"]	Items blocked by default in blacklist mode

XP Sources

Field	Type	Default	Description
xpSources.mobKill	int	25	XP per mob kill
xpSources.blockBreak	int	2	XP per block broken (skipped for container blocks — chests, crates)
xpSources.crafting	int	10	XP per item crafted
xpSources.itemPickup	int	2	XP per item picked up by pet (skipped for player-dropped items)
xpSources.passivePerMinute	int	1	Passive XP per minute while pet is active

Note

Pickup XP, the items-collected counter, and the Loot Luck duplication roll are all suppressed when the picked-up item is recognized as player-dropped. This covers manual Q-drops, death drops, and the contents of broken containers — collecting your own loot does not credit any pet progression. Block-break XP additionally skips chests, crates, and other ItemContainerBlock blocks to prevent chest-XP-farming.

---

Loot Luck Blacklist

A separate file, plugins/Pets/data/loot_luck_blacklist.json, holds item-id patterns that block the Loot Luck duplication roll regardless of pickup source. Created automatically on first load (empty by default — extracted from defaults/loot_luck_blacklist.json).

{
  "patterns": [
    "*_Tool_*",
    "*_Weapon_*",
    "Ore_*",
    "Dirt"
  ]
}

Pattern style	Behavior
Plain text (no *)	Substring match, case-insensitive (Dirt matches Dirt, DirtBlock, Dirt_Coarse)
Wildcard *	Treated as regex .* (*_Tool_*, Ore_*, *_Spear)

Edit through the in-game admin UI (/kspetadmin lootluck) or directly on disk and run /kspetadmin reload. The UI live-saves on every mutation and rebuilds the compiled-pattern cache, so changes hit the next pickup tick without a reload.

The blacklist only suppresses the Loot Luck duplication chance — the pet still picks up the item normally. Use the per-player Pickup Filter if you want the pet to ignore items entirely.

---

Pet Type Definitions

Pet types are defined as individual JSON files in plugins/Pets/pet-types/{module}/.

pet-types/
  collector/   — Pickup Pets (summoned via Pet Eggs)
  combat/      — Combat Pets (summoned via Battle Runes)
  mount/       — Mounts (summoned via Mount Horns)

Adding a new pet type: drop a .json file into the matching subfolder. The module is auto-detected from the folder name if not set in the JSON.

Collector Pet (Pickup Pet)

{
  "id": "wolf",
  "displayName": "Wolf",
  "entityTypeId": "Wolf_Black",
  "modelScale": 0.25,
  "followDistance": 3.0,
  "followSpeed": 5.0,
  "pickupRadius": 1.5,
  "maxLevel": 50,
  "baseXpPerLevel": 100,
  "xpScaleFactor": 1.15,
  "eggItemId": "Pet_Egg_Wolf",
  "rarity": "uncommon",
  "description": "A loyal wolf companion. Fast and agile."
}

Field	Type	Required	Description
id	string	yes	Unique identifier
displayName	string	yes	Name shown in UI
entityTypeId	string	yes	Hytale NPC entity type to spawn
modelScale	float	yes	Visual scale of the NPC model
followDistance	float	yes	Distance (blocks) the pet tries to stay from owner
followSpeed	float	yes	Movement speed of the follow AI
pickupRadius	float	yes	Radius (blocks) for auto item collection
maxLevel	int	yes	Maximum pet level
baseXpPerLevel	int	yes	XP required for level 2
xpScaleFactor	float	yes	Multiplier applied to XP requirement each level
eggItemId	string	no	Item ID for the summon egg (auto-generated as Pet_Egg_{Id} if omitted)
rarity	string	yes	Rarity tier (see below)
description	string	no	Tooltip/UI description

Combat Pet

{
  "id": "wolf_combat",
  "displayName": "Kriegswolf",
  "entityTypeId": "Wolf_Black",
  "modelScale": 0.5,
  "followDistance": 3.0,
  "followSpeed": 6.0,
  "maxLevel": 50,
  "baseXpPerLevel": 120,
  "xpScaleFactor": 1.15,
  "rarity": "rare",
  "description": "Ein treuer Kriegswolf. Kaempft an deiner Seite.",
  "module": "combat",
  "runeItemId": "Battle_Rune_Wolf",
  "combatStats": {
    "baseDamage": 8.0,
    "damagePerLevel": 0.5,
    "attackSpeed": 2.0,
    "attackRange": 3.0,
    "aggroRange": 15.0,
    "leashDistance": 20.0,
    "attackAnimation": "Bite",
    "attackAnimationsId": "Wolf_Black_Default"
  }
}

combatStats fields:

Field	Type	Description
baseDamage	float	Base damage at level 1
damagePerLevel	float	Additional damage gained per level
attackSpeed	float	Attacks per second
attackRange	float	Melee attack range (blocks)
aggroRange	float	Range at which the pet detects hostile targets
leashDistance	float	Max distance before the pet gives up a chase and returns
attackAnimation	string	Animation name played on attack
attackAnimationsId	string	Animation set ID (entity-specific)

The module field must be "combat", or the file must be placed in the combat/ subfolder. The runeItemId is auto-generated as Battle_Rune_{Id} if omitted.

Mount

{
  "id": "rex_cave_mount",
  "displayName": "Hoehlen-Rex",
  "entityTypeId": "Rex_Cave",
  "modelScale": 1.2,
  "maxLevel": 40,
  "baseXpPerLevel": 180,
  "xpScaleFactor": 1.18,
  "rarity": "epic",
  "description": "Ein gewaltiger Hoehlen-Rex.",
  "module": "mount",
  "hornItemId": "Mount_Horn_Rex_Cave",
  "mountConfig": {
    "mountType": "walk",
    "mountYOffset": 3.5,
    "speed": 1.5,
    "baseHealth": 150
  }
}

mountConfig fields:

Field	Type	Default	Description
mountType	string	"walk"	"walk", "fly", or "swim" — determines the NPC motion controller
mountYOffset	float	2.5	Vertical offset of the rider above the mount
speed	float	1.5	Speed multiplier
baseHealth	float	200	Mount NPC health

The module field must be "mount", or the file must be placed in the mount/ subfolder. The hornItemId is auto-generated as Mount_Horn_{Id} if omitted.

---

Rarity Levels

Rarity	Color	Max Stats	Unlock Levels	Quality Range
uncommon	Green	2	1, 10	0.0 - 0.7
rare	Blue	3	1, 8, 16	0.0 - 0.85
epic	Purple	4	1, 6, 12, 20	0.0 - 1.0
legendary	Gold	5	1, 5, 10, 15, 25	0.0 - 1.2

Stats unlock as the pet levels up. The first stat is always available at level 1. Additional stat slots unlock at the levels listed above based on rarity.

Quality Range determines how good or bad a stat roll can be. A quality of 0.0 = minimum possible value, 1.0 = maximum. Legendary pets can exceed the base maximum (up to 1.2x) for exceptionally strong rolls.

---

Stat Pool

All pets draw random stats from a shared pool of 11 stats. Each stat has a base value range (at level 1) and a per-level growth range.

Stat Type	Display Name	Base Range	Per-Level Range
damage_bonus	Damage	0.01 - 0.08	0.002 - 0.015
max_health	Max Health	2 - 20	1 - 5
pickup_radius	Pickup Range	0.3 - 3.0	0.05 - 0.5
xp_bonus	Pet XP	0.01 - 0.15	0.002 - 0.02
stamina_regen	Stamina Regen	0.3 - 3.0	0.1 - 0.6
mana_regen	Mana Regen	0.3 - 3.0	0.1 - 0.6
crit_chance	Crit Chance	0.01 - 0.1	0.002 - 0.015
armor_bonus	Armor	0.01 - 0.1	0.002 - 0.012
loot_luck	Loot Luck	0.02 - 0.15	0.003 - 0.02
thorns	Thorns	0.3 - 3.0	0.1 - 0.8
life_steal	Life Steal	0.005 - 0.06	0.001 - 0.01

Percentage stats (damage_bonus, xp_bonus, crit_chance, armor_bonus, loot_luck, life_steal) are stored as decimals (e.g., 0.08 = 8%).

Combat pets roll from a restricted pool: damage_bonus, crit_chance, max_health, life_steal, armor_bonus.

The same stat type can appear up to 3 times on a single pet.

Stat Mechanics

• Reroll Scroll: Re-rolls both the stat type and value randomly. Uses Pet Reroll Scroll (pickup pets) or Battle Reroll Scroll (combat pets).
• Refine Scroll: Keeps the same stat type but re-rolls the value. Uses Pet Refine Scroll (pickup pets) or Battle Refine Scroll (combat pets).
• Effective value: baseValue + (perLevel * (currentLevel - 1)) (returns 0 if current level is below unlock level)

---

Auto-Generated Item Templates

When the plugin loads a custom pet type but cannot find its summon item (egg/rune/horn) in the server content, it automatically generates a JSON item template in plugins/Pets/item-templates/.

This is useful when adding new custom pet types:

1. Create a pet type JSON in the appropriate pet-types/{module}/ folder
2. Start the server — the plugin detects the missing item and generates a template
3. Copy the generated template from item-templates/ to your server’s Server/Item/Items/ folder
4. Restart the server

The generated template includes correct translation properties, quality tier, model/texture paths, interactions, and tags matching the pet’s module and rarity. A warning is logged for each generated template so they are easy to spot in the console.

If the item ID field (eggItemId, runeItemId, hornItemId) is omitted from the pet type JSON, the plugin auto-generates an ID based on the pet’s ID:

Module	Pattern	Example
collector	Pet_Egg_{Id}	Pet_Egg_Frog_Green
combat	Battle_Rune_{Id}	Battle_Rune_Wolf_Combat
mount	Mount_Horn_{Id}	Mount_Horn_Rex_Cave_Mount