Skip to main content

FAQ & Troubleshooting

General Questions​

How many pets can I have at once?​

You can have up to three active companions simultaneously -- one from each module:

  • 1 Collector Pet (auto-pickup)
  • 1 Combat Pet (battle companion)
  • 1 Mount (rideable)

The total number of owned pets (not active, just owned) is controlled by maxPetsPerPlayer in config.json (default: 5 per category).

How do I get a pet?​

Pets are obtained via their summon items:

  • Pet Eggs for collector pets
  • Battle Runes for combat pets
  • Mount Horns for mounts

These items can come from loot drops, shops, events, or admin commands (/kspetadmin give <player> <type>).

Can I trade pets?​

Yes. Pet Eggs, Battle Runes, and Mount Horns are regular inventory items with embedded metadata. Trading, dropping, or storing these items transfers the pet data with them. The new owner can right-click the item to summon the pet.

What happens if I drop my pet egg while my pet is summoned?​

The pet is automatically dismissed. The Drop Guard system detects when a summoning item leaves the player's inventory and despawns the associated companion immediately.

Do pets persist across server restarts?​

Pet data (level, stats, XP, filter settings) is saved to the database and persists permanently. However, the pet NPC entity does not persist -- you need to re-summon your pet after logging in. Pet NPCs are cleaned up on server start and stop.

Leveling & Stats​

How does XP work?​

Pets gain XP from their owner's actions:

SourceDefault XP
Mob Kill25
Block Break2
Crafting10
Item Pickup (by pet)2
Passive (per minute)1

XP requirements increase each level: baseXpPerLevel * (xpScaleFactor ^ (level - 1)).

What is the stat quality system?​

When a pet is created, its stats are rolled with a random quality value between the rarity's qualityMin and qualityMax:

RarityQuality RangeMeaning
Uncommon0.0 - 0.7Stats can be 0% to 70% of the maximum
Rare0.0 - 0.85Stats can be 0% to 85% of the maximum
Epic0.0 - 1.0Stats can reach the full maximum
Legendary0.0 - 1.2Stats can exceed the normal maximum by 20%

What is the difference between Reroll and Refine?​

  • Reroll: Changes both the stat type and value. Your Damage Bonus might become Crit Chance. Uses a Reroll Scroll.
  • Refine: Keeps the same stat type but re-rolls the value. Your Damage Bonus stays Damage Bonus but gets a new roll. Uses a Refine Scroll.

Both come in two variants: Pet_*_Scroll (for collector pets) and Battle_*_Scroll (for combat pets).

There are also "All" variants (Pet_Reroll_All_Scroll, Pet_Refine_All_Scroll, etc.) that affect all stats at once with a preview before confirming.

Can the same stat appear multiple times?​

Yes. The same stat type can appear up to 3 times on a single pet. Multiple instances of the same stat stack additively.

When do new stats unlock?​

Stats unlock at level thresholds based on rarity:

RarityStat Unlocks at Levels
Uncommon1, 10
Rare1, 8, 16
Epic1, 6, 12, 20
Legendary1, 5, 10, 15, 25

The first stat is always available at level 1. Additional stats are rolled automatically when the pet reaches the unlock level.

Combat Pets​

How do combat pets choose targets?​

Combat pets always fight. They engage based on two triggers:

  1. Owner attacks an enemy -- the pet targets that enemy
  2. Owner is attacked -- the pet retaliates against the attacker

When the target dies, the pet returns to following the owner.

Do combat pet kills count as my kills?​

Yes. Damage dealt by combat pets is attributed to the owner. The owner receives all loot and XP from kills made by the combat pet.

What is the leash distance?​

If a combat target moves farther than leashDistance (default: 20 blocks) from the owner, the pet disengages and returns. This prevents pets from chasing enemies across the map.

Mounts​

How do I dismount?​

Press the F key while mounted, or use /ksmount dismount.

Why does my mount disappear when I drop the horn?​

This is the Drop Guard safety feature. If the Mount Horn item leaves your inventory while mounted, the mount is automatically dismissed to prevent orphaned NPCs.

Do other players see my mount?​

Yes. The mount system uses Hytale's native setMountEntityId() for position sync, and an ECS system copies movement states for walk/run/idle animation sync. All players see your mount moving and animating correctly.

Are flying mounts available?​

The mount system supports a fly mount type with a separate NPC role (KS_Mount_Fly_Role), but this feature is currently work-in-progress. Only walk mounts are fully supported in the current version.

UI & HUD​

How do I change the HUD position?​

Open the Pet Menu (/kspet) and use the dropdown at the bottom. Available positions: Top Left, Top Right, Middle Left, Middle Right, Bottom Left, Bottom Right. Layout can be set to Vertical or Horizontal.

Settings are saved per-player.

Why does a pet not show in my menu?​

The Pet Menu only displays pets whose summon item (egg/rune/horn) is currently in your inventory. If you dropped, traded, or stored the item, the pet will not appear until the item is back in your inventory.

How do I change the language?​

Use /kslang to open the language selection page, or /kslang <code> to set it directly (e.g., /kslang de-DE). Use /kslang auto to reset to auto-detection based on your client language.

Administration​

How do I check a pet's data?​

Use /kspetadmin inspect hand to inspect the item in your hand, or /kspetadmin inspect <player> to see all pet items in a player's inventory along with their cached player data.

How do I clean up orphaned NPCs?​

Three commands are available, from least to most aggressive:

  1. /kspetadmin despawnall -- Despawns all active pets for all players (safest)
  2. /kspetadmin cleanup -- Force-removes all KS-role NPCs from the default world
  3. /kspetadmin cleanworld -- Scans all worlds and removes orphaned KS-role NPCs

How do I add custom pet types?​

See the Custom Pets Guide for full instructions. The short version:

  1. Copy a _template.json from the appropriate pet-types/ subfolder
  2. Rename and edit it with your custom values
  3. Restart the server twice (first restart generates the item, second loads it)

Can I disable a specific module?​

Yes. In config.json, set the module to false:

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

Disabled modules hide their commands and UI sections but preserve existing pet data.

Common Issues​

IssueCauseSolution
"No permission" when using /kspetks.pet.user.use is deniedGrant the permission (defaults to true)
Pet not followingPet NPC spawned but follow service not tickingCheck followTickIntervalMs config, try dismiss and re-summon
Items not being picked upPickup filter blocking, or wrong tick intervalCheck filter settings (/kspet filter), verify pickupTickIntervalMs
"Combat module is not enabled"Module disabled in configSet modules.combat: true in config.json
Pet teleporting constantlypetTeleportDistance too lowIncrease petTeleportDistance in config (default: 30)
Stats showing 0Pet level below stat's unlock levelLevel up the pet to unlock the stat
Scroll not workingNo scroll in inventory, or pet not summonedSummon the pet first, ensure the correct scroll type is in inventory
Mount not spawningMount horn not in inventory, or already mountedCheck inventory, dismount first with /ksmount dismount
Custom pet not loadingInvalid JSON or wrong folderValidate JSON syntax, ensure file is in pet-types/{module}/, not starting with _