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

# Overview

Giveaways among the online players, revealed with a **3D reel of everyone's heads** spinning in front of each player. They run on an interval, when staff start one, or when a player **sponsors** one with their own money: the sponsor appears on stage as a player NPC, watches the reel and throws the prize to the winner.

Everything you see is packet-based (nothing is spawned in the world, every player only sees their own reel) and runs on its own thread, so it stays smooth on big and lagging servers. It works on **any Paper 1.21+ server**: every other plugin is optional.

## What's inside

| Feature                 | What it adds                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Giveaways**           | As many as you like: interval or staff-only, minimum players, several winners, extra entries by permission          |
| **Rewards**             | `give-eco` in any currency, console and player commands, messages, titles, sounds; offline winners are still paid   |
| **Sponsored giveaways** | Players pay into a giveaway (preset or typed amount, confirm menu), a queue, refunds, cooldowns, tax                |
| **Currencies**          | Vault, PlayerPoints, PinnaPrison, EdPrison, EdTools (EdGens) and EdDungeons, plus your own through the API          |
| **3D reel**             | Heads on a curved drum, pointer, light-sweep title, winner glow, particles, sounds; every number configurable       |
| **Sponsor stage**       | The sponsor's and the winner's NPCs with their skins, seats, labels, the prize thrown across with a counter         |
| **Menus**               | Giveaways list, sponsor and confirm menus as yml files in PinnaPrison's menu format: vanilla chest menus by default |
| **Storage**             | YAML (`data.yml`) by default, or MySQL / MariaDB shared by several servers, with `/giveaway migrate`                |
| **Extras**              | PlaceholderAPI placeholders, a developer API with events, optional per-player languages (EdLang)                    |

## Requirements

* Paper 1.21 or newer (Java 21). The packet animations come bundled with the plugin.
* Optional: **Vault** + an economy plugin (the default `money` currency), **PlayerPoints**, **PinnaPrison**, **EdPrison**, **EdTools**, **EdDungeons** (their currencies), **PlaceholderAPI** (placeholders, and `%placeholders%` in menus), **EdLang** (per-player languages), a **MySQL / MariaDB** database.

## Quick start

1. Put `PinnaGiveaways.jar` in `plugins/` and restart.
2. Open `plugins/PinnaGiveaways/config.yml`: the `money` currency uses Vault; enable the others you have (`currencies:`). `/giveaway currencies` shows which ones loaded.
3. Edit the example giveaways under `giveaways:` and run `/giveaway reload`.
4. Try it: `/giveaway preview` plays the reel for you alone, `/giveaway preview sponsor` the sponsored version.
5. Players use `/giveaway` (menu), `/giveaway sponsor` and `/giveaway toggle`.

## Folder

```
plugins/PinnaGiveaways/
  config.yml        giveaways, currencies, sponsoring, the animation, numbers, storage
  messages.yml      every chat message and title
  guis/             giveaways.yml, giveaway-sponsor.yml, giveaway-sponsor-confirm.yml (and any menu you add)
  data.yml          timers, last winners, the sponsor queue, animation settings, payouts owed (storage.type: yaml)
```