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. Bedrock Edition compatible. Powerful developer API.

---

Think of it as Baubles / Curios — but for Paper & Spigot, with 3D models, loot tables, GUI editors, Bedrock container support, 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 — with full support for Java and Bedrock Edition players.

⚡ Features

🎒 Core Accessory System

	Feature	Description
	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 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:

🛠️ Configuration Showcase & Setup Instructions

# Configuration for CuriosPaper Custom Accessory Slots
version: "2.0.1"

# Update Checker
updates:
  check-for-updates: true

# Storage Engine Settings
storage:
  # Selected engine: YAML (flatfile), SQLITE, MYSQL, or MONGODB
  engine: "YAML"
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: ""
    table-prefix: "curios_"
  mongodb:
    connection-string: "mongodb://localhost:27017"
    database: "minecraft"
    collection: "curios_playerdata"

# Resource Pack Settings
resource-pack:
  # Mode: SELF (embedded HTTP host), LINK (external URL), or NONE
  mode: SELF
  port: 8080
  host-ip: "123.45.67.89"
  url: ""
  hash: ""
  force-pack: false
  prompt-message: "Please accept the resource pack to view custom accessories!"

# Feature Toggles
features:
  # Allow elytra equipping in back slots
  allow-elytra-on-back-slot: true

  # Custom Bedrock GUIs for Anvils and Smithing Tables
  use-custom-smithing-gui: true
  use-custom-anvil-gui: true

  # Display empty accessory slots in GUI
  show-empty-slots: true

  # Keep Curios on Death: Always, Auto (follows keepInventory), or Never
  keep-curio-inventory:
    type: "Auto"

  # Sneak keybind hotkey to open accessory menu
  hotkey:
    enabled: true
    slot: 8
    sneak-type: "double" # single, double, or hold

# Message customization with legacy (&a) and HEX (<#FF5555>) color support
prefix: "&6[CuriosPaper] "

items:
  quick-equip-lore: "&8▶ Shift + Right Click to equip"
  slot-lore: "&6Slot: &e{slots}"
  ability-when-worn: "&7When worn:"
  ability-potion-effect: "&9{effect} {level}"
  
  # Attribute Modifier Operation Lore Formatting (v2.0.1)
  ability-attribute-positive: "&9+{value} {attribute}"
  ability-attribute-negative: "&c-{value} {attribute}"
  ability-attribute-scalar-positive: "&9+{value}% {attribute}"
  ability-attribute-scalar-negative: "&c-{value}% {attribute}"
  ability-attribute-multiply-positive: "&9x{value} {attribute}"
  ability-attribute-multiply-negative: "&cx{value} {attribute}"

🎮 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

🌐 Geyser & Bedrock Edition Support

CuriosPaper provides full GUI slot icon and custom container support 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 the mappings and resource pack, and copy them directly to Geyser's packs/ and custom_mappings/ folders.
• Custom Bedrock GUIs (Anvil & Smithing): Bedrock players get dedicated 3-row chest interfaces for Anvils (repair, rename, combine) and Smithing Tables (supports 1.20+ Netheriite templates and legacy recipes).
• Manual Setup (Proxy/Separate Server):
  1. Retrieve files from your server's plugins/CuriosPaper/geyser/ directory.
  2. Copy CuriosPaper_Geyser.zip into your Geyser packs/ folder.
  3. Copy CuriosPaper_mappings.json into your Geyser custom_mappings/ folder.
  4. Ensure enable-custom-content is set to true in Geyser's config.yml and restart Geyser.

📥 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!

📖 Documentation

The full documentation site covers:

🆕 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

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

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

plugin.yml

depend: [CuriosPaper]

Full API docs → curiospaper.run.place/api