> For the complete documentation index, see [llms.txt](https://ajneb97.gitbook.io/conditionalevents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajneb97.gitbook.io/conditionalevents/api.md).

# 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 actionGroup = event.getActionGroup();
}
```

## 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());
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ajneb97.gitbook.io/conditionalevents/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.