CuriosPaper

✦ CuriosPaper ✦

The Ultimate Custom Accessory Inventory System for Paper & Spigot

Rings · Necklaces · Capes · Crowns · Belts · Charms — and more.
Fully server-side. No mods required. Powerful developer API.

---

Think of it as Baubles / Curios — but for Paper & Spigot, with 3D models, loot tables, GUI editors, and a full plugin API.

🧩 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 — no client mods required.

⚡ Features

🎒 Core Accessory System

🎨 3D Model System ^{NEW in v1.3.0}

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, and flying
• 👁️ Smart visibility culling — hide models from the wearer's first-person view
• 🔱 Trident compatibility — models auto-hide during throws and riptide
• 🧟 Mob models — mobs can visually wear items they'll drop
• 🎮 Per-item toggle — players can right-click to show/hide their models

🛠️ In-Game GUI Editors

Create and configure everything visually — no YAML editing required:

📦 Item Distribution

🔌 Developer API

A comprehensive API for other plugins to integrate with CuriosPaper:

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);

Custom Events:

🎮 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

*Folia support is experimental

📥 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

# 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

  # What happens to accessories on death?
  keep-curio-inventory:
    type: "Auto"               # Always, Auto, or Never

# Resource pack with external pack merging
resource-pack:
  enabled: true
  combine-external-rp: false

Full configuration reference → curiospaper.run.place

📖 Documentation

The full documentation site covers:

🆕 What's New in v1.3.1

• 🛠️ Consolidated Commands — All management commands merged into /curios
• 🌐 Localization System — Fully configurable messages in messages.yml
• 📋 Item Browser — Paginated GUI to manage all custom items and recipes
• ✨ New API Events — CuriosCraftEvent, CuriosModelEquipEvent, CuriosMobModelEquipEvent
• 🚀 Auto-Update Checker — Stay up to date with the latest versions automatically
• 🧹 Refined Logic — Significant performance and reliability improvements

Full changelog → CHANGELOGS.md

💬 Community

☕ Support the Project

🤝 For Developers

Maven

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.Brothergaming52</groupId>
    <artifactId>CuriosPaper</artifactId>
    <version>1.3.1</version>
    <scope>provided</scope>
</dependency>

plugin.yml

depend: [CuriosPaper]

Full API docs → curiospaper.run.place/api