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
`xpSources.crafting`	int	`10`	XP per item crafted
`xpSources.itemPickup`	int	`2`	XP per item picked up by pet
`xpSources.passivePerMinute`	int	`1`	Passive XP per minute while pet is active

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:

Create a pet type JSON in the appropriate pet-types/{module}/ folder
Start the server — the plugin detects the missing item and generates a template
Copy the generated template from item-templates/ to your server's Server/Item/Items/ folder
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`

Full Config Structure​

Field Reference​

General​

Tick Intervals​

HUD Settings​

Pickup Filter Defaults​

XP Sources​

Pet Type Definitions​

Collector Pet (Pickup Pet)​

Combat Pet​

Mount​

Rarity Levels​

Stat Pool​

Stat Mechanics​

Auto-Generated Item Templates​