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

# Developer API

Add EdEvents as a `provided` dependency and `softdepend: [EdEvents]` in your `plugin.yml`.

```java
EdEventsAPI api = EdEventsAPI.get();   // null while EdEvents is not enabled
```

## Methods

```java
List<ActiveEvent> getActiveEvents();
ActiveEvent getActiveEvent(String eventId);
Collection<EventDefinition> getEventDefinitions();
EventDefinition getEventDefinition(String eventId);

/** Starts an event (durationSeconds <= 0 keeps the configured duration). */
EventManager.StartResult startEvent(String eventId, long durationSeconds, String startedBy);
/** Ends a running event; rewards are paid as configured. Safe from any thread. */
boolean stopEvent(String eventId);

/** Feeds progress for every running event of that objective type, honouring filters. Any thread. */
void progress(ObjectiveType type, Player player, double amount, ProgressContext context);
/** Adds progress to one event (e.g. a CUSTOM one), bypassing filters. Any thread. */
double addCustomProgress(String eventId, OfflinePlayer player, double amount, String source);

double getProgress(String eventId, UUID player);
int getPosition(String eventId, UUID player);
PlayerStats getStats(UUID player);        // wins, top3, played, bestScore...
HostHook getHost();                       // the detected plugin bridge (currencies, number formatting)
long getSecondsUntilNextEvent();          // -1 when the scheduler is disabled
```

`ActiveEvent` exposes the live state: `getTimeLeftSeconds()`, `getTop()`, `getLeader()`, `get(uuid)`, `getPosition(uuid)`, `getTotal()`, `getParticipants()`, `getDefinition()`...

### Feeding a CUSTOM event

```yaml
# events/vote-party.yml
name: "&d&lVote Party"
type: COMMUNITY
objective: {type: CUSTOM, name: "Votes", goal: 100}
```

```java
EdEventsAPI.get().addCustomProgress("vote-party", player, 1, "votes");
// or from a command / another plugin's reward list:
// /events progress {player} vote-party 1
```

## Bukkit events (`es.edwardbelt.edevents.api.event`)

| Event                | Thread            | Description                                                                                                    |
| -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `EventStartEvent`    | main              | Before an event starts. Cancellable.                                                                           |
| `EventProgressEvent` | any (often async) | Before progress is added: `getPlayer()`, `getAmount()` / `setAmount()`, `getContext()`. Cancellable.           |
| `EventWinEvent`      | main              | For every rewarded placement: `getPlayer()`, `getPlacement()`, `getValue()`.                                   |
| `EventEndEvent`      | main              | After rewards: `getReason()` (`TIME`, `GOAL_REACHED`, `COMMAND`, `RELOAD`, `SHUTDOWN`, `API`), `getWinners()`. |

All carry `getEvent()` (the `ActiveEvent`) and `getEventId()`. Check `isAsynchronous()` before touching non-thread-safe Bukkit APIs in `EventProgressEvent`.

```java
@EventHandler
public void onWin(EventWinEvent e) {
    if (e.getPlacement() == 1) discord.announce(e.getPlayer().getName() + " won " + e.getEvent().getDefinition().getName());
}
```

## Adding a host plugin

Implement `es.edwardbelt.edevents.hook.HostHook` (currencies, number formatting, action bar addon registration, progress listeners) — the four built-in hooks in `es.edwardbelt.edevents.hook.impl` are the reference.