> For the complete documentation index, see [llms.txt](https://xpressdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xpressdev.gitbook.io/docs/mods/bbottlecaps.md).

# BBottleCaps

Adds Pokémon Bottle Caps to Cobblemon - consumable items that hyper-train a Pokémon's IVs after it's already been caught, instead of forcing you to re-roll for perfect stats.

***

## Features

* **Ten cap types** - five base caps (Rusted, Silver, Gold, Funky, Blank) plus a Legendary variant of each
* **Full IV control** - zero an IV, max it, lower it by one, or revert Hyper Training entirely
* **Level requirement and species blacklist** for eligibility
* **Configurable legendary rule** - choose whether regular caps can affect legendary, mythical or Ultra Beast Pokémon
* **Per-cap item and custom model data**, for resource-pack reskinning of every cap type independently
* **Automatic migration** of legacy per-cap config keys (`goldCapItem`, `legendaryCapItem`, etc.) to the current format

***

## How Bottle Caps work

Hold a cap and use it (right-click) on your own Pokémon - the caught, owned one, not a wild spawn. Sneaking or off-hand use is ignored. Gold Bottle Caps apply immediately; every other cap opens a GUI so you can pick which of the six IVs (HP, Attack, Defence, Sp. Attack, Sp. Defence, Speed) to affect.

### Cap types

| Cap        | Effect                                                                                 | Needs a stat pick? |
| ---------- | -------------------------------------------------------------------------------------- | ------------------ |
| **Rusted** | Sets the chosen IV to 0.                                                               | Yes                |
| **Silver** | Sets the chosen IV to 31 (max).                                                        | Yes                |
| **Gold**   | Sets *all six* IVs to 31.                                                              | No                 |
| **Funky**  | Lowers the chosen IV by 1.                                                             | Yes                |
| **Blank**  | Removes Hyper Training from the chosen IV, reverting it to the Pokémon's natural roll. | Yes                |

Each of these five also has a **Legendary** variant (Legendary Rusted, Legendary Silver, etc.) that works only on legendary, mythical, or Ultra Beast Pokémon - the regular versions won't touch them unless `regularCapsApplyToLegendary` allows it.

Every cap is consumed (one item) on a successful use.

### Eligibility

A cap can be denied for several reasons:

* The Pokémon's species is blacklisted.
* The Pokémon is below the required level (default 50).
* A Legendary-only cap used on a non-legendary Pokémon, or vice versa.
* The targeted IV is already at the value the cap would set it to (e.g. a Silver cap on a stat that's already 31).
* A Blank cap used on a stat that was never Hyper Trained.
* A Gold cap used on a Pokémon whose IVs are all already 31.

Each denial sends the player a specific message.

***

## Commands

All commands live under `/bbcaps`.

| Command                                 | What it does                                                                    | Permission      |
| --------------------------------------- | ------------------------------------------------------------------------------- | --------------- |
| `/bbcaps give <player> <type> <amount>` | Gives a player bottle caps of the given type (e.g. `gold`, `legendary_silver`). | `bbcaps.give`   |
| `/bbcaps reload`                        | Reloads `bcaps_config.json` and `lang.json`.                                    | `bbcaps.reload` |

Both commands default to operators (permission level 2); granting the LuckPerms node to a group lets non-ops use them too.

***

## Configuration

Config files live in `config/BBottleCaps/`, created on first run:

| File                | Purpose                                                                   |
| ------------------- | ------------------------------------------------------------------------- |
| `bcaps_config.json` | Level requirement, legendary rules, blacklist, and per-cap item settings. |
| `lang.json`         | Every player-facing message.                                              |

Edit a file and run `/bbcaps reload`, or restart the server, to apply changes.

### `bcaps_config.json`

| Key                           | Default     | Description                                                                   |
| ----------------------------- | ----------- | ----------------------------------------------------------------------------- |
| `levelRequired`               | `50`        | Minimum Pokémon level a cap can be used on.                                   |
| `regularCapsApplyToLegendary` | `true`      | Whether non-Legendary caps can affect legendary/mythical/Ultra Beast Pokémon. |
| `blacklistedSpecies`          | `[]`        | Species that can never be Hyper Trained, e.g. `["ditto"]`.                    |
| `caps`                        | (see below) | Per-cap item and custom model data overrides.                                 |

### Customizing cap items

Each of the ten cap types can be given its own base item and custom model data, letting you use a resource pack to give each cap a distinct look:

```json
"caps": {
  "gold": {
    "item": "minecraft:popped_chorus_fruit",
    "customModelData": 869
  }
}
```

All caps default to `minecraft:popped_chorus_fruit` with a different `customModelData` per type. An unrecognized item ID falls back to the default, with a warning in the server log.

{% hint style="success" %}
Configs from older versions load fine - legacy per-cap keys like `goldCapItem` and `legendaryCapItem` are read automatically and rewritten into the current format.
{% endhint %}

***

## Messages

Every message players see is in `lang.json` and uses [MiniMessage](https://docs.advntr.dev/minimessage/format.html) formatting.

| Key                            | When it's shown                                          |
| ------------------------------ | -------------------------------------------------------- |
| `error.already_maxed_out_stat` | Silver/Gold cap on a stat already at 31.                 |
| `error.already_minimized_stat` | Rusted/Funky cap on a stat already at 0.                 |
| `error.insufficient_level`     | The Pokémon is below `levelRequired`.                    |
| `error.already_maxed_ivs`      | Gold cap on a Pokémon with all IVs already 31.           |
| `error.not_regular_pokemon`    | A Legendary-only cap on a non-legendary Pokémon.         |
| `error.not_legendary_pokemon`  | A regular cap on a legendary Pokémon, blocked by config. |
| `error.no_bottle_cap`          | You're no longer holding the cap you started with.       |
| `error.stat_not_hyper_trained` | Blank cap on a stat that was never trained.              |
| `error.species_blacklisted`    | The Pokémon's species is blacklisted.                    |
| `success.maxed_ivs`            | A Gold cap maxed all IVs.                                |
| `success.bottle_capped`        | A cap changed a single stat.                             |
| `success.training_cleared`     | A Blank cap removed Hyper Training from a stat.          |

Available tokens, depending on the message: `{level}`, `{stat}`.

***

## Requirements

* Minecraft 1.21.1 (Fabric)
* Cobblemon 1.8.0+
* Fabric API + Fabric Language Kotlin
* LuckPerms (optional, for permission nodes beyond operator)