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

# Horse Racing: Bet on Races with Configurable Odds

> Pick one of four horses with weighted win chances and payout multipliers, wait out a 30-second countdown, and collect your winnings if your horse wins.

Horse Racing lets you wager on one of four horses, each with a distinct win probability and payout multiplier. The moment the first bet is placed, a 30-second countdown begins. Any player can place a bet during that window. When the timer hits zero, the race runs automatically using a weight-based random draw — the higher a horse's win chance, the more likely it is to win, but the lower its payout multiplier. Riskier horses pay out more when they do come through. All horse names, win chances, and odds are fully configurable in `config.yml`.

## The Horses

Four horses compete in every race. Choose based on your risk appetite — a safe favourite or a long-shot with a massive multiplier.

| Horse       | Win Chance | Payout Multiplier |
| ----------- | ---------- | ----------------- |
| Relámpago ⚡ | 40 %       | 2×                |
| Sombra 🌑   | 30 %       | 3×                |
| Tornado 🌪  | 20 %       | 5×                |
| Cometa ☄    | 10 %       | 10×               |

<Note>
  Win chances are weight-based, not strict percentages. The winner is determined by drawing a random value against the combined weight of all horses, so results are stochastic — past races do not influence future outcomes.
</Note>

## How to Play

<Steps>
  <Step title="Open the betting GUI">
    Run `/carreras` to open the horse racing betting interface. You will see the four horses along with their current odds and any bets that have already been placed this round.
  </Step>

  <Step title="Choose your horse and bet amount">
    Click the horse you want to back and enter your bet amount. You can only bet on one horse per race. Once your bet is confirmed, your funds are deducted immediately.
  </Step>

  <Step title="Wait for the countdown">
    The 30-second countdown starts when the **first bet** of the round is placed. Countdown updates are broadcast to all players who have placed bets at every 10-second mark and during the final 5 seconds.
  </Step>

  <Step title="Race runs automatically">
    At zero, the race begins. The server plays horse gallop sounds for all bettors as the race progresses, then announces the winning horse.
  </Step>

  <Step title="Collect your winnings">
    If your horse wins, your payout is credited automatically: `bet amount × horse odds multiplier`. If your horse loses, your bet is forfeited.

    | Your horse | Result                                     |
    | ---------- | ------------------------------------------ |
    | Wins       | Receive `bet × multiplier` (tax may apply) |
    | Loses      | Bet is lost                                |
  </Step>
</Steps>

<Tip>
  Placing a bet on Cometa ☄ (10 % win chance, 10× payout) with $100,000 yields $1,000,000 if it wins. High-risk bets on this horse can be extremely rewarding — but they lose 9 out of 10 races on average.
</Tip>

## Commands

| Command     | Description                        |
| ----------- | ---------------------------------- |
| `/carreras` | Opens the horse racing betting GUI |

## Bet Limits

<CardGroup cols={3}>
  <Card title="Default Players" icon="user">
    **Min:** $100       **Max:** $100,000 per race
  </Card>

  <Card title="VIP Players" icon="star">
    **Max:** \$500,000\
    (`casinoliric.bet.vip` permission)
  </Card>

  <Card title="Admin Players" icon="shield">
    **Max:** \$10,000,000\
    (`casinoliric.bet.admin` permission)
  </Card>
</CardGroup>

## Daily Use Limits

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

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

<Note>
  Admins with `casinoliric.uses.admin` have unlimited daily bets. All limits are configurable under `racing.uses` and `racing.bet` in `config.yml`.
</Note>

## Configuration Reference

<CodeGroup>
  ```yaml Racing bet limits theme={null}
  racing:
    active: true
    bet:
      default:
        min: 100.0
        max: 100000.0
      ranks:
        vip:
          permission: "casinoliric.bet.vip"
          max: 500000.0
        admin:
          permission: "casinoliric.bet.admin"
          max: 10000000.0
    uses:
      default:
        max-uses-per-day: 5
      ranks:
        vip:
          permission: "casinoliric.uses.vip"
          max-uses-per-day: 20
        admin:
          permission: "casinoliric.uses.admin"
          max-uses-per-day: -1
  ```

  ```kotlin Default horse definitions (RaceManager.kt) theme={null}
  private var defaultHorses = listOf(
      Horse(1, "Relámpago", "⚡", 2.0,  40),
      Horse(2, "Sombra",    "🌑", 3.0,  30),
      Horse(3, "Tornado",   "🌪", 5.0,  20),
      Horse(4, "Cometa",    "☄",  10.0, 10)
  )
  ```
</CodeGroup>

<Warning>
  Only one bet per player is allowed per race. If you try to place a second bet while a race countdown is active, the plugin will reject it. Wait for the current race to finish before betting again.
</Warning>