API
Reading the trim catalogue, the halves a player combines by hand, their chosen trim and what they are shown wearing, the trims written onto armor, and the two events.
ArmorTrimService is what another plugin reads and drives ExyliaArmorTrims through: the patterns and
materials a player combines, the trim they chose, and the trims written onto armor itself.
ExyliaAPI.get(ArmorTrimService.class).ifPresent(trims -> {
trims.select(player, ArmorPiece.CHESTPLATE, "sentry/netherite");
trims.trimItem("rib/redstone").ifPresent(item -> player.getInventory().addItem(item));
});The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page. shown, giveTrimItem, removerItem, openMenu and
the two events arrived with ExyliaArmorTrims 1.3.0, in exylia-api v1.133.0: compile against that
tag or a newer one to reach them.
Everything is addressed by trim id, matched without regard to case: the pattern/material form of
a combination — sentry/netherite. A preset id from before 1.5.0 is still read as the look it stood
for. An id that names nothing the catalogue offers is not an error, so lookups answer empty and writes
answer false.
trims() now always answers an empty list and exists always false: they listed presets, and there
are none. Read patterns() and materials() for the catalogue, and trim(String) for one
combination. Every ArmorTrim has preset false, an empty permission and all four pieces.
The catalogue#
| Method | What it does |
|---|---|
trims() | Always empty since 1.5.0: it listed presets. Combinations are too many to list. |
trim(String trimId) | One trim as an Optional<ArmorTrim>, taking a pattern/material combination. Empty when either half is not offered. |
exists(String trimId) | Always false since 1.5.0: it asked for presets. Ask trim instead. |
patterns() | The patterns a player can combine by hand, in menu order. |
materials() | The materials a player can combine by hand, in menu order. |
Permissions#
| Method | What it does |
|---|---|
canUse(Player, String trimId) | Whether they may wear the trim. |
canUse(Player, String trimId, ArmorPiece) | The same answer: a trim fits every piece. Kept for callers written against presets. |
Both answer by the server's own rule: both halves, each by its node or by what a crate or a purchase unlocked — a shop asking gets the same answer the menu would give, not a raw permission check.
What the player chose#
| Method | What it does |
|---|---|
mode() | Where the trims this server draws come from, as a TrimMode. |
selected(UUID player, ArmorPiece) | The trim id chosen for that slot, as an Optional<String>. Empty when they chose none, the menu is off, or their selection is still being read. |
select(Player, ArmorPiece, String trimId) | Sets the choice for that slot. true when it was stored. |
clear(Player, ArmorPiece) | Takes the chosen trim off one slot. true when something was there to remove. |
clearAll(Player) | Takes every chosen trim off. true when something was there to remove. |
selected is a choice, not a result: it stays set while the slot is empty, and the trim appears
again the moment the player equips armor that fits.
select is a set rather than a toggle — running it twice leaves the trim on. It is not gated by
ownership: the caller decided this player may wear it. That is the same rule ExyliaArrows follows and
the opposite of ExyliaArmorSkin. Ask canUse(Player, String, ArmorPiece) first when you do want
ownership to decide.
TrimSelectionChangeEvent fires for it like for a menu click; a listener that cancels it makes
select answer false.
What the player is shown wearing#
| Method | What it does |
|---|---|
shown(UUID player, ArmorPiece) | The trim drawn on that slot right now, as an Optional<String>: a pattern/material combination. |
The answer after every rule has had its say — the mode, the armor actually in the slot, the wearer's
ownership, and whether their cosmetics are shown at all — which neither selected nor trimOf gives
on its own. Empty when the slot shows the armor as it really is or the player is not online. What a
placeholder or a scoreboard describing somebody's look should read; safe from any thread.
Trims on items#
| Method | What it does |
|---|---|
trimOf(ItemStack armor) | The trim id written onto that armor, as an Optional<String>. Empty when it carries none. |
apply(ItemStack armor, String trimId) | Writes a trim onto the armor in place, keeping everything else it had. true when written. |
strip(ItemStack armor) | Takes the trim off and gives nothing back. true when a trim was there. |
trimItem(String trimId) | A trim item ready to be given out, as an Optional<ItemStack>. Empty when the id names no trim. |
isTrimItem(ItemStack) | Whether an item is one of this plugin's trim items. |
Ask isTrimItem before a container, a shop or a trade treats a stack as ordinary loot: a trim item
is drawn as whatever suits it and is not the material it looks like.
Handing things out#
| Method | What it does |
|---|---|
giveTrimItem(Player, String trimId, int amount) | Gives trim items through the plugin's reward queue: what does not fit is kept and handed over on the player's next join. The player is told nothing. false when the id names no trim or the amount is below one. |
removerItem() | A new remover, ready to be given. It only takes trims off on a server whose mode uses items. |
openMenu(Player) | Opens the trim menu as /trims does — the classic one or the 3D wardrobe, by menu-style and the wardrobe node — for an NPC, a sign or a lobby item. The command node is not checked. false when the mode has no menu. |
Call giveTrimItem and openMenu on the thread that owns the player.
Redrawing#
| Method | What it does |
|---|---|
refresh(Player) | Recomputes what the player looks like and re-sends it to everyone who can see them. |
Only needed after something the service does not know about changed — a permission granted at runtime, an item swapped by another plugin. Every write above already redraws.
Types#
ArmorTrim — id, name (colour codes still in it), permission, pieces, pattern,
material and preset. Since 1.5.0 every trim is a combination: permission is empty, because it is
granted by the two halves behind it, pieces holds all four and preset is false.
TrimOption — one half a player combines by hand: id, name, permission. Patterns and
materials share the record, and which half one is comes from the method that handed it over. They
exist because a trim is sold in halves.
ArmorPiece — HELMET, CHESTPLATE, LEGGINGS, BOOTS. slot() gives the Bukkit
EquipmentSlot, so a caller reading an inventory does not keep a switch of its own in step.
TrimMode — where a drawn trim comes from: ITEM (only what a trim item wrote onto the armor),
MENU (only what the wearer chose; trim items do nothing) or BOTH. usesItems() and usesMenu()
answer without a switch. Worth asking before writing anything: the half a server does not use answers
false or empty rather than throwing, so an integration written for both runs on either.
Everything returning a value reads the plugin's cache and is safe from a menu redraw or a placeholder. Everything that changes a selection writes to the database and redraws the player for everyone watching — call those on the main thread, and no more often than a player could.
Events#
Both live in net.exylia.lib.api.armortrims.event, are cancellable, and are called on the thread
that owns the player, which on Folia is their region thread.
TrimSelectionChangeEvent — the trims a player chose are about to change. One event per write,
however many slots it touches: pieces() are the slots and trimId() what they all change to, empty
when trims are coming off. Fired for a menu click, an admin command and the service's select and
clears alike, and only once the write is known to change something. Cancelling writes nothing and
explains nothing.
TrimApplyEvent — a player is dropping a trim item onto armor, after the plugin has agreed to it
and before anything is written. armor() is the live item, trimId() the trim going on, piece()
the slot. Not fired for apply. Cancelling leaves the armor untrimmed and the item on the cursor.
@EventHandler
public void onTrim(TrimSelectionChangeEvent event) {
if (arena.isPlaying(event.getPlayer())) event.setCancelled(true);
}What it does not expose#
The menu and wardrobe flows, the crate and raw configuration rows are left out on purpose — a public contract cannot be broken later, so it carries what an integration needs and nothing that only made sense inside one version.
If something you need is genuinely missing, ask on Discord.
Something missing on this page? Tell us on Discord