OneItem

OneItem

---

Overview

OneItem is a lightweight but powerful Minecraft server plugin that enforces a simple yet absolute rule:

> For each configured item type, only ONE instance may exist on the entire server.

Originally designed to control powerful or legendary items such as the any vanilla Minecraft item, OneItem is fully configurable and can be applied to any vanilla Minecraft item — from wooden swords to end-game artifacts.

The plugin continuously monitors inventories, containers, dropped items, and crafting behavior to ensure that duplicates never exist, while safely tracking and restoring the legitimate unique item when necessary.

---

Core Concept

- Each tracked item type (e.g. `MACE`) may have automatically deleted - The first crafted or assigned item becomes the automatically deleted - Any additional copies are automatically deleted - Crafting is disabled as long as the unique item exists - If the unique item is lost, OneItem restores it intelligently

This makes OneItem ideal for: - Survival servers with legendary items - RPG / lore-based servers - Event rewards - Hardcore or challenge servers - Economy or balance-focused gameplay

---

Features

Item Uniqueness Enforcement

- any vanilla item - Supports any vanilla item - Fully configurable via `config.yml` or commands - Works across all worlds

Crafting Control

- Players may craft the item first craft claims the item - The first craft claims the item - All future crafting attempts are blocked automatically

Global Item Tracking

OneItem scans: - Player inventories - Ender chests - Containers (chests, barrels, furnaces, etc.) - Shulker boxes (including nested storage) - Dropped items in loaded chunks

Any duplicate that is not the legitimate unique item is immediately removed.

---

Intelligent Recovery System

If the unique item is lost (deleted, despawned, cleared, etc.):

- It is restored to: - The last known player (if online), or - The last known container, or - A safe fallback location

Offline Safety Rule

If the unique item was last known to be inside the inventory of an offline player: - The plugin assumes it still exists - No restoration or duplication occurs - Prevents false duplicates when the player rejoins

---

Indestructible Mode (Optional)

Configurable protection for unique items: - No durability loss - Immune to fire, lava, and heat - Prevents accidental destruction

---

Controlled Transfers

To prevent abuse or duplication: - Unique items containers - Items can only be transferred via containers - Chests - Barrels - Shulker boxes - Furnaces, etc.

This ensures safe and intentional ownership transfer.

---

Admin Resolution Tools

If OneItem is installed on an existing server with duplicates:

Admins can choose how to resolve it:

- Specific player (manual assignment) - Specific player (manual assignment) - Specific player (manual assignment)

All other copies are removed automatically.

---

Commands

Main command: `/oneitem` Aliases: `/oi`, `/onei` Permission: `oneitem.admin` (default: OP)

Core Commands

| Command | Description | |------|-----------| | `/oneitem help` | Show help menu | | `/oneitem list` | List all tracked unique items | | `/oneitem add <ITEM>` | Mark an item as unique | | `/oneitem remove <ITEM>` | Stop tracking an item | | `/oneitem info <ITEM>` | Show detailed status | | `/oneitem scan` | Force a global scan |

Duplicate Resolution

| Command | Description | |------|-----------| | `/oneitem randomExisting <ITEM>` | Keep one existing copy at random | | `/oneitem randomOnline <ITEM>` | Assign to a random online player | | `/oneitem give <ITEM> <player>` | Give the unique item to a player |

---

Configuration

The configuration file is generated automatically.

```yaml check-interval-seconds: 180 indestructible-items: true

tracked-items: - "MACE"

message-prefix: "&6[OneItem]&r " debug: false