---

CuriosPaper

CuriosPaper is a Curios-style accessory inventory API for Paper (api-version: 1.21).
It adds a separate accessory GUI with configurable slot types (back, rings, charms, etc.) and exposes a clean Java API so other plugins can register and manage accessories without touching NBT or custom inventories.

It does not add items or stats — it's an API layer for servers and plugins that want extra equipment slots.

Join our Discord for any help

---

Features

Dedicated accessory GUI
• Commands: /baubles, /b, /bbag
• Main menu → per-slot pages
• Configurable titles, layout, filler items, borders

9 slot types by default (fully configurable)
head, necklace, back, body, belt, hands, bracelet, charm, ring

Config-driven slot behavior
• Custom name, icon, lore
• Internal slot count
• Resource pack model per slot

Automatic resource pack generation & hosting
• Builds pack from plugin assets
• Merges assets from other plugins
• Hosts ZIP via built-in HTTP server (configurable IP/port)

Persistent player data
• YAML storage
• Auto-save interval
• Optional backup system

Performance controls
• Player data caching
• Unload data on quit
• Safety cap: max items per slot

Quality-of-life toggles
• Auto-add slot lore to tagged items
• Show/hide empty GUI slots
• GUI/equip sounds

Developer API
• Tag items as accessories
• Query and modify player accessory slots
• Listen to AccessoryEquipEvent
• Register additional resource pack assets

---

Requirements

• Paper or any Paper-compatible fork
• Minecraft 1.21+
• Players must accept the server resource pack (if enabled)

---

Commands

/baubles
Aliases: /b, /bbag
Opens the accessory GUI.
Everything else is handled via config or API.

---

Configuration Overview

CuriosPaper generates config.yml on first run.

Resource Pack

resource-pack:
  enabled: true
  port: 8080
  host-ip: "your.public.ip.or.domain"
  base-material: "PAPER"

Controls hosting, merge behavior, and the material used for slot icons.

Slots

Example:

slots:
  head:
    name: "&e⚜ Head Slot ⚜"
    icon: "GOLDEN_HELMET"
    item-model: "curiospaper:head_slot"
    amount: 1
    lore:
      - "&7Equip magical headpieces."

• Each top-level key (head, necklace, etc.) is a slot type ID.
• item-model links to the resource-pack model.
• amount determines how many internal slots the type has.

Storage

storage:
  type: "yaml"
  save-interval: 300
  save-on-close: true
  create-backups: false
  backup-interval: 3600
  max-backups: 5

Performance

performance:
  cache-player-data: true
  unload-on-quit: true
  max-items-per-slot: 54

GUI

gui:
  main-title: "&8✦ Accessory Slots ✦"
  slot-title-prefix: "&8Slots: "
  filler-material: "GRAY_STAINED_GLASS_PANE"
  border-material: "BLACK_STAINED_GLASS_PANE"
  filler-name: "&r"
  main-gui-size: 54
  use-patterns: true

Features & Debug

features:
  add-slot-lore-to-items: true
  show-empty-slots: true
  play-gui-sound: true
  gui-sound: "BLOCK_CHEST_OPEN"
  play-equip-sound: true
  equip-sound: "ENTITY_ITEM_PICKUP"

debug:
  enabled: false
  log-api-calls: false
  log-inventory-events: false
  log-slot-positions: false

---

Developer API

Adding the dependency

you can add this as a dependency for your plugin check out
https://jitpack.io/#Brothergaming52/CuriosPaper/1.0.1
for the maven or gradle code

Getting the API

import org.bg52.curiospaper.CuriosPaper;
import org.bg52.curiospaper.api.CuriosPaperAPI;

public class MyPlugin extends JavaPlugin {
    private CuriosPaperAPI curiosApi;

    @Override
    public void onEnable() {
        curiosApi = CuriosPaper.getInstance().getCuriosPaperAPI();
    }
}

---

Tagging Items as Accessories

ItemStack tagged = curiosApi.tagAccessoryItem(item, "necklace", true);

Retrieve slot type:

String slot = curiosApi.getAccessorySlotType(itemStack);

---

Validating Accessories

boolean valid = curiosApi.isValidAccessory(itemStack, "ring");
boolean slotExists = curiosApi.isValidSlotType("back");
int max = curiosApi.getSlotAmount("ring");

---

Querying Equipped Accessories

List<ItemStack> items = curiosApi.getEquippedItems(player, "ring");
ItemStack backItem = curiosApi.getEquippedItem(player, "back", 0);

boolean has = curiosApi.hasEquippedItems(player, "back");
int count = curiosApi.countEquippedItems(player, "ring");

UUID-based variants are also available.

---

Modifying Equipped Accessories

curiosApi.setEquippedItem(player, "ring", 0, item);
curiosApi.setEquippedItems(player, "bracelet", list);
curiosApi.removeEquippedItemAt(player, "necklace", 0);
curiosApi.removeEquippedItem(player, "necklace", targetItem);
curiosApi.clearEquippedItems(player, "charm");

---

Slot Metadata

NamespacedKey key = curiosApi.getSlotTypeKey();
List<String> types = curiosApi.getAllSlotTypes();

---

Accessory Equip Event

@EventHandler
public void onAccessoryEquip(AccessoryEquipEvent e) {
    if (e.getAction() == Action.EQUIP && isForbidden(e.getNewItem())) {
        e.setCancelled(true);
    }
}

Event triggers on EQUIP, UNEQUIP, and SWAP.

---

Resource Pack Integration for Other Plugins

File root = curiosApi.registerResourcePackAssetsFromJar(this);

Place your assets under src/main/resources/resources/
CuriosPaper extracts and merges them automatically.

---