Developer API

BlueprintService/FoodBlueprintService

PetService

gainExperience fires PetGainExperienceEvent first and reads back event.experienceGained(), so a listener can shrink or zero out the actual amount applied. It then loops level-ups, firing PetLevelUpEvent once per level and reading event.newLevel() back — a listener can change how far the pet actually levels on this call.

EntityService

spawn despawns any existing entity for the player first, then fires PetSpawnEvent — a null return means the event was cancelled, no collision-free spot was found within 5 blocks up/down of the target location, or the pet's AstralMobs mob-blueprint does not exist. The world entity itself is spawned by AstralMobs (MobsAPI.spawnOwnedMob), so PetEntity#entityId, uniqueId and bukkitLocation only carry real values after that call returns. ride is a no-op unless the pet's blueprint has a rideable effect at level ≥ 1 and the entity has no passenger already; if the level requirement isn't met it sends PET_CANNOT_BE_RODE with the level still required.

SkinService

apply enforces both rules itself — a pet that already wears a skin, and a skin the pet's blueprint does not list, are refused with a message and the item is left alone — then fires PetSkinApplyEvent. It hops to the main thread when called from a packet thread, returning false and doing the work a tick later; buildItemStack throws for a skin that declares no item. See Pet Skins.

MenuService

openPetMenu passes Map.of("pet", pet) into MenuContainer#computeAndOpen, which lands in the menu's parameters map (Menu#findParameter) — inside that menu, %parameters_pet% resolves to the raw Pet object itself. That's the concrete source of the Pet that rename-pet resolves its first argument against.

equip-pet

Looks up PetPlayerData for the executor, then bails with ACTIVE_PETS_LIMIT_REACHED if activePets().size() is already at the cap from PetsConfiguration.MaxPets#maxPets(player) (see permission overrides). If the pet is already active this is a silent no-op. Refuses with CANNOT_EQUIP_IDENTICAL_PET if another active pet shares the same blueprint id. On success, marks the pet active in PetPlayerData and fires PetEquipEvent — this action does not spawn the entity itself, that's spawn-pet's job.

unequip-pet

Silent no-op if the pet isn't currently active. Otherwise marks it inactive and fires PetUnequipEvent, which EntityListener listens to and removes the pet's spawned entity as a side effect.

spawn-pet

Looks up the pet in PetPlayerData; sends PET_NOT_FOUND if it isn't owned. Checks the WorldGuard pets flag at the player's current location first (PET_SPAWN_DENIED_HERE if denied), then delegates to EntityService#spawn(player, pet); a null result (event cancelled, or no free spot found) sends PET_SPAWN_CANCELLED. On success, sets the pet as the player's selectedPetId.

despawn-pet

Sends PET_NOT_FOUND if the pet isn't owned. Otherwise removes its spawned entity (if any) and clears selectedPetId regardless of whether an entity was found.

pickup-pet

Builds an ItemStack via PetService#buildItemStack(Pet) and mails it to the player through MailboxService#giveOrAdd. Only on confirmed delivery does it call PetPlayerData#removePet(pet) and send PET_REMOVED — a mailbox failure leaves the pet in the player's data untouched and sends UNEXPECTED_ERROR.

open-pet-container

Throws (uncaught RuntimeException, logged as an action failure) if the pet id doesn't resolve. Silently does nothing if pet.inventory().size() == 0 — i.e. the pet has no storage effect levelled up yet. Otherwise opens a PetInventoryMenu for it.

ride-pet

Throws if the pet id doesn't resolve to an owned pet or to a currently-spawned PetEntity — the pet must already be spawned (via spawn-pet or auto-respawn) before it can be ridden. Delegates to EntityService#ride, which applies the rideable-effect-level gate described above.

Preset actions

create-preset takes a PlaceholderWrapper<String> (the name); the other two take a PlaceholderWrapper<PetPreset> and must resolve to a PetPreset object, not a UUID string. All three throw if the executor has no loaded PetPlayerData. apply-preset fires PetUnequipEvent for every pet it deactivates and PetEquipEvent for every pet it activates, but does not go through equip-pet, so neither the active-pet cap nor the identical-blueprint rule is re-checked. See Pet Presets.

rename-pet

Takes two arguments and, unlike every other action here, the first is a PlaceholderWrapper<Pet> — it must resolve directly to a Pet object, not a UUID string. The second is a PlaceholderWrapper<String> for the new name. Validation: an empty name sends PET_RENAME_CANCELLED; a name longer than PetsConfiguration#maxPetNameLength (max-pet-name-length in config.yml, default 16) sends PET_NAME_TOO_LONG with a maxLength placeholder. On success the pet's Component name is recoloured to its blueprint's rarity color, PET_RENAMED is sent with oldName/newName placeholders, and if the pet is currently spawned its nametag is refreshed.

High-level pet events

Entity-level events

Nametag visibility

The pet's mob is a real, AstralMobs-spawned entity, so the server's own entity tracker handles it. What still needs managing is the nametag — a packet text display mounted on the mob — and that is what PetVisibilityTask does. It runs synchronously every 10 ticks (the pass reads live entity state, position and passengers, and sends packets derived from it, which is unsafe off the main thread) over EntityService#entities() and, per pet:

• re-asserts the nametag mount, because a single SetPassengers can be dropped by a client that is not yet tracking the mob, or evicted by a vanilla passenger broadcast. While a player is riding, the tag is hidden and the real passenger list is re-asserted instead, so a client that missed the mount does not walk around believing it dismounted;

• removes viewers who went offline, changed world, or moved 64+ blocks away (destroy packet), and adds every online player inside that radius in the same world (spawn packet).

PacketEntity#addViewer/#removeViewer send those packets to one client each — there is no global broadcast.

Max active pets overrides

The equip cap enforced by equip-pet isn't a single fixed permission node — it's a config-driven map, max-active-pets in config.yml (see Configuration for the resolution rule in full):

PetsConfiguration.MaxPets#maxPets(Player) checks every key in permissions the player has, taking the highest matching value, and falls back to default if none match. The permission strings are whatever you configure — group.roturier above is this network's example, not a hardcoded node — so granting a higher pet cap to a rank is entirely a config + permission-plugin exercise, not a code change.