> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Lottery: Jackpot Draw Setup and Ticket Management

> Run an automated hourly lottery with a growing jackpot pool, configurable ticket limits, server-wide countdown announcements, and Discord webhook alerts.

The LiricCasino lottery runs on a fully automated timer — no staff intervention required. Players buy numbered tickets for a flat price, a portion of every sale feeds the jackpot pool, and the server draws a winning number on a configurable interval. If nobody holds the winning number, the jackpot rolls over and keeps growing until someone wins. When there are multiple winners, they split the jackpot equally.

## How the Jackpot Works

Every ticket purchase contributes **50 %** of the ticket price directly to the jackpot pool (configurable via `jackpot-contribution` in `config.yml`). The pool starts at a minimum floor of **\$50,000** and accumulates across draws until a winner is found. After a win, the jackpot resets to the configured floor value.

<Note>
  The jackpot and all active tickets are persisted to `lottery.yml` in the plugin data folder. The jackpot survives server restarts.
</Note>

## Draw Cycle

<Steps>
  <Step title="Countdown begins">
    When the plugin starts (or after each completed draw), a **60-minute countdown** begins automatically. The interval is configurable via `draw-interval-minutes` in `config.yml`.
  </Step>

  <Step title="Server-wide announcements">
    The server broadcasts countdown messages to all online players at these intervals before the draw:

    | Time Remaining | Announcement  |
    | -------------- | ------------- |
    | 1 hour         | Early warning |
    | 30 minutes     | Reminder      |
    | 10 minutes     | Urgency alert |
    | 1 minute       | Final call    |
    | 30 seconds     | Imminent      |
    | 10 seconds     | Countdown     |
  </Step>

  <Step title="Winning number drawn">
    At zero, the server picks a random number between **1 and 1,000** (configurable via `number-range`). Every ticket held by any player has exactly one number assigned at purchase.
  </Step>

  <Step title="Winners determined">
    All tickets whose number matches the draw win. If multiple players hold winning tickets, the jackpot is **split equally** among them.
  </Step>

  <Step title="Discord webhook fires">
    When there is at least one winner, a Discord webhook notification is sent automatically with the winner name(s) and prize amount.
  </Step>

  <Step title="Reset and repeat">
    All tickets are cleared, the jackpot resets to the floor value if it was claimed, and a new 60-minute countdown starts immediately.
  </Step>
</Steps>

## Buying Tickets

Run `/lottery` (alias: `/loteria`) to open the ticket purchase GUI. Select how many tickets you want — up to your remaining daily limit. Each ticket costs **\$5,000** by default and is assigned a unique random number at the moment of purchase. You can hold a maximum of **5 tickets** per draw period.

<Tip>
  Buying multiple tickets increases your coverage of the 1–1,000 number range. With 5 tickets you cover 0.5 % of all possible numbers.
</Tip>

<Warning>
  Ticket numbers are randomly assigned and cannot be chosen. There is no guarantee two tickets will have different numbers, though collisions are statistically unlikely with a 1,000-number range.
</Warning>

## Daily Use Limits

<CardGroup cols={2}>
  <Card title="Default Players" icon="user">
    Up to **5 tickets** per day.
  </Card>

  <Card title="VIP Players" icon="star">
    Up to **10 tickets** per day (`casinoliric.uses.vip` permission).
  </Card>
</CardGroup>

<Note>
  Admins with `casinoliric.uses.admin` have unlimited daily ticket purchases. Limits are set under `lottery.uses` in `config.yml`.
</Note>

## Commands

<Tabs>
  <Tab title="Player Commands">
    | Command    | Description                           |
    | ---------- | ------------------------------------- |
    | `/lottery` | Opens the lottery ticket purchase GUI |
    | `/loteria` | Alias for `/lottery`                  |
  </Tab>

  <Tab title="Admin Commands">
    | Command                           | Description                                                           |
    | --------------------------------- | --------------------------------------------------------------------- |
    | `/lottery forcestart`             | Immediately triggers the draw, bypassing the countdown                |
    | `/lottery give <player> [amount]` | Gives the specified player free lottery tickets without charging them |
  </Tab>
</Tabs>

## Configuration Reference

<CodeGroup>
  ```yaml Lottery settings theme={null}
  lottery:
    active: true
    ticket-price: 5000.0
    max-tickets-per-player: 5
    draw-interval-minutes: 60
    number-range: 1000
    jackpot-start: 50000.0
    jackpot-contribution: 0.5   # 50 % of each ticket price
  ```

  ```yaml Daily use limits theme={null}
  lottery:
    uses:
      default:
        max-uses-per-day: 5
      ranks:
        vip:
          permission: "casinoliric.uses.vip"
          max-uses-per-day: 10
        admin:
          permission: "casinoliric.uses.admin"
          max-uses-per-day: -1  # unlimited
  ```
</CodeGroup>

<Warning>
  Using `/lottery forcestart` clears **all** current tickets and resets the jackpot after paying out. Use it carefully in production — it cannot be undone.
</Warning>