SimpleItemsPerms

The Ultimate Permission System for Minecraft Items

---

📖 What This Plugin Does

SimpleItemsPerms allows you to assign specific permissions to individual items in your Minecraft server. When you give an item a permission requirement, only players with that permission can use it - everyone else will be blocked with a customizable message.

Example: Create a Diamond Sword that requires simpleitemsperms.vip permission. Players without VIP rank cannot attack with it, equip it, or even pick it up. Perfect for exclusive donor rewards!

---

🎯 Why Download This Plugin?

Perfect for servers with:

• VIP/Donor Perks - Give exclusive items to paying supporters
• Rank Progression - Lock powerful items behind rank requirements
• Custom Kits - Create Elite, MVIP, or Admin-only kit items
• Economy Shops - Sell premium items that require special permissions
• Event Rewards - Give special items that only event winners can use

Key advantages:

• ⚡ Easy to use - Intuitive GUI, no complex commands
• 🌍 Fully translated - English and Italian included, add your own language
• 🔒 Persistent - Permissions survive server restarts and world changes
• 🎨 Customizable - Configure every message, sound, and behavior
• 📊 Professional - Item registry, statistics tracking, and management tools

---

⚠️ Important Information Before Downloading

Requirements:

• ✅ Server-side only plugin - Does NOT work on client, must be installed on server
• ✅ Permission plugin required - You need LuckPerms, PermissionsEx, or similar
• ✅ Minecraft 1.21+ - Compatible with Spigot, Paper, Purpur, Pufferfish
• ✅ Java 21+ - Required for modern Minecraft versions

Limitations:

• ⚠️ Placed blocks lose permissions - When you place a block, Minecraft removes all NBT data (this affects ALL plugins, not just ours). Permissions work perfectly for weapons, armor, tools, food, and potions.

How it works:

1. Permissions are stored in item NBT data (PersistentDataContainer)
2. The plugin checks permissions on 8+ different events (use, equip, consume, etc.)
3. Players without permission see a customizable lore message on the item
4. Admins can manage all registered items through an easy GUI

---

🌟 Key Features

🔐 Advanced Permission System

• Item-Specific Permissions - Assign unique permissions to any item
• Automatic Permission Checks - Players without permission cannot use restricted items
• Visual Feedback - Custom lore shows permission status
• Dynamic Lore - Hide permission lore from players who have the permission
• Persistent Storage - Permissions stored in item NBT data (survives server restarts)

🎨 Intuitive GUI System

• Easy-to-Use Interface - Assign permissions through a beautiful GUI
• Drag & Drop - Simply place items in the GUI to assign permissions
• Visual Confirmation - Green confirm and red cancel buttons
• Fully Customizable - Configure GUI size, materials, and colors
• Real-Time Updates - See changes immediately

🌍 Multi-Language Support

• Bilingual System - Full English and Italian translations
• Language Files - Easy to translate to any language
• Dynamic Switching - Change language with /sip reload
• Fully Translated - GUI, commands, messages, and lore
• No Hardcoded Strings - Everything is translatable

📊 Item Registry & Management

• Global Item Registry - Track all items with permissions
• Detailed Information - View item details, creator, and usage statistics
• Browse Interface - Paginated list of all registered items
• Item Details GUI - See enchantments, lore, and metadata
• Easy Deletion - Remove items from registry with one click

🛡️ Comprehensive Event Blocking

• Use Items - Block right/left click usage
• Equip Armor - Prevent wearing restricted armor
• Consume Items - Block eating/drinking
• Drop/Pickup - Control item transfer
• Move Inventory - Prevent inventory manipulation
• Break/Place Blocks - Control block interactions
• Attack Entities - Restrict combat usage
• Shoot Projectiles - Block bow/crossbow usage

⚙️ Advanced Configuration

• Customizable Lore - Define permission denial message
• Lore Position - Choose start or end position
• Sound Effects - Custom sounds when actions are blocked
• Event Toggle - Enable/disable specific event checks
• Debug Mode - Detailed logging for troubleshooting

📈 bStats Integration

• Anonymous Statistics - Help improve the plugin
• Custom Charts - Track total items with permissions
• Embedded System - No conflicts with other plugins
• Privacy Focused - Fully compliant with privacy standards

---

📋 Commands

Command	Description	Permission
/sip gui	Open the GUI to assign permissions to items	simpleitemsperms.admin
/sip give <player> <permission>	Give the item in your hand with a permission to a player	simpleitemsperms.admin
/sip remove	Remove the permission from the item in your hand	simpleitemsperms.admin
/sip check	Check if the item in your hand has a permission	simpleitemsperms.admin
/sip list	Open the GUI to browse all registered items	simpleitemsperms.admin
/sip reload	Reload the configuration and language files	simpleitemsperms.admin
/sip info	Display plugin information and commands	simpleitemsperms.admin

Command Aliases: /simpleitemsperms, /itemsperms

---

🔑 Permissions

Permission Node	Description	Default
simpleitemsperms.admin	Access to all plugin commands and features	OP only
simpleitemsperms.<custom>	Permission required to use items assigned with <custom>	False

