[plugin] CuriosPaper

---

🧩 What is CuriosPaper?

CuriosPaper adds a complete accessory slot system to your Minecraft server. Players can equip rings, necklaces, capes, belts, charms, and more through a clean, tiered GUI — with full support for Java and Bedrock Edition players.

---

⚡ Features

🎒 Core Accessory System

• 💍 9 Slot Types — Head, Necklace, Back, Body, Belt, Hands, Bracelet, Ring, Charm
  
• ✨ Ability System — Potion effects & player attribute modifiers with custom operations
  
• ⚡ Quick Equip — Shift + Right-Click to instantly equip accessories from your hand
  
• 🎹 Hotkey System — Configurable sneak keybind to open the accessory GUI — no commands needed
  
• 🪂 Elytra Back Slot — Equip elytra in the back accessory slot (1.21.3+)
  
• ☠️ Death Behavior — Keep, drop, or auto-detect accessories on death — fully configurable
  
• 📱 Bedrock Support — Native Geyser & Floodgate support with custom Anvil & Smithing GUIs
  

🎨 3D Model System

Attach custom 3D models directly to the player's body when accessories are equipped. Models are rendered using synchronized invisible armor stands — visible to all nearby players.

• 🔄 Tracks player movement, rotation, sneaking, swimming, flying, and spectator mode
  
• 👁️ Smart visibility culling — hide models from wearer's first-person view or during flight/dismount
  
• 🔱 Trident & Elytra compatibility — models auto-hide during throws, riptide, and elytra flight
  
• 🧟 Mob models — mobs can visually wear items they'll drop
  
• 🎮 Per-item toggle — players can right-click to show/hide their models
  
• 🚪 GUI Dismount Protection — models temporarily dismount when opening inventories to prevent visual overlap
  

🛠️ In-Game GUI Editors

Create and configure everything visually — no manual YAML editing required:

• Item Editor — Set name, material, lore, model data, slot type
  
• Ability Editor — Configure potion effects & attribute modifiers with operations (ADD_NUMBER, ADD_SCALAR, MULTIPLY_SCALAR_1)
  
• Recipe Editor — Shaped, shapeless, furnace, blast, smoker, anvil & smithing recipes
  
• Loot Table Editor — Browse all server loot tables, add items to dungeon chests with presets
  
• Mob Drop Editor — Configure which mobs drop your items and at what chance
  
• Trade Editor — Set up villager trades with professions and price ranges
  
• 3D Model Editor — Configure body-mounted 3D models with pitch limits
  

📦 Item Distribution

• Crafting Recipes — 7 recipe types — shaped, shapeless, furnace, blast, smoker, anvil, smithing
  
• Loot Tables — Items appear in dungeon chests, mineshafts, temples, strongholds, and more
  
• Mob Drops — Any mob type can drop accessories with configurable chance & amount
  
• Villager Trades — Accessories appear in villager trade pools by profession and level
  
• Commands — /curios give <item> [​player] [​amount] for direct distribution
  

🔌 Developer API

A comprehensive API for other plugins to integrate with CuriosPaper:

[​code=java]
CuriosPaperAPI api = CuriosPaper.getInstance().getCuriosPaperAPI();

// Tag any item as an accessory
ItemStack ring = api.tagAccessoryItem(myItem, "ring");

// Check what a player is wearing
List<ItemStack> rings = api.getEquippedItems(player, "ring");
boolean hasRing = api.hasEquippedItems(player, "ring");
int count = api.countEquippedItems(player, "ring");

// Register slots, items, recipes, loot tables at runtime
api.registerSlot("earring", "Earring", "DIAMOND", 2);
api.registerItemLootTable("my_ring", new LootTableData("minecraft:chests/simple_dungeon", 0.25));
api.setItemModelConfig("my_cape", true, "LEATHER_HORSE_ARMOR", null, "myplugin:cape", 45f, 30f);

// Contribute resource pack assets from your plugin's JAR
api.registerResourcePackAssetsFromJar(myPlugin);
[​/code]

Custom Events:

• AccessoryEquipEvent — Player equips, unequips, or swaps an accessory
  
• CuriosLootGenerateEvent — Custom item generated in a loot container (cancellable)
  
• CuriosMobDropEvent — Custom item dropped by a mob (cancellable)
  
• CuriosRecipeTransferEvent — Custom item crafted via a recipe (data transfer)
  
• CuriosCraftEvent — Custom item created via craft/smelt/smith (final)
  
• CuriosModelEquipEvent — 3D model about to be displayed on player
  
• CuriosMobModelEquipEvent — 3D model about to be displayed on mob
  
• PlayerDeathCurioDropEvent — Fired on player death to filter/cancel curio drops
  

---

🎮 How It Works


