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

# Overview

Coinflips for Paper 1.21+. A player bets an amount of a currency, another player matches it, and a coin decides who takes the pot. The flip is shown as a small **3D scene** in front of both players (mini versions of them sit on seats while a coin with both their faces flips between them), or as a flip menu. Bets are held from the moment they are placed, every change is stored, and nothing is lost on a crash, a restart or a logout.

EdCoinflip runs on its own. Vault, PlayerPoints, PinnaPrison, EdPrison, EdTools, EdDungeons, PlaceholderAPI and EdLang are all optional.

## Features

|                   |                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Any currency**  | Vault, PlayerPoints, PinnaPrison, EdPrison, EdTools (EdGens) and EdDungeons currencies, as many as you like at once                                     |
| **Per currency**  | Name, symbol, colour, icon, decimals, full or short amounts, min / max bet, tax, broadcast amount, permission                                           |
| **3D flip**       | Packet-only scene with the players' skins, a coin with both faces, sounds and particles; every size, timing, colour, text and particle is in config.yml |
| **Flip menu**     | For Bedrock players, or for everyone with `animation.style: MENU`                                                                                       |
| **Menus**         | List with pages, confirm menu, flip menu; PinnaPrison menu format (a file can be copied between both plugins)                                           |
| **Safe bets**     | Bets held in escrow, check-and-take withdrawals, wins stored before they are paid, refunds for expired coinflips, offline players paid on join          |
| **Storage**       | `data.yml` or MySQL / MariaDB (several servers can share it), `/cf migrate` between them                                                                |
| **Limits**        | Open coinflips per player, raised by `edcoinflip.max-open.<n>` permissions; per-currency permissions                                                    |
| **Big numbers**   | Exact amounts up to 10^36, short input (`1.5k`, `2m`, `1,000`), configurable suffixes and separators                                                    |
| **Placeholders**  | `%edcoinflip_...%` for scoreboards and holograms                                                                                                        |
| **Developer API** | Static API and four events (create, join, result, cancel)                                                                                               |
| **Languages**     | Every text in messages.yml / the menus; optional per-player languages through EdLang                                                                    |

## Requirements

* Paper (or a fork) 1.21 or newer, Java 21.
* At least one currency plugin: Vault with an economy plugin (EssentialsX, CMI...), PlayerPoints, PinnaPrison, EdPrison, EdTools or EdDungeons.
* Optional: PlaceholderAPI (placeholders in menus and the `%edcoinflip_...%` placeholders).

## Quick start

1. Put `EdCoinflip.jar` in `plugins/` and restart.
2. Out of the box players bet Vault money: `/cf 1000` creates a coinflip, `/cf` opens the list.
3. Add or turn on currencies in `config.yml` → `currencies` (see [Currencies](/p/edcoinflip/getting-started/currencies.md)), then `/cf reload`.
4. Change texts in `messages.yml`, menus in `guis/`, the 3D scene in `config.yml` → `animation.scene`.

## Folder

```
plugins/EdCoinflip/
  config.yml      tax, limits, currencies, number format, storage, the flip animation
  messages.yml    every chat message
  guis/           coinflip.yml (list), coinflip-confirm.yml, coinflip-animation.yml (flip menu)
  data.yml        open coinflips and unpaid payouts (storage.type yaml)
```