> 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/pinnagiveaways/reference/api.md).

# Developer API

Add the plugin jar as a `provided` dependency and `softdepend: [PinnaGiveaways]` in your plugin.yml. Everything public is in `es.edwardbelt.pinnagiveaways.api`; every other class may change or be renamed between versions. Call it from the main thread.

## PinnaGiveawaysAPI

Static and safe to call while PinnaGiveaways is disabled (lookups then return null / empty / false / -1).

| Method                                                          |                                                                                                                      |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `available()`                                                   | PinnaGiveaways is running                                                                                            |
| `giveawayIds()`                                                 | every giveaway id of config.yml                                                                                      |
| `giveaway(id)`                                                  | a `GiveawayInfo` snapshot (id, displayName, prize, intervalMillis, minPlayers, winners, rewards, sponsored), or null |
| `millisUntil(id)`                                               | ms until an automatic giveaway runs; -1 for a staff-only or unknown one                                              |
| `running()`                                                     | the `GiveawayInfo` rolling now, or null                                                                              |
| `start(id)`                                                     | starts it like `/giveaway start`; false when it couldn't                                                             |
| `lastWinners(id)`                                               | last winners' names (`"Steve, Alex"`), `sponsored` for the last sponsored one                                        |
| `sponsorQueueSize()`                                            | sponsored giveaways waiting on this server                                                                           |
| `isAnimationHidden(uuid)`                                       | an online player hid the animation                                                                                   |
| `isEligible(uuid)`                                              | an online player takes part                                                                                          |
| `currencyIds()`                                                 | currencies listed in config.yml or registered                                                                        |
| `registerCurrency(GiveawayCurrency)` / `unregisterCurrency(id)` | your own currency                                                                                                    |

## Your own currency

```java
PinnaGiveawaysAPI.registerCurrency(new GiveawayCurrency() {
    public String id() { return "shards"; }
    public String displayName() { return "Shards"; }
    public BigDecimal balance(UUID player) { return myPlugin.shards(player); }
    public boolean withdraw(UUID player, BigDecimal amount) { return myPlugin.takeShardsIfEnough(player, amount); }
    public boolean deposit(UUID player, BigDecimal amount) { myPlugin.addShards(player, amount); return true; }
    // optional: isReady(UUID) (default: the player is online), wholeNumbers() (default false)
});
```

`withdraw` must only take the amount when the player has it. Return false from `deposit` (or `isReady`) when it can't be paid now: the plugin keeps it and pays it when the player is back. The id then works in `give-eco shards 50`, `sponsor.currency` and menu items; list it under `currencies:` with `provider: api` and `currency: shards` to give it a name, format and sponsor limits.

## Events

| Event                  | When                                                                                                                                  | Cancellable                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `GiveawayStartEvent`   | a giveaway is about to roll (participants known, nothing drawn): `getGiveaway()`, `getParticipants()`, `getSponsor()`                 | yes: the run is skipped, a sponsored one refunded |
| `GiveawayWinEvent`     | a winner is revealed, before their reward: `getWinner()`, `getWinnerName()`, `getRoll()`, `getCurrency()` / `getAmount()` (sponsored) | no                                                |
| `GiveawayEndEvent`     | every winner revealed and rewarded: `getWinners()`                                                                                    | no                                                |
| `GiveawaySponsorEvent` | a player confirmed a sponsorship, before it is paid: `getSponsor()`, `getCurrency()`, `getAmount()`, `getPrize()`                     | yes: nothing is taken or queued                   |

All events fire on the main thread.