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

# CoinFlip: Create PvP Bets and Win the Animated Coin Flip

> Challenge other players to a CoinFlip PvP bet, browse open games in the GUI lobby, and watch an animated coin decide who takes the full pot.

CoinFlip is a pure player-versus-player game that requires no physical setup in your world. One player creates a bet, the server broadcasts the challenge to everyone online, and another player accepts through the shared GUI lobby. An animated coin flip then determines the winner, who immediately receives the entire pot. It is the fastest way to wager on LiricCasino — open the menu, name your price, and wait for a challenger.

## Opening the CoinFlip Lobby

Run either alias to open the GUI:

```
/coinflip
```

```
/cf
```

The lobby GUI shows all currently open bets waiting for an opponent. Each entry displays the creator's name, the wagered amount, and a button to join.

***

## Creating a Bet

<Steps>
  <Step title="Open the lobby">
    Run `/coinflip` or `/cf` to open the GUI.
  </Step>

  <Step title="Click 'Create a Bet'">
    Select the create option in the GUI. A bet-amount selection screen opens.
  </Step>

  <Step title="Choose your wager">
    Pick from the preset amounts or enter a custom value. The amount must be within your rank's configured minimum and maximum.

    | Rank                            | Min Bet | Max Bet    |
    | ------------------------------- | ------- | ---------- |
    | Default                         | 100     | 500,000    |
    | VIP (`casinoliric.bet.vip`)     | 100     | 1,000,000  |
    | Admin (`casinoliric.bet.admin`) | 100     | 10,000,000 |
  </Step>

  <Step title="Confirm the bet">
    Your wager is withdrawn from your balance immediately. A server-wide broadcast announces your open challenge, so all online players see the bet and can rush to join.
  </Step>
</Steps>

<Note>
  Your bet stays open in the lobby until another player joins it or you cancel it. If the server restarts while your bet is open, the wagered funds are returned to your balance.
</Note>

***

## Joining a Bet

<Steps>
  <Step title="Open the lobby">
    Run `/coinflip` or `/cf`. All open bets from other players appear as clickable items.
  </Step>

  <Step title="Find a bet to join">
    Browse the list. Each entry shows the challenger's name and wager amount.
  </Step>

  <Step title="Click to join">
    Clicking a bet entry deducts the matching wager from your balance and starts the coin flip animation immediately.
  </Step>
</Steps>

<Warning>
  You cannot join your own bet. If you attempt to interact with a bet you created, the GUI will ignore the click.
</Warning>

***

## The Coin Flip Animation

Once two players are matched, the animated coin flip begins. The animation runs for approximately **60 ticks (\~3 seconds)** — configurable via `animation-ticks` in `config.yml`. Both players see the outcome at the same moment:

* **Winner**: receives the full combined pot (both players' wagers).
* **Loser**: no payout; their wager was already deducted when they joined or created the game.

A server-wide broadcast announces the result with both player names and the winning amount, so the whole server knows who won.

***

## Server-Wide Broadcasts

CoinFlip sends two server-wide messages per game:

| Event         | Broadcast Sent                                       |
| ------------- | ---------------------------------------------------- |
| Bet created   | A challenge is open — shows creator and wager amount |
| Game resolved | Winner announced — shows both players and the pot    |

This keeps the server community engaged and encourages others to jump in and create their own bets.

***

## Configuration Reference

```yaml theme={null}
coinflip:
  active: true
  animation-ticks: 60   # ~3 seconds at 20 tps
  bet:
    default:
      min: 100.0
      max: 500000.0
    ranks:
      vip:
        permission: "casinoliric.bet.vip"
        max: 1000000.0
      admin:
        permission: "casinoliric.bet.admin"
        max: 10000000.0
  uses:
    default:
      max-uses-per-day: 15
    ranks:
      vip:
        permission: "casinoliric.uses.vip"
        max-uses-per-day: 50
      admin:
        permission: "casinoliric.uses.admin"
        max-uses-per-day: -1   # -1 = unlimited
```

<Tip>
  Increase `animation-ticks` for a more dramatic flip, or decrease it for a snappier result. At 20 ticks per second, a value of `40` gives a 2-second animation and `100` gives a 5-second animation.
</Tip>

***

## Tax Integration

Apply a tax rate to CoinFlip winnings when the global tax system is enabled:

```yaml theme={null}
taxes:
  enabled: true
  coinflip: 0.05   # 5 % deducted from the winner's payout
```

The tax is deducted from the **gross payout** (the full pot) before the winner's balance is credited.

***

## No Physical Setup Required

Unlike Slots, Roulette, Blackjack, and Poker, CoinFlip has no world entity to place or manage. The game is entirely GUI-driven and accessible from anywhere on the server via the `/coinflip` command. You do not need admin permissions to create or join a bet — only the standard play permission is required.

<Note>
  To disable CoinFlip without removing any entities, set `coinflip.active: false` in `config.yml` and reload. The `/coinflip` command will produce no response until the game is re-enabled.
</Note>

***

## Command Reference

| Command     | Alias | Description                 |
| ----------- | ----- | --------------------------- |
| `/coinflip` | `/cf` | Open the CoinFlip lobby GUI |