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

# Sponsored Giveaways

Any player with `pinnagiveaways.sponsor` can pay for a giveaway everyone else can win: `/giveaway sponsor` (or the Sponsor button of the giveaways menu) opens a menu with preset amounts and a custom amount typed in chat, then a confirm menu. `/giveaway sponsor <amount> [currency]` goes straight to the confirm menu.

The amount is taken when they confirm and the giveaway joins a queue. It starts `start-delay-seconds` later (countdown at `announce-at`), one giveaway at a time, and its single winner gets the whole amount, minus the currency's sponsor tax.

```yaml
sponsor:
  enabled: true
  currency: 'money'          # the currency of 'currencies:' the menus use by default
  min-players: 2             # players who can win, needed to sponsor and again when it starts
  sponsor-can-win: false
  start-delay-seconds: 10
  queue-limit: 5             # sponsored giveaways waiting at once
  per-player-queue: 1        # ... per player
  cooldown: '0'              # '5m', '1h'... between two sponsorships of a player
  prompt-timeout-seconds: 30 # to type a custom amount in chat
  cancel-words: ['cancel', 'exit']
  display-name: '&#7CFF6B&l{sponsor}''s Giveaway'
  prize: '&a{formatted}'
  icon: 'EMERALD'
  gui: { menu: 'giveaway-sponsor', confirm: 'giveaway-sponsor-confirm' }
```

The minimum, maximum and tax are set per currency (`currencies.<id>.sponsor`, see [Currencies](/p/pinnagiveaways/features/currencies.md)), so one menu can offer sponsoring in several currencies: give each preset item its own `currency:`.

Tokens of the texts: `{sponsor}`, `{amount}` (5,000), `{amount-short}` (5k), `{currency-name}`, `{formatted}` (the currency's format, e.g. $5,000), `{prize}`.

## Safety

* The balance is checked when the confirm menu opens and again on confirm, and taken in one check-and-take: a player can never sponsor money they lost meanwhile.
* If fewer than `min-players` can win when it starts (or another plugin cancels it), it is cancelled and the sponsor gets everything back, tax included.
* Winners and sponsors who are offline, or whose balance isn't loaded, are paid as soon as they are back.
* Waiting sponsored giveaways are saved, so a restart doesn't lose them; they wait `start-delay-seconds` again after it.
* The typed amount never reaches the chat (nor chat games or Discord relays).

## The stage

The animation opens with the sponsor's own player NPC: it pops in under "GIVEAWAY SPONSORED BY" sitting on its seat, waves, and its seat glides it to the left to watch the reel. When the reel stops, the winning head flies to the right and grows into the winner's NPC, and the sponsor throws them the prize one piece at a time while a counter adds it up. Like the reel, everything is packet-based and shown only to each player.

```yaml
sponsor:
  animation:
    npc-scale: 0.6
    seat: 'DARK_OAK_SLAB'      # '' = they sit on thin air
    winner-platform: 'GOLD_BLOCK'
    hand-item: 'EMERALD'       # what is thrown; '' = nothing
    gifts: 8
    npc-viewers: 300
    npcs-per-tick: 25
    seat-turn: 38              # degrees the seats turn to the centre
    label-scale: 0.36
    texts: { title, name, prize, sponsor-label, winner-label, gift-counter }
    sounds: { appear, text, wave, sit, grow, throw, catch, gifted }
    particles: { appear, swirl, sit, grow, winner, catch, gifted, vanish }
    timeline: { title, name, prize, wave, texts-out, glide, glide-length, sit,
                fly, fly-length, grow, grow-length, throw-every, flight, celebrate }
```

The `timeline` (ticks) sets when each step happens: the entrance (the reel starts 12 ticks after `sit`), the head's flight and growth on the reveal, and the throws. A sponsored reveal always lasts long enough for the winner's NPC to take the head's place.

On big servers only the first `npc-viewers` players get the two player NPCs (the sponsor and the winner first, then the others in join order); everyone else sees the same scene without them. The NPCs are made `npcs-per-tick` at a time (some already during the countdown) and kept for the next sponsored giveaway.

Try it alone with `/giveaway preview sponsor [amount] [currency]`.