Custom Pets Guide

Add your own pets, combat companions, and mounts without touching any code. All you need is a JSON file.

---

How It Works

The Pets mod auto-discovers all .json files in the pet-types/ subfolders. When it finds a pet type that has no matching item file, it auto-generates the item JSON into the server's content directory.

Two Restarts Required

Due to how Hytale loads items (before plugins start), adding a new pet requires two server restarts:

1. First restart — The mod loads your pet type and generates the missing item file
2. Second restart — Hytale loads the generated item, and the pet is fully functional

This is a Hytale engine limitation, not a mod limitation.

---

Quick Start

1. Find the Templates

The mod includes ready-to-use templates in each pet-types subfolder:

plugins/kyuubisoft.pets/pet-types/
├── collector/
│   └── _template.json    ← Pickup Pet template
├── combat/
│   └── _template.json    ← Combat Pet template
└── mount/
    └── _template.json    ← Mount template

2. Copy and Rename

Copy the template for the type you want and give it a unique name:

_template.json  →  phoenix.json

warning

Do NOT rename _template.json directly — copy it. Files starting with _ are ignored by the mod.

3. Edit the JSON

Open your new file and fill in the values. Here's what each field means:

4. Restart Twice

1. Start the server → check the log for "Generated missing item 'Pet_Egg_Phoenix'"
2. Restart again → the item is loaded and the pet is ready
3. Test with /kspetadmin give <player> phoenix

---

Pickup Pet Fields

Field	Type	Description
id	string	Unique identifier (lowercase, underscores). Must match filename
displayName	string	Display name shown to players
entityTypeId	string	Hytale entity model (e.g. Fox, Bunny, Owl_Snow)
modelScale	float	Size multiplier (0.5 = half size, 1.0 = normal)
followDistance	float	How far the pet follows behind the player
followSpeed	float	Movement speed when following
pickupRadius	float	Item pickup range in blocks
maxLevel	int	Maximum level (default: 50)
baseXpPerLevel	int	XP needed for level 2
xpScaleFactor	float	XP curve multiplier per level (1.15 = 15% more per level)
eggItemId	string	Item ID for the egg (auto-generated if omitted: Pet_Egg_<Id>)
rarity	string	common, uncommon, rare, epic, or legendary
description	string	Short description

Example: Pickup Pet

{
  "id": "phoenix",
  "displayName": "Baby Phoenix",
  "entityTypeId": "Skrill_Chick",
  "modelScale": 0.6,
  "followDistance": 3.0,
  "followSpeed": 5.5,
  "pickupRadius": 2.0,
  "maxLevel": 50,
  "baseXpPerLevel": 120,
  "xpScaleFactor": 1.18,
  "rarity": "epic",
  "description": "A fiery phoenix companion that collects items."
}

---

Combat Pet Fields

All pickup pet fields plus:

Field	Type	Description
module	string	Must be "combat"
runeItemId	string	Item ID for the rune (auto: Battle_Rune_<Id>)
combatStats.baseDamage	float	Base damage at level 1
combatStats.damagePerLevel	float	Additional damage per level
combatStats.attackSpeed	float	Attacks per second
combatStats.attackRange	float	Attack range in blocks
combatStats.aggroRange	float	Detection range for enemies
combatStats.leashDistance	float	Max distance before returning to owner
combatStats.attackAnimation	string	Animation name (e.g. Bite, Ram, SwingLeft)
combatStats.attackAnimationsId	string	Animation set (e.g. Wolf_Black_Default)

Example: Combat Pet

{
  "id": "fire_golem",
  "displayName": "Fire Golem",
  "entityTypeId": "Bramblekin",
  "modelScale": 1.2,
  "followDistance": 3.0,
  "followSpeed": 5.0,
  "maxLevel": 50,
  "baseXpPerLevel": 140,
  "xpScaleFactor": 1.15,
  "rarity": "epic",
  "description": "A burning golem that fights by your side.",
  "module": "combat",
  "combatStats": {
    "baseDamage": 12.0,
    "damagePerLevel": 0.7,
    "attackSpeed": 1.0,
    "attackRange": 3.0,
    "aggroRange": 15.0,
    "leashDistance": 20.0,
    "attackAnimation": "Bite",
    "attackAnimationsId": "Bramblekin_Default"
  }
}

---

Mount Fields

All base fields plus:

Field	Type	Description
module	string	Must be "mount"
hornItemId	string	Item ID for the horn (auto: Mount_Horn_<Id>)
mountConfig.mountType	string	"walk", "fly" (WIP), or "swim" (WIP)
mountConfig.mountYOffset	float	Player seat height on the mount
mountConfig.speed	float	Movement speed multiplier
mountConfig.baseHealth	float	Mount health points

Example: Mount

{
  "id": "war_elephant",
  "displayName": "War Elephant",
  "entityTypeId": "Bison",
  "modelScale": 1.5,
  "maxLevel": 30,
  "baseXpPerLevel": 180,
  "xpScaleFactor": 1.2,
  "rarity": "legendary",
  "description": "A massive war elephant. Slow but unstoppable.",
  "module": "mount",
  "mountConfig": {
    "mountType": "walk",
    "mountYOffset": 2.8,
    "speed": 0.9,
    "baseHealth": 200
  }
}

---

Available Entity Types

Any Hytale entity can be used as a pet model. Common choices:

Small animals (good for pickup pets): Fox, Bunny, Cat, Gecko, Meerkat, Crab, Duck, Penguin, Squirrel, Bat, Parrot, Bluebird, Frog_Green, Owl_Snow, Mouse, Rat

Medium creatures (good for combat pets): Wolf_Black, Boar, Crocodile, Spider, Scorpion, Hyena, Bramblekin, Crawler_Void

Large creatures (good for mounts): Horse, Camel, Bison, Moose_Bull, Bear_Polar, Tiger_Sabertooth, Dragon_Frost, Rex_Cave

---

Rarity Effects

Rarity	Max Stats	Unlock Levels	Quality Range
Uncommon	2	1, 10	0% - 70%
Rare	3	1, 8, 16	0% - 85%
Epic	4	1, 6, 12, 20	0% - 100%
Legendary	5	1, 5, 10, 15, 25	0% - 120%

Higher rarity = more random stat slots, better stat rolls. Legendary pets can exceed the normal maximum stat values (up to 120% of the base maximum).

info

The common rarity is accepted but has no stat rules defined in the default stat-pool.json. Common pets will have 1 stat with a narrow quality range. For best results, use uncommon or higher.

---

Troubleshooting

Pet type not loading

• Ensure the file is in the correct subfolder (collector/, combat/, or mount/)
• Filename must NOT start with _
• Validate JSON syntax (no trailing commas, proper brackets)
• Check server logs for loading errors

Item not generating

• Check the log for "Generated missing item" messages
• If you see "Content directory not found", copy the file from item-templates/ manually
• The eggItemId/runeItemId/hornItemId must follow the naming convention (e.g. Pet_Egg_<CamelCase>)

Pet looks wrong

• Verify entityTypeId matches a real Hytale entity name (case-sensitive)
• Adjust modelScale — most small pets use 0.5-0.8, mounts use 1.0+

Admin commands for testing

/kspetadmin give <player> <pet_id>    — Give the pet
/kspetadmin list                       — List all registered types
/kspetadmin reload                     — Reload configs (no restart)