## Trim Discovery

The first player to open a naturally generated chest containing a tracked armor trim becomes the discoverer of that trim. The trim is removed from the chest and placed directly into the player's inventory. If their inventory is full, the trim is dropped at their feet. A server-wide broadcast announces the discovery.

If a chest contains a trim that has already been discovered and is exclusive, the trim is silently removed from the chest regardless of who opens it. No one receives it.

If a trim has been released to the public, it remains in the chest and can be taken by anyone.

Trims that are not yet discovered are given to the first player who opens a chest containing one. Only one player can ever be the discoverer of each trim.

---

## Exclusive by Default

Every trim is exclusive the moment it is discovered. No configuration or command is needed. The discoverer is the only player who can hold, find, or duplicate that trim until they choose to release it or share it.

---

## Allowed Players (25-Second Drop Transfer)

If the discoverer of an exclusive trim drops it on the ground and another player picks it up within 25 seconds, that player permanently becomes an allowed player for that trim.

Allowed players have the same access as the discoverer. They can pick up the trim from the ground, find it in naturally generated chests, and duplicate it at a crafting table.

If a non-allowed player attempts to pick up an exclusive trim from the ground outside the 25-second window, the pickup is blocked and the item is removed.

Both the discoverer and all allowed players are saved permanently and persist across server restarts.

---

## Releasing a Trim

The `/ott release <trim>` command allows the discoverer to release an exclusive trim to the public. Once released, all players on the server can find, pick up, and duplicate that trim normally.

The release command is disabled by default. It must be enabled in `config.yml` by setting `release-command-enabled` to `true`. When disabled, any player who runs the command receives the message: **This Command Is Disabled!**

When enabled, the command has two requirements:

- The player must be the discoverer of the specified trim.

- The player must have the specified trim in their inventory.

If either requirement is not met, the command fails with an appropriate message.

A server-wide broadcast announces when a trim is released.

---

## Keeping a Trim Exclusive

The `/ott keep <trim>` command allows the discoverer to set a previously released trim back to exclusive. Once set back to exclusive, no other players (except allowed players) can find, pick up, or duplicate that trim.

Only the discoverer can use this command. If the trim is already exclusive, the player is informed and no change occurs.

A server-wide broadcast announces when a trim is made exclusive again.

---

## Player-Placed Containers

Containers placed by players (chests, barrels, shulker boxes, and any other container block) are never affected by this plugin. Trims stored inside player-placed containers are left completely alone. Players can safely store their trims in any container they place.

Only naturally generated containers (found in structures, dungeons, temples, etc.) have trims removed or managed by the plugin.

Double chests are fully supported. Both sides of a double chest are checked when determining whether it was player-placed.

---

## Loot Generation

Exclusive trims are removed from loot tables during generation. This prevents exclusive trims from appearing in any newly generated loot anywhere in the world.

Public and undiscovered trims are unaffected and generate in loot normally.

---

## Crafting and Duplication

Vanilla trim duplication at a crafting table is blocked for exclusive trims. Only the discoverer and allowed players can duplicate an exclusive trim.

If a non-allowed player attempts to duplicate an exclusive trim, the crafting result is removed and they receive a message stating who owns the trim.

Public trims can be duplicated by anyone at a crafting table as normal.

---

## Server Broadcasts

A server-wide broadcast is sent when:

- A player discovers a trim for the first time.

- A player makes a trim exclusive again using `/ott keep`.

- A player releases a trim to the public using `/ott release`.

---

## Commands

All commands can be run using `/onetimetrims` or the alias `/ott`.

| Command | Description |

|---|---|

| `/ott` | Displays the help menu with all available commands. |

| `/ott reload` | Reloads the configuration file and data file. Requires the `onetimetrims.admin` permission. |

| `/ott status` | Displays a list of all tracked trims with their current status, discoverer name, and count of allowed players. Also shows totals for undiscovered, exclusive, and public trims. |

