Interface Pet

All Superinterfaces:
Scheduler, StoredPet
All Known Subinterfaces:
PetAmphibiousEntity, PetAquaticEntity, PetBaby, PetEquipment, PetFlyingEntity, PetInteractionGate, PetLightningConvertible, PetMetamorphic, PetNaturalDrop, PetSittable, PetSunSensitive, PetSwimmingEntity, PetWaterSensitive, PetZombifiable

public non-sealed interface Pet extends StoredPet, Scheduler
Active, in-world pet. Extends the read-only StoredPet contract with the mutators the live entity needs as it takes damage, gains XP, eats, and is renamed. Mutations on the persisted snapshot type PersistedPet use withX / Builder instead — only the active pet (this interface) is genuinely mutable.
  • Method Details

    • setUUID

      void setUUID(UUID uuid)
      Sets the pet's unique id.
      Parameters:
      uuid - the pet's new unique id
    • setOwner

      void setOwner(MyPetPlayer owner)
      Transfers the pet to a different owner.
      Parameters:
      owner - the player the pet now belongs to
    • setPetName

      void setPetName(String petName)
      Updates the pet's display name (MiniMessage format).
      Parameters:
      petName - the new name, in MiniMessage format
    • setPetType

      void setPetType(PetType petType)
      Changes which species the pet is.
      Parameters:
      petType - the species the pet becomes
    • setWorldGroup

      void setWorldGroup(String worldGroup)
      Moves the pet into a different world group.
      Parameters:
      worldGroup - name of the world group the pet belongs to
    • setVolume

      void setVolume(OptionalDouble volume)
      Sets this pet's sound-volume override.
      Parameters:
      volume - the override in [0, 1], or empty to inherit the owner's setting
    • setHealth

      void setHealth(double health)
      Sets the pet's current health, clamped to [0, getMaxHealth()]. Setting to 0 triggers death handling.
      Parameters:
      health - the new health; clamped into [0, getMaxHealth()]
    • setSaturation

      void setSaturation(double saturation)
      Sets saturation (1–100). Reaching 1 disables hunger drain.
      Parameters:
      saturation - the new saturation, from 1 to 100
    • setRespawnTime

      void setRespawnTime(int respawnTime)
      Sets the respawn countdown in seconds. Zero means alive.
      Parameters:
      respawnTime - seconds until the pet may respawn; 0 means alive
    • setLastUsed

      void setLastUsed(long lastUsed)
      Records when the pet was last active.
      Parameters:
      lastUsed - epoch milliseconds when the pet was last active
    • setWantsToRespawn

      void setWantsToRespawn(boolean wantsToRespawn)
      Sets whether the pet should return on its own after being despawned.
      Parameters:
      wantsToRespawn - true to have the pet spawn again on the owner's next call or login
    • setExp

      void setExp(double exp)
      Sets raw XP. Triggers level-up/down logic internally.
      Parameters:
      exp - the new raw experience total
    • setSkilltree

      void setSkilltree(Skilltree skilltree)
      Single-arg form that updates the skilltree without firing PetSelectSkilltreeEvent. Used during pet activation when the skilltree is being restored from persistence rather than chosen.
      Parameters:
      skilltree - the skilltree to restore
    • getExperience

      PetExperience getExperience()
      Returns the experience tracker managing XP gain and level curves.
      Returns:
      this pet's experience tracker
    • removePet

      void removePet()
      Despawns and deactivates the pet. Equivalent to removePet(true) — the pet will attempt to respawn on the next call/login.
    • removePet

      void removePet(boolean wantsToRespawn)
      Despawns and deactivates the pet.
      Parameters:
      wantsToRespawn - if true, the pet will auto-spawn on the owner's next login or call command
    • createEntity

      Pet.SpawnFlags createEntity()
      Attempts to spawn the pet at the owner's location.
      Returns:
      result flag indicating success or the reason for failure
    • createEntity

      Pet.SpawnFlags createEntity(Location spawnLocation)
      Attempts to spawn the pet at the specified location.
      Parameters:
      spawnLocation - where to place the pet
      Returns:
      result flag indicating success or the reason for failure
    • getStatus

      Pet.PetState getStatus()
      Returns the current lifecycle state of this pet.
      Returns:
      the pet's current lifecycle state
    • getCachedStatus

      Pet.PetState getCachedStatus()
      Returns the last cached pet status without touching the Bukkit entity. Safe to call from any thread on Folia. Use this when ticking from a thread that does not own the pet's region.
      Returns:
      the last known lifecycle state, read without touching the Bukkit entity
    • setStatus

      void setStatus(Pet.PetState status)
      Moves the pet into a different lifecycle state.
      Parameters:
      status - the lifecycle state to move the pet into
    • getLocation

      Optional<Location> getLocation()
      Returns the pet's current world location, or empty if the Bukkit entity is not spawned.
      Returns:
      the pet's location, or empty if its entity is not spawned
    • getMaxHealth

      double getMaxHealth()
      Returns the current max health (base and Life skill bonus). May differ from the starting HP configured in PetInfo.
      Returns:
      the current maximum health, base plus any Life skill bonus
    • getSkills

      Skills getSkills()
      Returns the skill container holding all active skill instances.
      Returns:
      the container holding this pet's skill instances
    • autoAssignSkilltree

      boolean autoAssignSkilltree()
      Attempts to auto-assign a skilltree based on permission or config rules. Called on first activation if no tree is already set.
      Returns:
      true if a tree was assigned
    • getBukkitEntity

      Mob getBukkitEntity()
      Returns the underlying Bukkit mob, or null if the pet is not currently spawned (dead/despawned).
      Returns:
      the pet's mob, or null if it is not currently spawned
    • setBukkitEntity

      void setBukkitEntity(Mob mob)
      Binds a freshly spawned Bukkit mob to this pet instance.
      Parameters:
      mob - the freshly spawned mob to bind to this pet
    • getPetNavigation

      AbstractNavigation getPetNavigation()
      Returns the navigation controller for this pet's movement.
      Returns:
      the navigation controller driving this pet's movement
    • getDamage

      double getDamage()
      Returns mêlée damage dealt by this pet (base and Damage skill).
      Returns:
      mêlée damage per hit, base plus any Damage skill bonus
    • getRangedDamage

      double getRangedDamage()
      Returns ranged damage for projectile-shooting pets.
      Returns:
      damage per projectile, for pets that shoot
    • isPassive

      boolean isPassive()
      Returns true if the pet's skilltree has no damage-dealing skills active — the pet will not attack even if provoked.
      Returns:
      true if the pet has no damage-dealing skill active and will not attack
    • hasTarget

      boolean hasTarget()
      Returns true if the pet has an active combat target.
      Returns:
      true if the pet currently has a combat target
    • decreaseSaturation

      void decreaseSaturation(double value)
      Reduces saturation by the given amount (hunger tick).
      Parameters:
      value - how much saturation to remove
    • setSkilltree

      boolean setSkilltree(Skilltree skilltree, PetSelectSkilltreeEvent.Source source)
      Sets the skilltree and fires PetSelectSkilltreeEvent, allowing cancellation. Use this for player-initiated selections.
      Parameters:
      skilltree - the skilltree to apply
      source - who/what triggered the selection
      Returns:
      true if the tree was applied (event not canceled)
    • isSitting

      boolean isSitting()
      Returns true if the pet is in its sitting/stay pose.
      Returns:
      true if the pet is sitting rather than following
    • setSitting

      void setSitting(boolean sitting)
      Puts the pet into or takes it out of its sitting/stay pose.
      Parameters:
      sitting - true to sit the pet down, false to have it follow again
    • setMinDistanceStep

      void setMinDistanceStep(int step)
      Sets how close the pet lets itself get to its owner before stepping back. Out-of-range values are clamped to 1..5.
      Parameters:
      step - the personal-space step
    • setMaxDistanceStep

      void setMaxDistanceStep(int step)
      Sets how far the pet may fall behind before it starts following. Out-of-range values are clamped to 1..5.
      Parameters:
      step - the follow-distance step
    • getPetTarget

      LivingEntity getPetTarget()
      Returns the current combat target, or null if none.
      Returns:
      the current combat target, or null if there is none
    • setTarget

      void setTarget(LivingEntity target)
      Sets a combat target with TargetPriority.Overwrite.
      Parameters:
      target - the entity to attack
    • setTarget

      void setTarget(LivingEntity target, TargetPriority priority)
      Sets a combat target if the given priority is higher than the current one. Lower-priority calls are ignored.
      Parameters:
      target - the entity to attack
      priority - how strongly this target claim should hold; a lower priority than the current one is ignored
    • forgetTarget

      void forgetTarget()
      Clears the current target and resets priority to None.
    • getTargetPriority

      TargetPriority getTargetPriority()
      Returns the priority level of whoever set the current target.
      Returns:
      the priority the current target was set with
    • canMove

      boolean canMove()
      Returns true if the pet is able to move (spawned, not sitting, not riding, entity is alive).
      Returns:
      true if the pet is spawned, alive, and neither sitting nor being ridden
    • removeEntity

      void removeEntity()
      Removes the Bukkit entity from the world without changing pet state. Used during chunk-unload or teleport transitions.
    • callToOwner

      Pet.SpawnFlags callToOwner()
      Calls the pet to its owner. If the pet is already spawned, despawns it first (preserving auto-respawn intent) and then re-spawns at the owner's location. Returns the spawn result for the caller to handle.
      Returns:
      the result of the spawn attempt
    • sendAway

      void sendAway()
      Sends the pet away — equivalent to removePet(false). The pet stays owned but will not auto-spawn on the next login or call until it is summoned again.
    • updateNameTag

      default void updateNameTag()
      Re-renders the pet's name tag from the current state and config.
    • updateVisuals

      default void updateVisuals()
      Pushes all visual states (variant, baby, collar, etc.) to the mob.
    • onMeleeHitLanded

      default void onMeleeHitLanded(LivingEntity target)
      Hook fired by PetMeleeAttackGoal immediately after a successful melee hit (one that reduced the target's health). Default no-op; pet implementations override to apply post-hit effects that vanilla normally runs inside the mob's doHurtTarget (e.g., IronGolem toss-up).
      Parameters:
      target - the entity that was hit
    • tickRespawnTimer

      default void tickRespawnTimer()
      Ticks the respawn countdown for a dead pet. Must be invoked from the owner's scheduler (not the pet entity's), because the dead Bukkit mob is removed from the world shortly after death and its per-entity scheduler stops firing.
    • showPotionParticles

      default void showPotionParticles(Color color)
      Displays a coloured potion-swirl particle above the pet.
      Parameters:
      color - the swirl colour to display
    • hidePotionParticles

      default void hidePotionParticles()
      Stops any active potion particle effect.
    • makeSound

      default void makeSound(String sound, float volume, float pitch)
      Plays a sound at the pet's location. Silently ignores invalid sound names (e.g., sounds added in newer MC versions).
      Parameters:
      sound - namespaced sound name; an unknown name is ignored
      volume - playback volume
      pitch - playback pitch
    • setLocation

      default void setLocation(Location loc)
      Async-teleports the pet to the given location.
      Parameters:
      loc - where to teleport the pet
    • hasPetRider

      default boolean hasPetRider()
      Returns true if a player is currently riding this pet.
      Returns:
      true if a player is currently riding this pet
    • onInteract

      default boolean onInteract(Player player, ItemStack item, EquipmentSlot hand)
      Called when a player right-clicks the pet. Implementations handle feeding, equipment, and skill interactions.
      Parameters:
      player - the interacting player
      item - the item they were holding
      hand - the hand the item was held in
      Returns:
      true if the interaction was consumed
    • consumePendingSnapshot

      default byte[] consumePendingSnapshot()
      Single-shot read of the serialized snapshot bytes captured at the pet's last despawn, used by the spawner to deserialize a vanilla mob with the pet's prior visual state. Default null — only the active impl overrides with real semantics (read-and-clear).
      Returns:
      the pending snapshot bytes, or null if none were captured
    • isHostAwaitingAdoption

      default boolean isHostAwaitingAdoption()
      Whether the pet's current host is a creature its provider plugin spawned that MyPet has bound but not yet adopted (goals, attributes and marker still pending). While true, the host must not be snapshotted: its provider may still be applying the model, and restoring such a snapshot later would bring back a bare host instead of the real creature. Default false; only the active impl tracks it, and it clears itself when the host changes.
      Returns:
      true while the host is bound but not yet adopted
    • setHostAwaitingAdoption

      default void setHostAwaitingAdoption(boolean awaiting)
      Marks whether the pet's current host is still awaiting adoption. No-op by default; only the active impl stores it.
      Parameters:
      awaiting - true while the provider-spawned host is bound but not yet adopted
      See Also: