# API

## How to use

To use and implement the ComplexTurrets API just add the plugin jar file to the external dependencies of your project or import the file into your local maven repository.

Remember to also set `depend` or `softdepend` in your plugin.yml file!

## Methods

The main class for the API is `ComplexTurretsAPI`. You can use this class whenever you want in your plugin.

```java
// Returns all turrets owned by a player.
ArrayList<PlayerTurret> turrets = ComplexTurretsAPI.getPlayerTurrets(Player player);

// Return whether a player is allied to a turret or not. 
boolean allied = ComplexTurretsAPI.isAllyToTurret(Player player,PlayerTurret playerTurret);

// Returns the turret at certain location.
PlayerTurret turret = ComplexTurretsAPI.getTurretFromLocation(Location location);

// Damages a turret.
// The player is optional and used to show an actionbar message.
ComplexTurretsAPI.damageTurret(PlayerTurret playerTurret,int damage,Player player)
```

## Events

```java
// Event called when a player tries to place a turret. 
// ct.ajneb97.api.TurretPlaceEvent
@EventHandler
public void turretPlace(TurretPlaceEvent event){
    Player player = event.getPlayer();
    Location l = event.getLocation();
    
    // This object contains all config of the turret, is not
    // the turret being placed, but the properties of it.
    Turret turret = event.getTurret();
}
```

```java
// Event called when a player tries to right click a turret. 
// ct.ajneb97.api.TurretRightClickEvent
@EventHandler
public void turretClick(TurretRightClickEvent event){
    Player player = event.getPlayer();
    PlayerTurret playerTurret = event.getPlayerTurret();
}
```

```java
// Event called when a turret levels up. 
// ct.ajneb97.api.TurretLevelUpEvent
@EventHandler
public void turretLevelUp(TurretLevelUpEvent event){
    Player player = event.getPlayer(); //Player leveling up the turret
    PlayerTurret playerTurret = event.getPlayerTurret();
    int newLevel = event.getNewLevel()
}
```

```java
// Event called when a turret is removed. 
// ct.ajneb97.api.TurretRemoveEvent
@EventHandler
public void turretRemove(TurretRemoveEvent event){
    PlayerTurret playerTurret = event.getPlayerTurret();
    
    //DAMAGE: The turret was destroyed when receiving damage, or automatically
    //        removed.
    //MANUAL: The turret was removed by a player from the inventory.
    TurretRemoveType removeType = event.getRemoveType(); 
}
```



## Creating your own Custom Target Validations

Currently, ComplexTurrets will prevent targeting an entity or player if some conditions are met, for example if you set `ignore_damage_to_invisible_players` to true in the config, turrets will avoid targeting (and shooting) invisible players.

However, sometimes you need to make other validations, maybe even checking for conditions from other plugins. That's when custom target validations can help you.

First, start by creating a class associated with your new validation. This class must extends from the **EntityValidation** class. For example, I want to create a ComplexTurret target validation to prevent targeting a player who is flying.

```java
public class TurretFlyValidation extends EntityValidation {

}
```

Next, create a constructor that calls the super constructor with a certain name. This name corresponds to the name of the validation. In my case the name of the action will be **turret\_fly\_validation**.

```java
public class TurretFlyValidation extends EntityValidation {
    public TurretFlyValidation() {
        super("turret_fly_validation");
    }
}
```

Now, override the `validate` method from the super class, which provides a LivingEntity object and a PlayerTurret object.

```java
public class TurretFlyValidation extends EntityValidation {
    public TurretFlyValidation() {
        super("turret_fly_validation");
    }

    @Override
    public boolean validate(LivingEntity livingEntity, PlayerTurret playerTurret) {
        return true;
    }
}
```

* **LivingEntity livingEntity**: The entity which the turret is targeting (is about to shoot).
* **PlayerTurret playerTurret**: The turret itself.

You can now create your own logic and check for whatever condition you want. If you want to prevent the turret from targeting the entity, you must return **false**. I have created a condition to check if the player is flying or not. If the player is flying, I will return false, since I don't want the turret from targeting those players.

```java
public class TurretFlyValidation extends EntityValidation {
    public TurretFlyValidation() {
        super("turret_fly_validation");
    }

    @Override
    public boolean validate(LivingEntity livingEntity, PlayerTurret playerTurret) {
        if(livingEntity instanceof Player){
            if(((Player)livingEntity).isFlying()){
                return false;
            }
        }
        return true;
    }
}
```

Finally, you must register this new target validation and make ComplexTurrets know about it. For that, when enabling your plugin, use the **ComplexTurretsAPI.registerApiTargetValidations()** method. The first parameter is the object of your plugin class, and the second parameter is a new object of your validation class.

```java
public void onEnable(){
     ComplexTurretsAPI.registerApiTargetValidations(this,new TurretFlyValidation());
}
```

If you are creating multiple target validations, you can concatenate more objects.

```java
public void onEnable(){
     ComplexTurretsAPI.registerApiTargetValidations(this,new TurretFlyValidation(),new AnotherValidation());
}
```
