> ## 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.

# Scratch Cards: Ticket Tiers, Prizes, and Commands

> Buy scratch card tickets across four tiers, reveal tiles in your inventory GUI, and match symbols to win configurable cash prizes in LiricCasino.

Scratch cards let you purchase a ticket, open it directly in your inventory GUI, and reveal hidden tiles one by one. When you uncover enough matching symbols, you win a payout calculated from the symbol's base prize multiplied by your ticket tier's payout multiplier. Every ticket price, prize value, and multiplier is fully configurable in `config.yml`, so server administrators can tune the economy to fit any server.

## Ticket Tiers

LiricCasino offers four scratch card tiers. Higher tiers cost more but feature larger grids, require more matches, and apply a bigger payout multiplier to every prize symbol.

| Tier     | Grid Size | Price    | Matches Required | Payout Multiplier |
| -------- | --------- | -------- | ---------------- | ----------------- |
| Basic    | 3 × 3     | \$1,000  | 3                | 1×                |
| Advanced | 5 × 5     | \$5,000  | 4                | 5×                |
| Master   | 7 × 5     | \$10,000 | 5                | 10×               |
| Giant    | 9 × 6     | \$25,000 | 6                | 25×               |

<Note>
  The grid dimensions, ticket prices, match requirements, and payout multipliers for all tiers are defined under `scratch.tiers` in `config.yml`.
</Note>

## How to Play

<Steps>
  <Step title="Buy or receive a ticket">
    Run `/scratch` (or its alias `/boleto`) to open the ticket shop GUI and purchase the tier you want. Admins can also give you a ticket directly using the give command.
  </Step>

  <Step title="Open the ticket">
    With the ticket in your hand, **right-click in the air**. Your inventory GUI opens and displays a covered grid of tiles.
  </Step>

  <Step title="Reveal the tiles">
    Click each covered tile to scratch it away and reveal the hidden symbol underneath.
  </Step>

  <Step title="Match and win">
    If the number of matching symbols on your card meets or exceeds the required match count for your tier, you win. The payout equals the symbol's `base-payout` multiplied by the tier's `payout-multiplier`.
  </Step>
</Steps>

## Prize Symbols

There are 11 configurable prize symbols. Each symbol has a `base-payout` and a weighted rarity (`weight`) — lower weight means rarer. The two lowest-value symbols pay nothing on their own but can appear as non-matching fillers.

| Symbol          | Base Payout | Rarity (weight) |
| --------------- | ----------- | --------------- |
| Netherite Block | \$250,000   | 1               |
| Diamond Block   | \$50,000    | 3               |
| Emerald Block   | \$15,000    | 8               |
| Amethyst Block  | \$5,000     | 15              |
| Gold Block      | \$2,500     | 25              |
| Iron Block      | \$1,000     | 40              |
| Ender Pearl     | \$500       | 60              |
| Blaze Powder    | \$300       | 80              |
| Apple           | \$200       | 100             |
| Wooden Stick    | \$0         | 150             |
| Coal Block      | \$0         | 150             |

<Tip>
  The actual payout you receive is `base-payout × payout-multiplier`. On a Giant ticket (25×) a Netherite match pays out \$6,250,000. Make sure your economy can handle top-tier payouts before raising multipliers.
</Tip>

## Commands

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

  <Tab title="Admin Commands">
    | Command                                  | Description                                                                                     |
    | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
    | `/scratch give <player> <tier> [amount]` | Gives the specified player one or more scratch tickets of the chosen tier without charging them |

    **Tier names** accepted by the give command match the config keys: `basico`, `avanzado`, `maestro`, `gigante`.
  </Tab>
</Tabs>

## Daily Use Limits

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

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

<Note>
  Admins with the `casinoliric.uses.admin` permission have unlimited daily uses. All limits are configurable under `scratch.uses` in `config.yml`.
</Note>

## Configuration Reference

All scratch settings live under the `scratch` key in `config.yml`.

<CodeGroup>
  ```yaml Tier configuration theme={null}
  scratch:
    tiers:
      basico:
        display-name: "&6Basic &7(3x3)"
        price: 1000.0
        rows: 3
        match-required: 3
        payout-multiplier: 1.0
      gigante:
        display-name: "&#FFD700Giant &7(9x6)"
        price: 25000.0
        rows: 6
        match-required: 6
        payout-multiplier: 25.0
  ```

  ```yaml Prize configuration theme={null}
  scratch:
    prizes:
      - material: NETHERITE_BLOCK
        display-name: "<#302B27><bold>NETHERITE!</bold>"
        base-payout: 250000.0
        weight: 1
      - material: COAL_BLOCK
        display-name: "<dark_gray><bold>COAL</bold>"
        base-payout: 0.0
        weight: 150
  ```
</CodeGroup>

<Warning>
  Increasing `payout-multiplier` on high-tier tickets significantly amplifies all prize payouts. Always test economy balance on a staging server before deploying changes.
</Warning>