Class PetManager
getMaxActivePets(MyPetPlayer), not by this container.
The concrete implementation in the plugin module handles spawning, despawning, repository I/O, and the active/inactive state transitions.
-
Field Summary
FieldsModifier and TypeFieldDescriptionActive pets keyed by their live Bukkit entity's UUID, for resolving a pet from an entity.protected final ListMultimap<MyPetPlayer, Pet> Active pets per owner, in activation order.Owner UUIDs known to have at least one pet — active or stored. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionactivatePet(StoredPet storedPet) Activates a stored pet — creates the livePetinstance, registers it in the active map, and spawns the entity if possible.intReturns the total number of currently active pets across all players.booleandeactivatePet(MyPetPlayer owner, boolean update) Deprecated, for removal: This API element is subject to removal in a future version.a player may have more than one active pet.abstract booleandeactivatePet(MyPetPlayer owner, Pet pet, boolean update) Deactivates one of the owner's active pets — despawns the entity and moves the pet back to a stored / inactive state.booleandeactivatePets(MyPetPlayer owner, boolean update) Deactivates every pet the owner currently has active, in activation order.Pet[]Returns a snapshot array of all currently active pets across all players.protected intgetMaxActivePets(MyPetPlayer owner) Maximum simultaneously-active pets forowner: the server ceiling (MyPet.Max-Active-Pet-Count, default 1) narrowed by the highestMyPet.petlimit.active.<n>node the player holds.getPet(MyPetPlayer owner) Deprecated.answers for the primary pet only, which was the whole roster until multi-pet shipped.Deprecated.getPetFromEntity(Entity entity) Resolves a Bukkit entity to its owningPetvia the entity-UUID index.getPets(MyPetPlayer owner) Returns all of the player's active pets, in activation order.Returns all active pets for the given Bukkit player, in activation order.getPrimaryPet(MyPetPlayer owner) Returns the player's primary active pet — the first one activated that is still active — ornullif none.getPrimaryPet(Player owner) Returns the primary active pet for the given Bukkit player, ornull.getSelectedPet(MyPetPlayer owner) The pet a command with no pet named acts on: the one the owner selected (MyPetPlayer.selectPet(java.util.UUID)) while it is still out, else the active pet brought out most recently, elsenullwhen nothing is out.getSelectedPet(Player owner) The pet a command with no pet named acts on; seegetSelectedPet(MyPetPlayer).abstract CompletableFuture<List<StoredPet>> getStoredPets(MyPetPlayer owner) Lists all pets — active or stored — owned by the given player.booleanhasActivePet(MyPetPlayer player) Returnstrueif the given player has an active pet.booleanhasActivePet(String name) Returnstrueif the player with this name has an active pet.booleanhasActivePet(Player player) Returnstrueif the given Bukkit player has an active pet.booleanhasRoomForActivePet(MyPetPlayer owner) Whetherownercan have one more pet out without anything being evicted.booleanownsAnyPet(UUID playerUuid) Returnstrueif the player owns at least one pet — active or stored.abstract CompletableFuture<Void> refreshOwnership(MyPetPlayer owner) Asynchronously re-derives the cachedownsAnyPet(UUID)flag for the given owner from the repository.voidregisterPetEntity(UUID entityUuid, Pet pet) Registers the live entity→pet binding.restorePet(StoredPet storedPet) Activates likeactivatePet(de.Keyle.MyPet.api.entity.StoredPet)but without making the pet the owner's selected pet.voidsetOwnsPet(UUID playerUuid, boolean owns) Updates the cached ownership flag for a player.abstract PersistedPetReturns an immutable point-in-time snapshot of an active pet, suitable for hand-off across an active/inactive boundary (deactivation, trade, admin clone).inttrimToActivePetCap(MyPetPlayer owner) Deactivates pets, oldest activation first, untilowneris back inside the cap.voidunregisterPetEntity(UUID entityUuid) Removes a live entity→pet binding.
-
Field Details
-
mActivePlayerPets
Active pets per owner, in activation order. -
mActivePetsByEntityUuid
Active pets keyed by their live Bukkit entity's UUID, for resolving a pet from an entity. -
petOwners
Owner UUIDs known to have at least one pet — active or stored. Populated asynchronously (repository I/O) at the few points ownership can change, so thatownsAnyPet(UUID)can answer synchronously for callers on the main thread (e.g. the PlaceholderAPI hook). May lag reality by the duration of an in-flight refresh.
-
-
Constructor Details
-
PetManager
public PetManager()Creates a manager. MyPet supplies the implementation; addons reach it through the API.
-
-
Method Details
-
getPrimaryPet
Returns the player's primary active pet — the first one activated that is still active — ornullif none.Prefer
getPets(MyPetPlayer)for anything that should affect every pet the player has out.- Parameters:
owner- the pet's owner- Returns:
- the owner's primary active pet, or
nullif none is active
-
getPrimaryPet
Returns the primary active pet for the given Bukkit player, ornull.- Parameters:
owner- the pet's owner- Returns:
- the owner's primary active pet, or
nullif none is active
-
getPet
Deprecated.answers for the primary pet only, which was the whole roster until multi-pet shipped. UsegetPets(MyPetPlayer)for anything that should affect every pet the player has out, orgetPrimaryPet(MyPetPlayer)when the primary is genuinely what you want.- Parameters:
owner- the pet's owner- Returns:
- the owner's primary active pet, or
nullif none is active
-
getPet
Deprecated.- Parameters:
owner- the pet's owner- Returns:
- the owner's primary active pet, or
nullif none is active
-
getPets
Returns all of the player's active pets, in activation order. Nevernull.This is an immutable snapshot, not a view: callers routinely iterate it while deactivating pets inside the loop, which would otherwise mutate the backing multimap mid-iteration.
- Parameters:
owner- the pet's owner- Returns:
- every active pet of that owner, in activation order
-
hasRoomForActivePet
Whetherownercan have one more pet out without anything being evicted.Call sites that used to ask
MyPetPlayer.hasPet()before deciding whether to activate meant this: "has one" and "has no room" were the same question only while the cap was 1.A
falsereturn does NOT meanactivatePet(de.Keyle.MyPet.api.entity.StoredPet)will fail -- it always makes room by retiring the oldest active pet. What afalseshould make a caller do is set by theMyPet.Store-Oldest-When-Fullconfig option (defaulttrue):- An acquisition -- taming, buying, trading for, capturing a new pet --
checks this and, when the option is
false, refuses rather than costing the player a pet they already had. With the optiontrueit activates anyway and lets the eviction happen. - An explicit swap -- a roster click,
/petswitch, the storage NPC -- does not consult the option at all: the player asked for the swap.
- Parameters:
owner- the pet's owner- Returns:
trueif the owner is below their active-pet cap
- An acquisition -- taming, buying, trading for, capturing a new pet --
checks this and, when the option is
-
trimToActivePetCap
Deactivates pets, oldest activation first, untilowneris back inside the cap. Returns how many were retired.activatePet(de.Keyle.MyPet.api.entity.StoredPet)enforces the cap on the way in, which covers every path that ADDS a pet -- but not a cap that shrinks under a roster that was legal when it was built. LoweringMax-Active-Pet-Count, or revoking aMyPet.petlimit.active.<n>node, leaves pets out that no longer fit.- Parameters:
owner- the pet's owner- Returns:
- how many pets were deactivated
-
getPets
Returns all active pets for the given Bukkit player, in activation order.- Parameters:
owner- the pet's owner- Returns:
- every active pet of that owner, in activation order
-
getMaxActivePets
Maximum simultaneously-active pets forowner: the server ceiling (MyPet.Max-Active-Pet-Count, default 1) narrowed by the highestMyPet.petlimit.active.<n>node the player holds.Both have to allow it — raising the ceiling alone grants nobody a second pet, and a node above the ceiling is clamped to it. See MyPetORG/MyPet#1435.
- Parameters:
owner- the pet's owner- Returns:
- how many pets that owner may have out at once
-
getAllActivePets
Returns a snapshot array of all currently active pets across all players.- Returns:
- every active pet on the server
-
getPetFromEntity
Resolves a Bukkit entity to its owningPetvia the entity-UUID index. Returnsnullif the entity is not a live pet entity.- Parameters:
entity- the Bukkit entity to resolve- Returns:
- the pet that entity belongs to, or
nullif it is not a pet
-
registerPetEntity
Registers the live entity→pet binding. Called fromPet#setBukkitEntity.- Parameters:
entityUuid- the live entity's UUIDpet- the pet it belongs to
-
unregisterPetEntity
Removes a live entity→pet binding. Called fromPet#setBukkitEntity.- Parameters:
entityUuid- the entity UUID to forget
-
hasActivePet
Returnstrueif the given player has an active pet.- Parameters:
player- the player to test- Returns:
trueif that player has a pet out
-
hasActivePet
Returnstrueif the given Bukkit player has an active pet.- Parameters:
player- the player to test- Returns:
trueif that player has a pet out
-
hasActivePet
Returnstrueif the player with this name has an active pet.- Parameters:
name- the player name to test- Returns:
trueif that player has a pet out
-
ownsAnyPet
Returnstrueif the player owns at least one pet — active or stored. Reads the cachedpetOwnersset, so it is safe to call on the main thread. The value is refreshed asynchronously on login and whenever a pet is created or removed; see the concrete implementation'srefreshOwnership.- Parameters:
playerUuid- the player to test- Returns:
trueif that player owns at least one pet, active or stored
-
setOwnsPet
Updates the cached ownership flag for a player. Called by the async refresh.- Parameters:
playerUuid- the player to recordowns-trueif they own at least one pet
-
snapshot
Returns an immutable point-in-time snapshot of an active pet, suitable for hand-off across an active/inactive boundary (deactivation, trade, admin clone). Callers needing to tweak fields after the fact should use the record'swithXmethods ortoBuilder.- Parameters:
activePet- the live pet to snapshot- Returns:
- an immutable record carrying the pet's persistent fields
-
activatePet
Activates a stored pet — creates the livePetinstance, registers it in the active map, and spawns the entity if possible.- Parameters:
storedPet- the pet at rest to bring live- Returns:
- the activated pet, or empty if activation failed (e.g., player already has an active pet, or spawn conditions not met)
-
restorePet
Activates likeactivatePet(de.Keyle.MyPet.api.entity.StoredPet)but without making the pet the owner's selected pet. For the restore paths -- join, world change, plugin enable -- which bring every bound pet back in database order and must not overwrite a selection the player made.- Parameters:
storedPet- the pet at rest to bring live- Returns:
- the activated pet, or empty if activation failed
-
getSelectedPet
The pet a command with no pet named acts on: the one the owner selected (MyPetPlayer.selectPet(java.util.UUID)) while it is still out, else the active pet brought out most recently, elsenullwhen nothing is out.- Parameters:
owner- the pet's owner;nullyieldsnull- Returns:
- the pet commands should act on, or
nullwhen none is out
-
getSelectedPet
The pet a command with no pet named acts on; seegetSelectedPet(MyPetPlayer).- Parameters:
owner- the pet's owner- Returns:
- the pet commands should act on, or
nullwhen none is out
-
deactivatePet
Deactivates one of the owner's active pets — despawns the entity and moves the pet back to a stored / inactive state.- Parameters:
owner- the pet's ownerpet- the pet to deactivate; must currently be active forownerupdate- iftrue, persists the pet's current state to the repository before deactivation- Returns:
trueif the pet was deactivated
-
deactivatePets
Deactivates every pet the owner currently has active, in activation order.- Parameters:
owner- the pet's ownerupdate- iftrue, persists each pet's state before deactivating it- Returns:
trueif at least one pet was deactivated
-
deactivatePet
@Deprecated(since="4.1.0", forRemoval=true) public boolean deactivatePet(MyPetPlayer owner, boolean update) Deprecated, for removal: This API element is subject to removal in a future version.a player may have more than one active pet. UsedeactivatePets(MyPetPlayer, boolean)to deactivate all of them, ordeactivatePet(MyPetPlayer, Pet, boolean)to name the one you mean. This overload deactivates all of them.Deactivates the owner's pet.- Parameters:
owner- the pet's ownerupdate- whether to persist the pet as it is put away- Returns:
trueif a pet was deactivated
-
getStoredPets
Lists all pets — active or stored — owned by the given player.The returned
CompletableFuturecompletes on a background thread. Callers that intend to touch Bukkit API in a continuation must hop to the appropriate scheduler (e.g.Bukkit.getServer().getGlobalRegionScheduler().run(plugin, t -> ...)orplayer.getScheduler().run(plugin, t -> ..., null)) inside the continuation; touching Bukkit API directly from the continuation is undefined behavior on Paper and an outright crash on Folia.- Parameters:
owner- the pet's owner- Returns:
- the owner's pets that are not currently active
-
refreshOwnership
Asynchronously re-derives the cachedownsAnyPet(UUID)flag for the given owner from the repository. Safe to ignore the returned future — the cache is updated as a side effect when it completes.- Parameters:
owner- the pet's owner- Returns:
- a future completing once the ownership cache has been refreshed
-
countActivePets
public int countActivePets()Returns the total number of currently active pets across all players.- Returns:
- how many pets are active across the server
-