ItemTag

Track item ownership and history on your Paper Minecraft server. Automatically tag items with owner information, record transfers, and query ownership history through Skript.

Features

• Automatic ownership tracking - Tags items when created, dropped, or transferred
• Event logging - Records ORIGINAL, STOLEN, GIFTED, RETURNED, and LOOTED events with timestamps
• Multiple storage backends - Base64-encoded NBT storage with SQLite fallback for reliability
• Configurable tracking - Track specific materials or entire categories (tools, weapons, armor)
• Ownership queries - Check current/original owner, transfer counts, and theft status
• Skript integration - Full API access via Skript conditions and expressions

Installation

Requirements:

• Java 21 or higher
• Paper 1.21.11 or later
• Skript 2.12.1+ (optional, for Skript integration)

1. Download the latest JAR from Releases
2. Place itemtaghistory-1.0.jar in your plugins/ folder
3. Restart your server
4. Edit plugins/ItemTag/config.yml as needed
5. Restart again to apply configuration changes

Configuration

Edit plugins/ItemTag/config.yml to customize tracking behavior:

# Items to track (specific materials or categories: TOOLS, WEAPONS, ARMOR)
tracked-items:
  - DIAMOND_HELMET
  - DIAMOND_CHESTPLATE
  - DIAMOND_LEGGINGS
  - DIAMOND_BOOTS
  - TOOLS
  - WEAPONS
  - ARMOR

# Time window after drop to consider item as "gifted" (seconds)
gift-window-seconds: 45

# Timestamp format for item lore
timestamp-format: "yyyy-MM-dd HH:mm:ss"

# Customize lore lines for each event type
history-title: "&6Item History"

original-1: "&6[Original Owner]"
original-2: "&7%owner%"

stolen-1: "&c[Stolen]"
stolen-2: "&7From %pastowner%"

gifted-1: "&a[Gifted]" gifted-2: "&7From %owner%"

returned-1: "&b[Returned]" returned-2: "&7To %pastowner%"

looted-1: "&e[Looted]" looted-2: "&7From %pastowner%"

**Placeholders:** `%owner%`, `%pastowner%`, `%timestamp%`

## Skript Integration

### Conditions

```skript
%itemstack% belongs to %offlineplayer%
%itemstack% has [itemtag] history
%itemstack% is [itemtag] tracked
%itemstack% was [itemtag] stolen
%itemstack% is [itemtag] ignored
%itemstack% has been owned by %offlineplayer%

Expressions

owner of %itemstack%
history of %itemstack%
original owner of %itemstack%
ownership transfer count of %itemstack%
formatted history of %itemstack%

API Usage

Access the plugin API from your code:

ItemTagApi api = ((ItemTag) Bukkit.getPluginManager().getPlugin("itemtaghistory")).getApi();

api.belongsToPlayer(playerUuid, itemStack);           // Check if player owns item
api.getHistory(itemStack);                            // Get all history entries
api.getCurrentOwner(itemStack);                       // Get current owner UUID
api.getOriginalOwner(itemStack);                      // Get original owner UUID
api.isTracked(itemStack);                             // Check if item is tracked
api.hasHistory(itemStack);                            // Check if item has history
api.hasBeenOwned(itemStack);                          // Check if item ever owned
api.wasStolen(itemStack);                             // Check if item was stolen
api.getOwnershipTransferCount(itemStack);             // Count ownership transfers
api.getFormattedHistory(itemStack);                   // Get formatted history strings
api.markEvent(itemStack, type, owner, pastOwner);     // Record a history event
api.clearHistory(itemStack);                          // Clear all history
api.addIgnoredItem(itemStack);                        // Mark item as ignored
api.removeIgnoredItem(itemStack);                     // Unignore item
api.isIgnoredItem(itemStack);                         // Check if item ignored
api.listIgnoredItems(player);                         // Get ignored items in inventory