Class PetManager

java.lang.Object
de.Keyle.MyPet.api.repository.PetManager

public abstract class PetManager extends Object
Manages the lifecycle of active (in-world) pets and provides access to stored (inactive) pet records. Maps each player to their active pets, in activation order; how many a player may have at once is governed by 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 Details

    • mActivePlayerPets

      protected final ListMultimap<MyPetPlayer,Pet> mActivePlayerPets
      Active pets per owner, in activation order.
    • mActivePetsByEntityUuid

      protected final Map<UUID,Pet> mActivePetsByEntityUuid
      Active pets keyed by their live Bukkit entity's UUID, for resolving a pet from an entity.
    • petOwners

      protected final Set<UUID> 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 that ownsAnyPet(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

      public Pet getPrimaryPet(MyPetPlayer owner)
      Returns the player's primary active pet — the first one activated that is still active — or null if 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 null if none is active
    • getPrimaryPet

      public Pet getPrimaryPet(Player owner)
      Returns the primary active pet for the given Bukkit player, or null.
      Parameters:
      owner - the pet's owner
      Returns:
      the owner's primary active pet, or null if none is active
    • getPet

      @Deprecated public Pet getPet(MyPetPlayer owner)
      Deprecated.
      answers for the primary pet only, which was the whole roster until multi-pet shipped. Use getPets(MyPetPlayer) for anything that should affect every pet the player has out, or getPrimaryPet(MyPetPlayer) when the primary is genuinely what you want.
      Parameters:
      owner - the pet's owner
      Returns:
      the owner's primary active pet, or null if none is active
    • getPet

      @Deprecated public Pet getPet(Player owner)
      Parameters:
      owner - the pet's owner
      Returns:
      the owner's primary active pet, or null if none is active
    • getPets

      public List<Pet> getPets(MyPetPlayer owner)
      Returns all of the player's active pets, in activation order. Never null.

      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

      public boolean hasRoomForActivePet(MyPetPlayer owner)
      Whether owner can 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 false return does NOT mean activatePet(de.Keyle.MyPet.api.entity.StoredPet) will fail -- it always makes room by retiring the oldest active pet. What a false should make a caller do is set by the MyPet.Store-Oldest-When-Full config option (default true):

      • 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 option true it 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.
      An addon adding its own acquisition path should follow the first shape, or a server that turned the option off will still lose pets through it.
      Parameters:
      owner - the pet's owner
      Returns:
      true if the owner is below their active-pet cap
    • trimToActivePetCap

      public int trimToActivePetCap(MyPetPlayer owner)
      Deactivates pets, oldest activation first, until owner is 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. Lowering Max-Active-Pet-Count, or revoking a MyPet.petlimit.active.<n> node, leaves pets out that no longer fit.

      Parameters:
      owner - the pet's owner
      Returns:
      how many pets were deactivated
    • getPets

      public List<Pet> getPets(Player owner)
      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

      protected int getMaxActivePets(MyPetPlayer owner)
      Maximum simultaneously-active pets for owner: the server ceiling (MyPet.Max-Active-Pet-Count, default 1) narrowed by the highest MyPet.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

      public Pet[] getAllActivePets()
      Returns a snapshot array of all currently active pets across all players.
      Returns:
      every active pet on the server
    • getPetFromEntity

      public Pet getPetFromEntity(Entity entity)
      Resolves a Bukkit entity to its owning Pet via the entity-UUID index. Returns null if the entity is not a live pet entity.
      Parameters:
      entity - the Bukkit entity to resolve
      Returns:
      the pet that entity belongs to, or null if it is not a pet
    • registerPetEntity

      public void registerPetEntity(UUID entityUuid, Pet pet)
      Registers the live entity→pet binding. Called from Pet#setBukkitEntity.
      Parameters:
      entityUuid - the live entity's UUID
      pet - the pet it belongs to
    • unregisterPetEntity

      public void unregisterPetEntity(UUID entityUuid)
      Removes a live entity→pet binding. Called from Pet#setBukkitEntity.
      Parameters:
      entityUuid - the entity UUID to forget
    • hasActivePet

      public boolean hasActivePet(MyPetPlayer player)
      Returns true if the given player has an active pet.
      Parameters:
      player - the player to test
      Returns:
      true if that player has a pet out
    • hasActivePet

      public boolean hasActivePet(Player player)
      Returns true if the given Bukkit player has an active pet.
      Parameters:
      player - the player to test
      Returns:
      true if that player has a pet out
    • hasActivePet

      public boolean hasActivePet(String name)
      Returns true if the player with this name has an active pet.
      Parameters:
      name - the player name to test
      Returns:
      true if that player has a pet out
    • ownsAnyPet

      public boolean ownsAnyPet(UUID playerUuid)
      Returns true if the player owns at least one pet — active or stored. Reads the cached petOwners set, 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's refreshOwnership.
      Parameters:
      playerUuid - the player to test
      Returns:
      true if that player owns at least one pet, active or stored
    • setOwnsPet

      public void setOwnsPet(UUID playerUuid, boolean owns)
      Updates the cached ownership flag for a player. Called by the async refresh.
      Parameters:
      playerUuid - the player to record
      owns - true if they own at least one pet
    • snapshot

      public abstract PersistedPet snapshot(Pet activePet)
      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's withX methods or toBuilder.
      Parameters:
      activePet - the live pet to snapshot
      Returns:
      an immutable record carrying the pet's persistent fields
    • activatePet

      public abstract Optional<Pet> activatePet(StoredPet storedPet)
      Activates a stored pet — creates the live Pet instance, 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

      public Optional<Pet> restorePet(StoredPet storedPet)
      Activates like activatePet(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

      public Pet 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, else null when nothing is out.
      Parameters:
      owner - the pet's owner; null yields null
      Returns:
      the pet commands should act on, or null when none is out
    • getSelectedPet

      public Pet getSelectedPet(Player owner)
      The pet a command with no pet named acts on; see getSelectedPet(MyPetPlayer).
      Parameters:
      owner - the pet's owner
      Returns:
      the pet commands should act on, or null when none is out
    • deactivatePet

      public abstract boolean deactivatePet(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.
      Parameters:
      owner - the pet's owner
      pet - the pet to deactivate; must currently be active for owner
      update - if true, persists the pet's current state to the repository before deactivation
      Returns:
      true if the pet was deactivated
    • deactivatePets

      public boolean deactivatePets(MyPetPlayer owner, boolean update)
      Deactivates every pet the owner currently has active, in activation order.
      Parameters:
      owner - the pet's owner
      update - if true, persists each pet's state before deactivating it
      Returns:
      true if 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. Use deactivatePets(MyPetPlayer, boolean) to deactivate all of them, or deactivatePet(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 owner
      update - whether to persist the pet as it is put away
      Returns:
      true if a pet was deactivated
    • getStoredPets

      public abstract CompletableFuture<List<StoredPet>> getStoredPets(MyPetPlayer owner)
      Lists all pets — active or stored — owned by the given player.

      The returned CompletableFuture completes 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 -> ...) or player.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

      public abstract CompletableFuture<Void> refreshOwnership(MyPetPlayer owner)
      Asynchronously re-derives the cached ownsAnyPet(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