DUXPLIMA Documentation
UXPLIMA Documentation / Custom Items & Heads

Custom Items & Heads

Anywhere uxmEssentials asks for a material — menu icons, and the same shared icon resolution used for kits and hologram displays — you aren't limited to vanilla items. A short provider:id prefix lets you drop in custom items from ItemsAdder, Oraxen, Nexo, MMOItems or ExecutableItems, and custom heads from HeadDatabase, base64 textures or player skins.

Copy Markdown

Custom Item Providers

Prefix the material with the provider name and the item's id:

PrefixProviderExample
itemsadder:ItemsAdderitemsadder:ruby_sword
oraxen:Oraxenoraxen:emerald_pickaxe
nexo:Nexonexo:amethyst_axe
mmoitems:MMOItemsmmoitems:SWORD:cutlass
ei:ExecutableItemsei:magic_wand

These resolve reflectively, so uxmEssentials never loads a provider's classes unless that plugin is actually present.

Exact id format follows the source plugin

The prefix vocabulary above is fixed, but the part after the colon is whatever id the source plugin expects (ItemsAdder namespaced ids, MMOItems type/id pairs, ...). Copy the id from that plugin's own catalog.

Heads

Custom-head sources use the same prefixed syntax:

PrefixSourceExample
hdb:HeadDatabase, by idhdb:12345
basehead:A base64 texture valuebasehead:eyJ0ZXh0dXJlcyI6...
skull:A player's headskull:Notch

HeadDatabase is guarded strictly — the hdb: source only resolves when the plugin is enabled and its API loads. Base64 and player heads are native and need no extra plugin.

Where These Work

The provider:id syntax is the material spec used by the menu engine, which backs the icon picker across menus and every module GUI. The same shared head sources (hdb: / basehead: / skull:) also feed hologram head displays and custom icons on kits and vaults.

# a menu item using an ItemsAdder icon
items {
  reward {
    material = "itemsadder:ruby_sword"
    slot = 13
    name = "<gradient:#ff4e50:#f9d423>Ruby Blade</gradient>"
  }
}

When a Provider Is Absent

Custom-item resolution fails soft. If a prefix points at a plugin that isn't installed (or an id that doesn't exist), the lookup silently misses and the renderer falls back to a plain material — the menu, kit or hologram still opens, just with a default icon.

SituationBehavior
Provider installed, id validThe custom item / head renders.
Provider absent or id unknownSilent fallback to a plain material.
HeadDatabase not enabledhdb: is a no-op; basehead: / skull: still work.
Advanced item meta with NBT-API

For the rare tag that native Paper data-components can't express, uxmEssentials will use NBT-API if it's installed. Item meta is built from native components first; without NBT-API that raw-NBT path is simply skipped — no de.tr7zw classes are touched.

Setup Checklist

  1. Install whichever item providers you use (ItemsAdder, Oraxen, Nexo, MMOItems, ExecutableItems) and/or HeadDatabase — no uxmEssentials config needed.
  2. Reference items with provider:id in menu specs, kit editors and hologram head displays.
  3. Missing providers degrade gracefully to plain materials, so a menu is never broken by an item you haven't installed yet.

Next Steps