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 Mace, 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 only one legitimate instance
• The first crafted or assigned item becomes the unique item
• 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

• One item per type, server-wide
• Supports any vanilla item
• Fully configurable via config.yml or commands
• Works across all worlds

Crafting Control

• Players may craft the item only if no unique instance exists
• 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 cannot be dropped
• 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:

• Random existing owner
• Random online player
• 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.

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

tracked-items:
  - "MACE"

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