Developer API

This page is incomplete and out of date.

As A Maven Dependency

If you're familiar with Maven, you'll be able to automatically download EchoPet as a dependency using the following setup.

<repositories>
    <repository>
        <id>echopet-repo</id>
        <url>http://repo.dsh105.com/</url>
    </repository>
<!-- And so on... -->
</repositories>

<dependencies>
    <dependency>
        <groupId>com.dsh105<groupId>
        <artifactId>EchoPet</artifactId>
        <version>2.3.3</version>
    </dependency>
<!-- And so on... -->
</dependencies>

Note: Change the version to whatever you require (even if it is a snapshot build! ;D).

If you don't use Maven, include it as a dependency in your IDE.

Access The API

The EchoPet Developer API can be accessed used the following method.

2.2.2 and after

import io.github.dsh105.echopet.api.EchoPetAPI

public EchoPetAPI getEchoPetAPI() {
    return EchoPetAPI.getAPI();
}

2.2.1 and before

import io.github.dsh105.echopet.EchoPet
import io.github.dsh105.echopet.api.EchoPetAPI

public EchoPetAPI getEchoPetAPI() {
    Plugin plugin = this.getServer().getPluginManager().getPlugin("EchoPet");
    if (plugin == null || !(plugin instanceof EchoPet)) {
        return null;
    }

    return ((EchoPet) plugin).getAPI();
}

Using The API

The EchoPet Developer API allows developers access to a wide range of utilities that can be used to control Pets initiated using the plugin. It also allows control over the Pet AI System and Target Selection.

List Of Methods

Method Name	Description/Function
givePet(Player.class, PetType.class, Boolean.class)	Gives a Pet to the specified player. If the third parameter is true, the player will also be notified of their new Pet.
removePet(Player.class, Boolean.class	Removes any Pet a player has.
hasPet(Player.class)	Checks whether a Player has a Pet. Returns a boolean value depending on the result.
getPet(Player.class)	Gets a Player's Pet. Will return null if the Player does not have a Pet.
getAllPets()	Returns an Array of all active Pets.
teleportPet(Pet.class, Location.class)	Teleport's a Pet to a certain Location. The Pet's owner can be retrieved using pet.getOwner()
addData(Pet.class, PetData.class)	Applies/adds the specified data to a Pet.
removeData(Pet.class, PetData.class)	Removes/deactivates a data option for a Pet.
hasData(Pet.class, PetData.class)	Checks whether a Pet has a data option enabled.
setAttackTarget(Pet.class, LivingEntity.class)	Sets a Pet's target to the specified LivingEntity. Note that if the Attack Goal has not been added to the Pet's AI, this will not work.
getAttackTarget(Pet.class)	Gets the current Attack Target of a Pet. Will return null if the Pet does not have an Attack Target.
addGoal(Pet.class, GoalType.class)	Adds a predefined Goal to a Pet's AI. Usage example: addGoal(petInstance, GoalType.ATTACK);
addGoal(Pet.class, PetGoal.class, String.class)	Adds an extension of PetGoal.class to a Pet's AI. A tutorial on this can be found below.
removeGoal(Pet.class, GoalType.class)	Removes a predefined Goal from a Pet's AI. Usage example: removeGoal(petInstance, GoalType.ATTACK);
removeGoal(Pet.class, String.class)	Removes a Goal from a Pet's AI by it's Identifier
removeGoal(Pet.class, PetGoal.class)	Removes a Goal instance from a Pet's AI

Referenced Classes:

• Player.class: Player object from the Bukkit API
• PetType.class: API Enumeration, representing all available Pet Types (com.github.dsh105.echopet.data.PetData)
• Pet.class: Represents a Pet object (com.github.dsh105.echopet.entity.pet.Pet)
• Location.class: Location object from the Bukkit API
• PetData.class: API Enumeration of all valid Data options for all Pets. Note that only some data types may be applied to certain Pets. Use pet.getPetType() (com.github.dsh105.echopet.data.PetType) to check Entity Types
• LivingEntity.class: Represents a Living Entity (org.bukkit.entity.LivingEntity)
• GoalType.class: API Enumeration of already included Goals to add to a Pet's AI
• PetGoal.class: API Super class representing all PetGoals. A tutorial for extending this can be found below.

Custom Events

Event Name	Function
PetAttackEvent	Called when a Pet attempts to damage a target. Cancelling this event will not cancel the animation, only the damage dealt.
PetDamageEvent	Called when a Pet is damaged.
PetInteractEvent	Called when a Player interacts (right or left click) with a Pet.
PetMenuOpenEvent	Called when a Pet's Owner opens the PetMenu for their Pet.
PetMoveEvent	Called when a Pet moves while following it's Owner or riding.
PetRideJumpEvent	Called when a Player attempts to jump while riding their Pet.
PetRideMoveEvent	Called when a Player moves while riding their Pet.
PetSpawnEvent	Called when a Pet spawns.
PetTeleportEvent	Called when a Pet teleports.

Extending PetGoal

Custom AI Goals can be created and applied to Pets through the Developer API. For this tutorial, a simple goal (floating in water) is used.

First, create a class that extends PetGoal.

import com.github.dsh105.echopet.entity.pathfinder.PetGoal;

public class PetGoalFloat extends PetGoal {
    private EntityPet pet;

    public PetGoalFloat(EntityPet pet) {
        this.pet = pet;
    }
}

There are five important methods that can be accessed inside this class now:

• shouldStart() - Called to check whether the method should start. Use this to return true if it is to start, false if not.
• shouldFinish() - Called to check whether the method should finish running. Use this to return true if it is to finish, false if not.
• start() - Called when the Goal starts executing.
• finish() - Called when the Goal finished executing.
• tick() - Called every tick if the Goal has started.

In this example, it checks if the Pet is currently in water, and keeps it floating if it is.

@Override
public boolean shouldStart() {
    return pet.world.getMaterial((int) pet.locX, (int) pet.locY, (int) pet.locZ).isLiquid();
}

@Override
public boolean tick() {
    if (pet.aC().nextFloat() < 0.8F) {
        this.pet.getControllerJump().a();
    }
}

The final class looks like this:

import com.github.dsh105.echopet.entity.pathfinder.PetGoal;

public class PetGoalFloat extends PetGoal {
    private EntityPet pet;

    public PetGoalFloat(EntityPet pet) {
        this.pet = pet;
    }

    @Override
    public boolean shouldStart() {
        return pet.world.getMaterial((int) pet.locX, (int) pet.locY, (int) pet.locZ).isLiquid();
    }

    @Override
    public boolean tick() {
        if (pet.aC().nextFloat() < 0.8F) {
            this.pet.getControllerJump().a();
        }
    }
}