📝 Permission Examples

# Grant a player access to VIP items
/lp user PlayerName permission set simpleitemsperms.vip true

# Grant a group access to Elite items
/lp group elite permission set simpleitemsperms.elite true

# Multiple permission levels
simpleitemsperms.vip       - Basic VIP items
simpleitemsperms.mvip      - More VIP items
simpleitemsperms.elite     - Elite exclusive items
simpleitemsperms.admin     - Admin-only items

---

🎓 How to Use

Method 1: Using the GUI (Recommended)

1. Run command: /sip gui
2. Place items you want to restrict in the GUI
3. Click the green CONFIRM button
4. Type the permission name in chat (e.g., vip)
5. Done! Items now require permission simpleitemsperms.vip

Method 2: Using Commands

1. Hold the item in your hand
2. Run: /sip give <player> <permission>
3. The item will be given to the player with the permission requirement

💡 Pro Tips

• Use descriptive permission names like vip, mvip, elite
• Group related items with the same permission
• Set hide-for-permitted-players: true to hide lore from players who can use the item
• Use /sip list to manage all your restricted items
• Check /sip check to verify item permissions

---

⚙️ Configuration

Click to view config.yml

# ╔═══════════════════════════════════════════════════════════════╗
# ║              SimpleItemsPerms - Configuration                 ║
# ║          Developed with ❤ by AlessioGTAII                    ║
# ╚═══════════════════════════════════════════════════════════════╝

# Language / Lingua
# Supported languages: en_US (English), it_IT (Italiano)
language: "en_US"

# Message prefix
prefix: "&8[&6SimpleItemsPerms&8]&r"

# GUI Configuration
gui:
  title: "&6Assign Permission to Items"
  size: 54
  
  confirm-button:
    slot: 49
    material: LIME_CONCRETE
    name: "&a&lCONFIRM"
    lore:
      - "&7Click to confirm"
      - "&7permission assignment"
  
  cancel-button:
    slot: 53
    material: RED_CONCRETE
    name: "&c&lCANCEL"
    lore:
      - "&7Click to cancel"
      - "&7and close the GUI"

# Lore Configuration
lore:
  hide-for-permitted-players: true
  position: "end"

# Events to block for players without permission
blocked-events:
  use-item: true
  equip-armor: true
  consume: true
  drop: false
  pickup: true
  move-inventory: true
  break-block: true
  place-block: true
  attack: true
  shoot-bow: true

# Sound played when an action is blocked
block-sound:
  enabled: true
  sound: "ENTITY_VILLAGER_NO"
  volume: 1.0
  pitch: 1.0

# Debug system
debug: false

🌍 Language Files

Language files are located in plugins/SimpleItemsPerms/lang/

• messages_en_US.yml - English translations
• messages_it_IT.yml - Italian translations

Want to add your language? Copy an existing file, translate it, and send it to us!

---

❓ FAQ

How do I create VIP-only items?

1. Run /sip gui
2. Place your VIP items in the GUI
3. Click confirm and type vip
4. Give your VIP players the permission: simpleitemsperms.vip
5. Only players with this permission can use those items!

What happens if a player without permission tries to use a restricted item?

The action will be blocked and the player will receive a message explaining they need the permission. A sound effect will play (configurable) to give clear feedback.

Can I use this with LuckPerms/PermissionsEx?

Yes! SimpleItemsPerms works with any permission plugin that implements the Bukkit/Spigot permission system.

Does this work with custom items from other plugins?

Yes! SimpleItemsPerms works with:

• Vanilla Minecraft items
• Custom items from ItemsAdder, Oraxen, etc.
• Items with custom names/lore
• Enchanted items
• Items with custom NBT data

If I change the language, do existing items update?

No. The lore is saved when you create the item. Only new items will have the new language. However, permissions always work regardless of lore language.

Do permissions persist after server restarts?

Yes! Permissions are stored in the item's NBT data and will survive:

• Server restarts
• Plugin reloads
• World changes
• Item trades between players

What about placeable blocks?

When you place a block, Minecraft removes all NBT data. This is normal behavior affecting all plugins.

Perfect for: Weapons, armor, tools, food, potions
Not recommended for: Placeable blocks

---

🔧 Compatibility

✅ Tested & Compatible:

• Minecraft: 1.21, 1.21.1, 1.21.3+
• Server: Spigot, Paper, Purpur, Pufferfish
• Java: 21+
• Permissions: LuckPerms, PermissionsEx, GroupManager
• Custom Items: ItemsAdder, Oraxen, MMOItems
• Kits: EssentialsX, KitsPvP, AdvancedKits

⚠️ Known Issues:

• None currently reported!

---

💾 Installation

📥 Installation Steps:

1. Download SimpleItemsPerms-1.1.0.jar
2. Place in your plugins/ folder
3. Restart your server
4. Configure plugins/SimpleItemsPerms/config.yml (optional)
5. Use /sip gui to get started!

⚠️ Requirements:

• Minecraft 1.21+ server (Spigot/Paper)
• Java 21 or higher
• Permission plugin (LuckPerms recommended)

---

📝 License

This plugin is released under the MIT License.

---