API & Events

The Pet System fires Hytale events that other mods can listen to for integration. These events use Hytale's native IEvent system.

---

Events

All events are in the com.kyuubisoft.pets.event package.

PetSpawnedEvent

Fired when a pet NPC is successfully spawned in the world.

public class PetSpawnedEvent implements IEvent<Void> {
    public PlayerRef getPlayerRef();   // Owner
    public String getPetTypeId();      // Pet type ID (e.g., "wolf")
    public String getPetInstanceId();  // Unique instance UUID
}

PetDespawnedEvent

Fired when a pet NPC is despawned (dismissed, owner disconnect, egg dropped, etc.).

public class PetDespawnedEvent implements IEvent<Void> {
    public PlayerRef getPlayerRef();   // Owner
    public String getPetTypeId();      // Pet type ID
    public String getPetInstanceId();  // Unique instance UUID
}

PetLevelUpEvent

Fired when a pet levels up. Includes both the old and new level.

public class PetLevelUpEvent implements IEvent<Void> {
    public PlayerRef getPlayerRef();   // Owner
    public String getPetTypeId();      // Pet type ID
    public String getPetInstanceId();  // Unique instance UUID
    public int getOldLevel();          // Level before
    public int getNewLevel();          // Level after
}

PetXpGainedEvent

Fired when a pet gains XP from any source.

public class PetXpGainedEvent implements IEvent<Void> {
    public PlayerRef getPlayerRef();   // Owner
    public String getPetTypeId();      // Pet type ID
    public double getAmount();         // XP gained this tick
    public double getTotalXp();        // Cumulative total XP earned
}

---

Listening to Events

To listen to pet events from another mod, use Hytale's event system:

EventBus.get().register(PetLevelUpEvent.class, event -> {
    PlayerRef owner = event.getPlayerRef();
    int newLevel = event.getNewLevel();
    // Your integration logic here
});

---

Key Data Structures

PetInstance

Represents a single pet owned by a player. Key fields:

Field	Type	Description
instanceId	String	Unique UUID for this pet instance
petTypeId	String	ID of the pet type definition
nickname	String	Custom display name
level	int	Current level (1-based)
currentXp	double	XP toward next level
totalXpEarned	long	Lifetime XP earned
itemsPickedUp	long	Total items collected (collector pets)
mobsKilled	long	Total mobs killed (combat pets)
combatMode	String	"defensive", "aggressive", or "passive"
stats	List<PetStat>	Rolled random stats
filter	PickupFilterConfig	Pickup filter rules (collector pets)
createdAt	long	Timestamp of creation
lastSummoned	long	Timestamp of last summon

PetStat

A single random stat on a pet:

Field	Type	Description
type	String	Stat type ID (e.g., "damage_bonus")
baseValue	double	Value at level 1
perLevel	double	Growth per level
unlockLevel	int	Level at which this stat becomes active

Effective value formula:

value = baseValue + (perLevel * (currentLevel - 1))

A stat returns 0 if the pet's level is below the stat's unlockLevel.

PetTypeDefinition

Defines a pet type loaded from JSON. Key fields:

Field	Type	Description
id	String	Unique type identifier
displayName	String	Display name
entityTypeId	String	Hytale NPC entity type
module	String	"collector", "combat", or "mount"
rarity	String	"common", "uncommon", "rare", "epic", or "legendary"
maxLevel	int	Maximum pet level
combatStats	CombatStats	Combat-specific stats (combat module only)
mountConfig	MountConfig	Mount-specific config (mount module only)

---

Optional Dependencies

The Pet System has no required dependencies but supports optional integration:

Dependency	Purpose
KyuubiSoft Core	SmartConfigManager for merge-based config loading
DynamicTooltipsLib	Enhanced item tooltips showing pet stats, level, and rarity
hytale:mounts	Native mount system integration (declared as optional in manifest)

---

Database

Pet data is stored in SQLite via the PetDatabase class. Each pet instance is stored with its full state (stats, level, XP, filter config). Player runtime data is cached in-memory with dirty-flag tracking and periodic auto-save (configurable via autoSaveIntervalSeconds).

The database file is located at plugins/Pets/data/pets.db.