1. /baubles → Opens the accessory menu
2. Click a slot icon → Opens that slot's inventory
3. Place an accessory → Abilities activate instantly!


Or use Quick Equip: Hold a tagged item + Shift + Right-Click to equip instantly.

Or use the Hotkey: Select a hotbar slot + Double-Sneak to open the menu.

---

📊 Stats

---

🔧 Compatibility

• Minecraft: 1.14.4 — 1.21+
  
• Server: Spigot, Paper, Purpur, Folia*
  
• Java: 8+
  
• GeyserMC: Supported (custom Bedrock resource pack, mappings & custom container GUIs included)
  
• Dependencies: None (standalone)
  

*Folia support is experimental

🌐 Geyser & Bedrock Edition Support
CuriosPaper provides full GUI slot icon support and custom container interfaces for Bedrock Edition players joining via GeyserMC.

• Automatic Setup: If Geyser is running on the same server, CuriosPaper will automatically detect Geyser's folder on startup, extract mappings & pack, and copy them directly to Geyser's packs/ and custom_mappings/ folders.
  
• Custom Container GUIs: Bedrock players receive 3-row chest interfaces for Anvils and Smithing Tables.
  
• Manual Setup: Copy CuriosPaper_Geyser.zip into Geyser's packs/ and CuriosPaper_mappings.json into custom_mappings/.
  

---

📥 Quick Start


# 1. Download CuriosPaper.jar from Modrinth or GitHub Releases
# 2. Drop it into your server's plugins/ folder
# 3. Start the server
# 4. Done! Use /baubles in-game


First Accessory in 60 Seconds


/curios create speed_ring # Create a new item

In the GUI: set the name, material, slot type → add a Speed ability → add a recipe → done.

/curios give speed_ring # Get the item
/baubles # Open accessory menu

Place it in a ring slot — Speed I activates! 🏃

---

⚙️ Configuration Highlights

[​code=yaml]
# Accessory slots — fully customizable
slots:
ring:
name: "Ring"
icon: "GOLD_NUGGET"
amount: 2

# Hotkey to open GUI without commands
features:
hotkey:
enabled: true
slot: 8
sneak-type: "double" # single, double, or hold

# Custom Bedrock GUIs
use-custom-smithing-gui: true
use-custom-anvil-gui: true

# Resource pack with external pack merging
resource-pack:
enabled: true
combine-external-rp: false
[​/code]

Full configuration reference → curiospaper.run.place

---

📖 Documentation



The full documentation site covers:

• Getting Started — Installation, concepts, first accessory walkthrough
  
• Configuration — Slots, features, abilities, performance & storage
  
• Systems — Accessories, abilities, recipes, loot tables, mob drops, trades, 3D models, hotkeys, death behavior
  
• GUI Editors — Item, ability, recipe, loot table, mob drop, trade, 3D model editors
  
• Developer API — Getting the API, accessories, loot tables, 3D models, resource packs, events
  
• Examples — Complete plugin examples with loot tables, abilities, and recipes
  

---

🆕 What's New in v2.0.1

• 📱 Bedrock Anvil & Smithing GUIs — Dedicated 3-row chest interfaces for Bedrock Edition players to access Anvil (combining, repairing, renaming with XP cost) and Smithing Tables (1.20+ templates & legacy smithing).
  
• 📊 Attribute Modifier Operations — Configure player modifier abilities with specific operations: ADD_NUMBER (flat value), ADD_SCALAR (percentage %), and MULTIPLY_SCALAR_1 (multiplier x).
  
• ✈️ Flight & Spectator Model Auto-Hiding — ArmorStand 3D models automatically hide when players toggle flight (isFlying), enter spectator mode, or enter special poses (SWIMMING, FALL_FLYING, SPIN_ATTACK).
  
• 🚪 Inventory Dismount Safety — 3D models temporarily dismount when opening inventories and auto-remount 2 ticks after close to eliminate visual GUI overlaps.
  
• 🛠️ Flexible Server Version Parsing — Improved version parsing regex in VersionUtil for non-standard Paper dev builds (e.g. 26.2.build.48-alpha).
  
• 💬 Command & GUI Improvements — Fixed give command messaging targeting and case-insensitive color-stripped GUI title matching.
  

Full changelog → CHANGELOGS.md

---

💬 Community

---

☕ Support the Project

---

🤝 For Developers

Maven
[​code=xml]
<repository>
<id>jitpack.io</id>
<url>jitpack.io</url>
</repository>

<dependency>
<groupId>com.github.Brothergaming52</groupId>
<artifactId>CuriosPaper</artifactId>
<version>2.0.1</version>
<scope>provided</scope>
</dependency>
[​/code]

plugin.yml
[​code=yaml]
depend: [​CuriosPaper]
[​/code]

Full API docs → curiospaper.run.place/api

---