> 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/features/giveaways.md).

# Giveaways & Rewards

Each entry under `giveaways:` is one giveaway:

```yaml
giveaways:
  hourly:
    display-name: '&#FFC23D&lHourly Giveaway'
    prize: '&a$25,000'
    interval: '1h'        # '30m', '1h30m', '1d'... '0' = only with /giveaway start
    min-players: 2        # skipped (retried next interval) with fewer players online
    winners: 1            # rolls in a row, each a different winner (1-10)
    icon: 'SUNFLOWER'     # menu item
    rewards:              # run for each winner
      - 'give-eco money 25000'
      - 'console give {player} diamond 3'
      - 'message &7Enjoy your prize!'
```

Ids may use letters, digits, `-` and `_`.

## How a giveaway runs

* Automatic giveaways count down and announce the time left at every second listed in `announce-at`.
* Only one giveaway rolls at a time; one that comes due meanwhile starts right after.
* After a restart, automatic giveaways wait `start-delay-seconds` so players can join first.
* The winners are drawn when it starts and rewarded when the reel reveals them. If the server stops mid-animation, they are still rewarded.
* Players can hide the animation for themselves (`/giveaway toggle` or the menu): they still take part and see the winner in chat.

## Who takes part

Everyone online with `pinnagiveaways.participate` (all players by default), except players with the `exempt-permission` (e.g. `pinnagiveaways.exempt` for staff).

```yaml
entries:
  'pinnagiveaways.entries.2': 2
  'pinnagiveaways.entries.3': 3
```

A player counts with the highest entry permission they have (1 without any): more entries = a higher chance. With several winners, each player can only win once per giveaway.

## Rewards

Reward lines are actions, written like PinnaPrison's (`action arguments`, or `[action] arguments`):

| Action                                                                      |                                                                                         |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `give-eco <currency> <amount>`                                              | pays a [currency](/p/pinnagiveaways/features/currencies.md) (`give-currency` works too) |
| `take-eco <currency> <amount>`                                              | takes it                                                                                |
| `console <command>` / `player <command>`                                    | a command as the console / the winner                                                   |
| `message <text>`, `cmessage <text>`, `broadcast <text>`, `actionbar <text>` | texts                                                                                   |
| `title <title>\|<subtitle>`, `titlewithsubtitle <title>\|<subtitle>`        | a title                                                                                 |
| `sound <sound> [volume] [pitch]`, `sound-all ...`                           | sounds                                                                                  |

Tokens: `{player}` `{uuid}` `{prize}` `{giveaway}`, and PlaceholderAPI placeholders. A line starting with `[if <condition>]` only runs while the condition holds (`[if %player_level% >= 10] give-eco money 5000`).

`give-eco` is paid at once when the currency can take it; otherwise (a PinnaPrison / EdTools... currency of a player who is offline, or a currency whose plugin is missing) it is kept and paid as soon as they are back, with the `reward-paid-late` message.

**Offline winners** (they logged off during the reel) still get every `give-eco` and `console` line without an `[if]` condition; other lines are logged as skipped. Every reward is logged in the console.

## The winner's title

`winner-title: true` shows `winner-title` / `winner-subtitle` (messages.yml) to the winner; `winner-title-times` sets its fade-in, stay and fade-out in ticks.