| `/ott status <trim>` | Displays detailed information for a specific trim including status, discoverer name, and all allowed player names. |

| `/ott keep <trim>` | Sets a previously released trim back to exclusive. Only the discoverer can use this. |

| `/ott release <trim>` | Releases an exclusive trim to the public. Only the discoverer can use this. Requires the trim to be in the player's inventory. Disabled by default in config. |

All subcommands and trim names support tab completion that filters as you type.

---

## Permissions

| Permission | Description | Default |

|---|---|---|

| `onetimetrims.admin` | Allows reloading the plugin configuration and data. | op |

| `onetimetrims.use` | Allows players to interact with the trim system, use keep, release, and status commands. | true (all players) |

---

## Configuration (config.yml)

Auto-created on first server start if missing.

### tracked-trims

A list of all armor trim keys the plugin tracks. All 18 vanilla armor trims are included by default:

coast, dune, eye, host, raiser, rib, sentry, shaper, silence, snout, spire, tide, vex, ward, wayfinder, wild, bolt, flow.

Remove a trim from this list to stop tracking it entirely. Untracked trims behave as normal vanilla trims.

### release-command-enabled

Controls whether the `/ott release` command can be used. Set to `false` by default. When set to `false`, any player who runs `/ott release` receives the message: **This Command Is Disabled!**

### messages

All player-facing messages are fully customizable and support `&` color codes. The following message keys are available:

| Key | When It Appears |

|---|---|

| `trim-discovered` | Sent to the player who discovers a trim for the first time. Supports `%trim%` placeholder. |

| `trim-kept` | Sent to the discoverer when they make a trim exclusive again. Supports `%trim%` placeholder. |

| `trim-released` | Sent to the discoverer when they release a trim to the public. Supports `%trim%` placeholder. |

| `trim-shared` | Sent to a player when they become an allowed player via the 25-second drop transfer. Supports `%trim%` placeholder. |

| `no-permission` | Sent when a player lacks the required permission. |

| `config-reloaded` | Sent after a successful configuration reload. |

| `trim-already-found` | Sent when a player encounters a trim that has already been discovered. Supports `%trim%` and `%player%` placeholders. |

| `release-disabled` | Sent when a player tries to use `/ott release` while it is disabled in config. |

| `not-discoverer` | Sent when a player tries to use `/ott keep` or `/ott release` on a trim they did not discover. |

| `must-have-trim` | Sent when a player tries to use `/ott release` without having the trim in their inventory. Supports `%trim%` placeholder. |

| `already-exclusive` | Sent when a player tries to use `/ott keep` on a trim that is already exclusive. Supports `%trim%` placeholder. |

| `already-public` | Sent when a player tries to use `/ott release` on a trim that is already public. Supports `%trim%` placeholder. |

---

## Data Storage (data.yml)

Auto-created on first server start if missing. Stores all persistent plugin data.

For each tracked trim, the following is saved:

- **Status** — UNDISCOVERED, EXCLUSIVE, or PUBLIC.

- **Discoverer UUID** — The UUID of the player who first found the trim.

- **Discoverer Name** — The username of the player who first found the trim.

- **Allowed Players** — A map of player UUIDs to player names for every player who gained access via the 25-second drop transfer.

Data is saved immediately whenever:

- A trim is discovered.

- A trim status changes (keep or release).

- An allowed player is added via the 25-second drop transfer.

- The plugin is disabled or the server shuts down.

---

## Trim Statuses

| Status | Meaning |

|---|---|

| UNDISCOVERED | No player has found this trim yet. It can appear normally in naturally generated chests. |

| EXCLUSIVE | A player has discovered this trim. It is removed from all naturally generated chests and loot generation. Only the discoverer and allowed players can pick it up, find it, and duplicate it. This is the default status after discovery. |

| PUBLIC | The discoverer released this trim. All players can find it in chests, pick it up, and duplicate it normally. |

OneTimeTrims999