# Custom Events

## Explanation

ConditionalEvents allows you to check for any event you want, even from other plugins. Below you will find an explained example to show you how these events work.

{% hint style="warning" %}
This section is mainly dedicated for people which have Java knowledge and know the basics of how to create a Minecraft plugin. If you don't understand this, feel free to contact me through private message (on Spigot) or in the discussion of the plugin.
{% endhint %}

Here is an example of a **custom event** which will activate when a player places a Turret of my plugin [`DefensiveTurrets`](https://www.spigotmc.org/resources/defensiveturrets-defend-yourself-using-turrets-1-8-1-16.67188/). Remember you can add as many custom events you want, just add a new section with a new name. The plugin must have an API for this to work.

```yaml
example1:
    type: custom
    custom_event_data:
      event: dt.ajneb97.api.TurretPlaceEvent
      player_variable: getPlayer()
      variables_to_capture:
      - '%turret_world%;getLocation().getWorld().getName()'
    conditions:
    - '%turret_world% equals spawn'
    actions:
      default:
      - 'cancel_event: true'
      - "message: &cYou can''t place turrets on this world."
```

As you can see, there is a new option called `custom_event_data` which is used just for custom events.

## Event

This option defines the class of the event. If you want to check for a spigot/bukkit event, you can obtain this value in the Spigot javadocs: <https://hub.spigotmc.org/javadocs/spigot/allclasses-index.html> Just go to the link, search the event and click on it. In the first lines you will see the "package name" of this class, for example:\
[**org.bukkit.event.player.PlayerLevelChangeEvent**](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/player/PlayerLevelChangeEvent.html)<br>

On the other hand, if you want to check a plugin event you need the API and the package for that event.

```yaml
event: "dt.ajneb97.api.TurretPlaceEvent"
```

## Player Variable

This is the method which will return the Player variable. The player variable contains all information about the user who is performing this event. For spigot/bukkit events it will most of the time be getPlayer().

You can create non-player events that don't have the getPlayer() method, if that is the case, remove the `player_variable` option.

```yaml
player_variable: "getPlayer()"
```

{% hint style="info" %}
On all custom events you can check whether the player exists or not using this variable in the conditions: `%player_is_present%`. Can be 'true' or 'false'.
{% endhint %}

## Variables to Capture

Here you need to define the variables to capture and save. Each of the variables will be obtained executing a method. This method is provided by the API of the plugin, or the same bukkit/spigot class. For example, in the `PlayerLevelChangeEvent` link I used before, you can find the getNewLevel() and getOldLevel() methods, which returns the new and old level of the player when the event is executed.

Use the following format: `<variable_to_capture>;<method>`

```yaml
variables_to_capture:
 - '%turret_world%;getLocation().getWorld().getName()'
```


---

# Agent Instructions: 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/custom-events.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.