# API

## How to use

To use and implement the ConditionalEvents API, create a plugin and import ConditionalEvents.jar as an external jar or use maven and set the following on your pom.xml file:

```xml
<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.ajneb97</groupId>
  <artifactId>ConditionalEvents</artifactId>
  <version>4.65.1</version>
  <scope>provided</scope>
</dependency>
```

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

## Methods

You can access all API static methods using the **ConditionalEventsAPI** class.

## Events

The plugin has one event:

```java
//Event called when conditions for an event are accomplished and a group
//of actions is executed.
@EventHandler
public void actionsExecuted(ConditionalEventsEvent event){
   Player player = event.getPlayer(); //Returns null if not a player event
   String eventName = event.getEvent();
   String actionName = event.getAction();
}
```

## Creating your own Actions

The API allows you to create custom and unique ConditionalEvents actions, that you can add to your events.

First, start by creating a class associated with your new action. This class must extends from the **ConditionalEventsAction** class. For example, I want to create a CE action to change the weather of a certain world.

```java
public class ChangeWeatherAction extends ConditionalEventsAction {

}
```

Next, create a constructor that calls the super constructor with a certain name. This name corresponds to the name of the action, the one you use in your event (for example, `cancel_event`, `message`, `console_command`, `playsound`, and so on). In my case the name of the action will be **change\_weather.**

```java
public class ChangeWeatherAction extends ConditionalEventsAction {
    public ChangeWeatherAction() {
        super("change_weather");
    }
}
```

Now, override the `execute` method from the super class, which provides a Player, a String and an Event object.

```java
public class ChangeWeatherAction extends ConditionalEventsAction {
    public ChangeWeatherAction() {
        super("change_weather");
    }

    @Override
    public void execute(Player player, String actionLine, Event minecraftEvent) {
        
    }
}
```

* **Player player**: The player involved in the event. If there is no player, this variable will be null.
* **String actionLine**: Everything that comes after the name of the action. Example:

```yaml
# The actionLine variable here would be "say Welcome %player%"
console_command: say Welcome %player%

# The actionLine variable here would be "spawn;SUN"
change_weather: spawn;SUN
```

* **Event minecraftEvent:** The minecraft/spigot event involved.

You can now create your own logic and do whatever you want with the parameters stored in the actionLine String.

```java
public class ChangeWeatherAction extends ConditionalEventsAction {
    public ChangeWeatherAction() {
        super("change_weather");
    }

    @Override
    public void execute(Player player, String actionLine, Event minecraftEvent) {
        // Format: change_weather: <world>;<weather>
        // weather: SUN,STORM,THUNDER
        String[] sep = actionLine.split(";");
        World world = Bukkit.getWorld(sep[0]);
        switch(sep[1]){
            case "SUN":
                world.setStorm(false);
                world.setThundering(false);
                break;
            case "STORM":
                world.setStorm(true);
                break;
            case "THUNDER":
                world.setThundering(true);
                break;
        }
    }
}
```

Finally, you must register this new action and make ConditionalEvents know about it. For that, when enabling your plugin, use the **ConditionalEventsAPI.registerApiActions()** method. The first parameter is the object of your plugin class, and the second parameter is a new object of your action class.

```java
public void onEnable(){
     ConditionalEventsAPI.registerApiActions(this,new ChangeWeatherAction());
}
```

&#x20;If you are creating multiple action types, you can concatenate more objects.

```java
public void onEnable(){
     ConditionalEventsAPI.registerApiActions(this,new ChangeWeatherAction(), new GiveDiamondAction());
}
```