API & Events

Version: 1.12.1

KyuubiSoft Pets has no separate API jar. Other plugins can listen to four events, read the data on pet items and find the pet HUD by its key. Everything else (PetsPlugin.getInstance() and the service classes behind it) is public Java code, but internal: it can change in any version.

Plugin identity

Plugin ID	kyuubisoft:pets (manifest Group kyuubisoft, Name pets)
Main class	com.kyuubisoft.pets.PetsPlugin
Jar	KyuubiSoftPets-1.12.1.jar (contains its own SQLite driver and asset pack)
Data folder	mods/kyuubisoft_pets/
Server	Hytale 0.7.x, Java 25
Optional dependencies (manifest)	hytale:mounts, kyuubisoft:item-control, kyuubisoft:core, KyuubiDDragon:KyuubiSoftAPI

Events

All events are in the package com.kyuubisoft.pets.event. Each one implements com.hypixel.hytale.event.IEvent<Void> and is dispatched on the server event bus (HytaleServer.get().getEventBus()).

• They are dispatched synchronously on the thread that caused them, usually the owner’s world thread.
• They are notifications only: nothing can be cancelled or changed.
• They are only fired while the owner is online.

PetSpawnedEvent

Fired when a collector pet or combat pet entity has been spawned: summoned from the compendium or the classic menu, by using its egg or battle rune, with /kspet summon, or when the plugin respawns a pet. Mounts do not fire it.

Getter	Type	Value
getPlayerRef()	PlayerRef	The owner
getPetTypeId()	String	The pet type id, for example wolf_combat or duck
getPetInstanceId()	String	The pet’s own id (a UUID); the same as PET_Id on its item and instance_id in the database

PetDespawnedEvent

Same getters as PetSpawnedEvent.

Fired whenever a summoned collector pet or combat pet leaves while the server runs: dismissed (with its item, in the compendium or menu, or by command), swapped for another pet, the owner’s death, logout or world change, dropping the pet’s item, an admin removing the pet, and /kspetadmin cleanup. On logout the pets are sent home before the player leaves the online list, so the event still carries the player. Together with PetSpawnedEvent it tells you whether a pet is out.

It is not fired for the pets that are cleared when the server shuts down, and mounts never fire it.

Before 1.11.1 it only fired on one rare respawn path.

PetXpGainedEvent

Fired every time a pet below its maximum level receives XP:

• the summoned collector pet, from block breaking, crafting, mob kills and item pickups,
• the summoned combat pet, from its kills,
• any pet, from admin XP (/kspetadmin addxp and the admin window).

Getter	Type	Value
getPlayerRef()	PlayerRef	The owner
getPetTypeId()	String	The pet type id
getAmount()	double	XP added by this grant, after the pet’s xp_bonus stat
getTotalXp()	double	The pet’s XP in its current level right after adding, before level-ups are applied (it can be higher than the level requirement). It is not the lifetime XP

The event has no instance id. It fires once per broken block and per picked-up item, so keep listeners cheap.

PetLevelUpEvent

Fired when XP lifts a pet to a higher level, once per XP grant, even when several levels are gained at once. New stats for crossed unlock levels are already rolled when it fires. /kspetadmin setlevel and maxout set the level directly and do not fire it.

Getter	Type	Value
getPlayerRef()	PlayerRef	The owner
getPetTypeId()	String	The pet type id
getPetInstanceId()	String	The pet’s id
getOldLevel()	int	Level before
getNewLevel()	int	Level after

Listening to the events

Register through your plugin’s event registry, for example in setup():

import com.kyuubisoft.pets.event.PetLevelUpEvent;

@Override
protected void setup() {
    getEventRegistry().register(PetLevelUpEvent.class, event -> {
        var owner = event.getPlayerRef();
        int newLevel = event.getNewLevel();
        // your logic, e.g. a reward every 10 levels
    });
}

• Compile against KyuubiSoftPets-1.12.1.jar as a compile-only dependency.
• Declare Pets in your manifest.json so it loads first: "Dependencies": {"kyuubisoft:pets": "*"}, or "OptionalDependencies" if your plugin also runs without it.
• With an optional dependency, put the code that touches Pets classes in its own class and only load that class when Pets is installed.

Pet items

Every pet lives in an item: an egg (collector pets, Pet_Egg_*), a battle rune (combat pets, Battle_Rune_*) or a mount horn (Mount_Horn_*). The item ids of custom pets come from their pet type file. The pet data itself is in the database; the item only carries these metadata keys:

Key	Content
PET_Id	The pet’s id (UUID)
PET_TypeId	The pet type id
PET_Gen	Item generation; only on items handed out by /kspetadmin restore (missing = 0)

Since 1.10.0 a restore raises the pet’s generation. An item whose PET_Gen is lower than the stored generation is stale: it no longer proves ownership and crumbles when used. Items from before the SQLite storage carried the full pet data under keys like PET_InstanceId; the plugin still reads them.

A pet counts as owned while its (not stale) item is in the player’s inventory. The item’s tooltip shows name, level and stats.

Storage

SQLite database

Pet data is stored in mods/kyuubisoft_pets/pets.db (SQLite, WAL mode).

Table pets, one row per pet:

Column	Content
instance_id	Primary key, the pet’s id (PET_Id)
type_id	Pet type id
nickname	Nickname
level	Level
current_xp	XP in the current level
total_xp	Lifetime XP
items_picked	Items collected
mobs_killed	Kills
combat_mode	Stored combat mode (default defensive)
created_at, last_summoned	Times in epoch milliseconds
stats_json	Rolled stats as a JSON list of type, baseValue, perLevel, unlockLevel
filter_mode, filter_json	Pickup filter mode (blacklist / whitelist) and its rules
downed_until	Since 1.8.0: end of a combat pet’s recovery in epoch milliseconds, 0 = not defeated
health_fraction	Since 1.8.0: remaining HP of a combat pet, 0 to 1

The table has no owner column: a pet belongs to whoever has its item.

Table pet_item_gen (since 1.10.0): instance_id (primary key) and gen, the item generation of pets that were restored. Pets without a row have generation 0.

A stat’s value at level L is baseValue + perLevel × (L − 1), and 0 below its unlockLevel. Stats whose type contains bonus, chance, luck or life_steal are stored as fractions (0.05 = 5 %).

When rows are written: XP and level changes are kept in memory and written on a level-up, on deliberate actions (summon, rename, filter change, reroll), every petDbFlushIntervalSeconds (default 30) for the pets that are out, and when the player leaves.

Working with the file:

• Run /kspetadmin dbflush before you open pets.db with an external SQLite tool while the server runs; it merges the WAL file into the database.
• After changing a row of an online player, run /kspetadmin dbreload <player>. It sends the player’s pets home and reloads them from the database.

Other files

Path	Content
mods/kyuubisoft_pets/config.json, stat-pool.json, loot_luck_blacklist.json	Settings, see Configuration
mods/kyuubisoft_pets/pet-types/<collector,combat,mount>/*.json	Pet types, see Custom Pets
mods/kyuubisoft_pets/localization/*.json	Languages, see Localization
mods/kyuubisoft_pets/data/players/<uuid>.json	Per player: the list of their pets, the active slots, bestiary, HUD position and layout (once picked), counters, and heldDeathItems (pet items the death protection is holding back while the player is dead). The previous version is kept as <uuid>.json.bak
mods/kyuubisoft_pets/pet_state.json	Entity ids of spawned pets, used to remove leftover pet NPCs after a crash
mods/kyuubisoft_pets/npc-roles/	NPC role files of the pets, written again on every start
mods/kslang/	Language choice shared by all KyuubiSoft mods (prefs.json, mods.json)
mods/KyuubiSoftPets_CustomItems/	Item files generated for custom pet types; Hytale loads them as an asset pack after a restart

Optional integrations

None of these is required; Pets runs on its own.

Integration	What Pets does with it
KyuubiSoft Core (kyuubisoft:core)	Optional manifest dependency since 1.11.2, so Core loads first. Detected at startup by the class com.kyuubisoft.core.util.SmartConfigManager. If present, config.json is loaded through it, which merges new default keys into an existing file, and the admin window is added as a tile to the /ksadmin hub (Core 2.8.0 or newer). Without Core, Pets only adds missing combatBalance and ui blocks and the keys maxPetsEverywhere and combatBalance.levelUpCombatStatsOnly to an existing config.json.
KyuubiSoftAPI (KyuubiDDragon:KyuubiSoftAPI)	Optional manifest dependency since 1.12.0. With version 2.1 or newer, Pets registers a status page on the KyuubiSoft Panel’s “Mod Status” page and sends the events pet_level_up and config_reloaded to the panel’s event stream. See Admin Panel.
DynamicTooltipsLib	Detected at startup by the class org.herolias.tooltips.api.DynamicTooltipsApiProvider. Pets then registers a tooltip provider with the id kyuubisoft:pets that builds the tooltip of pet items from the database. Without it, pet items keep their own name, level and stats text.
Item Control (kyuubisoft:item-control)	Optional manifest dependency, so it sets up first. Pets’ death protection takes pet items out of the inventory before Item Control’s death rules and drop prevention run, and puts them back afterwards.
Graveyard (kyuubisoft:graveyard)	Not a manifest dependency. Pets’ death protection runs before Graveyard’s death system as well, so pet eggs, Battle Runes and Mount Horns stay with the player and never end up in a gravestone. The ordering is only declared when the other system is registered, also when it registers after Pets.
Hytale mounts (hytale:mounts)	Optional manifest dependency. The mount module uses its mount component.
MultipleHUD	Only used when the server has no keyed HUD API. On Hytale 0.7 the server’s own API is used.
KS UI kit	Not a dependency: the textures of the Goldfiligran windows are inside the jar and are registered once per server under UI/Custom/KSPremium/. Other KyuubiSoft mods that use the kit share them.

Pet HUD key

The pet HUD is a custom HUD with the key ks.pets.tracker and z-order 50. Other plugins can look it up with the player’s HudManager.getCustomHud("ks.pets.tracker"). What it shows: UI Pages.