PreventArmor

Stops players wearing armor they aren't supposed to. You choose what happens to them: armor bounces straight back into their inventory, or they keep it on and take damage until they take it off.

Heavily inspired by Naked and Afraid. Runs on Paper, Folia and Fabric, 1.21.1 to 26.3.

Two modes

Features

• Block everything or a list. Anything in an armor slot, or only the items you name.
• Exempt items. Tag an item, or give it a certain lore line, and it's ignored completely. Good for event gear and kits.
• Whitelist. Only named players, or holders of a permission, may wear blocked armor.
• Per-piece permissions. Let ranks wear helmets but not chestplates, or netherite but not diamond.
• Folia support. Each player is checked on their own region thread.
• Fabric build with the same rules and permission nodes.

Where to go next

Install it, then read Who can wear what. That page explains how bypass, whitelist and per-piece permissions fit together.

Install

Download from Modrinth.

Requirements

Java 21 for 1.21.x, Java 25 for 26.x. Spigot isn't supported.

Paper and Folia

1. Put the Paper jar in plugins/.
2. Start the server. plugins/PreventArmor/config.yml is created.
3. Edit it, then run /preventarmor reload.

Fabric

1. Install Fabric API.
2. Put the PreventArmor jar for your exact Minecraft version in mods/.
3. Start the server. Settings are in config/preventarmor.json.

fabric-permissions-api is bundled, so LuckPerms for Fabric just works.

Updating from 2.0

Your old config.yml keeps working as it is. The new options are all off until you add them, so an upgraded server still punishes like before. block-equip in particular counts as false when it's missing. Fresh installs get the new default file, with block-equip: true.

config.yml

Paper and Folia. plugins/PreventArmor/config.yml, applied with /preventarmor reload.

Penalty

What counts as blocked

Exemptions and access

nbt-exempt and lore-exempt have their own page. permissions and whitelist are explained in Who can wear what.

Full default file

damage-amount: 2.0
warning-message: "&cArmor is forbidden!"
remove-armor: false
block-equip: true
equip-denied-message: "&cYou are not allowed to wear that."
check-interval: 20
block-specific: false
blocked-armor:
  - DIAMOND_HELMET
  - NETHERITE_CHESTPLATE
nbt-exempt:
  enabled: true
  key: "armor_exempt"
  value: "true"
lore-exempt:
  enabled: true
  lines:
    - "ONLY NETHERITE ARMOR"
permissions:
  enabled: false
whitelist:
  enabled: false
  players: []
  permissions:
    - preventarmor.whitelisted

Who can wear what

Every armor piece a player has on is checked against these steps, top to bottom. The first one that gives an answer wins.

The order

1. Not blocked (see block-specific) or exempt? Allowed.
2. Has preventarmor.bypass? Allowed.
3. whitelist.enabled and the player isn't on it? Refused.
4. permissions.enabled? Allowed only with preventarmor.wear.<slot> or preventarmor.wear.<item>.
5. Otherwise: allowed if the whitelist is on (so the player got past step 3), refused if it's off.

With both whitelist and permissions off, you get the classic behaviour: nobody wears blocked armor, except preventarmor.bypass.

Whitelist

whitelist:
  enabled: true
  players:
    - Steve
    - 069a79f4-44e9-4726-a5be-fca90e38aaf5
  permissions:
    - preventarmor.whitelisted
    - myserver.rank.knight

A player is on the list if their name (any capitalisation) or UUID is listed, or if they hold any node under permissions. Names are checked as they are now, so after a name change, either update the list or use the UUID.

This is the strict option. Off the list means no blocked armor, full stop, whatever else they have. An empty enabled list leaves only preventarmor.bypass holders able to wear anything, and the console warns you about it on reload.

Per-piece permissions

permissions:
  enabled: true

Now a player needs one of these for each piece they wear:

Either node is enough. Slot nodes are the quick way. Item nodes are for when only certain materials should be allowed.

Combining them

Whitelist on plus permissions on: you must be whitelisted and hold the piece's node. That's how you get “only staff, and only leather”.

whitelist:
  enabled: true
  permissions: [ myserver.staff ]
permissions:
  enabled: true
# then: /lp group staff permission set preventarmor.wear.leather_chestplate true

Examples

Exempt items

An exempt item is ignored completely: no damage, no warning, never removed or refused. Exemptions are checked before any permission or whitelist rule.

NBT tag

nbt-exempt:
  enabled: true
  key: "armor_exempt"
  value: "true"

The item needs a string tag in the plugin's persistent data, under the preventarmor namespace. With the defaults that's preventarmor:armor_exempt = "true", compared without caring about case.

/give @s diamond_chestplate[custom_data={PublicBukkitValues:{"preventarmor:armor_exempt":"true"}}]

The key may only contain lower-case letters, digits and . _ - /. A bad key is logged and the NBT exemption turns itself off.

Lore line

lore-exempt:
  enabled: true
  lines:
    - "ONLY NETHERITE ARMOR"
    - "Event Gear"

Any lore line that matches an entry, as a whole line, makes the item exempt. Colours and formatting are ignored, so is capitalisation, and spaces at either end are trimmed. Blank entries are skipped. Otherwise every item with an empty lore line would slip through.

On Fabric

The Fabric build looks for the same tag in the same place, custom_data.PublicBukkitValues."preventarmor:armor_exempt", so gear made on Paper keeps working. It also accepts the key at the top level of custom_data:

/give @s diamond_chestplate[custom_data={"preventarmor:armor_exempt":"true"}]

Fabric config

config/preventarmor.json. Same options as Paper with camel-case names. Rewritten on load so new options appear, applied with /preventarmor reload.

Options

blockedArmor takes item ids. Mod items work too: "examplemod:steel_helmet".

Permissions without a mod

With no permissions mod, every preventarmor.* node except reload is off for everyone, ops included. So bypass, whitelist nodes and per-piece nodes all need LuckPerms or similar. Whitelisting by name or UUID needs nothing extra.

Commands

Reference

A reload swaps the whole config in one go. Checks running at that moment see either the old settings or the new ones, never half of each.

Permissions

All permissions

Creative and spectator

Players in creative or spectator are skipped entirely: no checks, no refusals, no damage. Neither mode can be hurt, so punishing them would only strip their armor for no reason.

How it works

The check

Each online player gets their own repeating task, every check-interval ticks, starting one tick after they join. On Paper and Folia it runs on the player's entity scheduler, which on Folia is their region thread. So the plugin never touches a player from the wrong thread.

• Refuse mode: each unauthorized piece is taken off and added to the inventory. Whatever doesn't fit is dropped at the player's feet. One action bar message per check, however many pieces came off.
• Punish mode: if any piece is unauthorized, the player takes damage-amount damage once and sees the warning. With remove-armor, each offending piece is dropped.

Refusing on equip

In refuse mode, armor isn't left on until the next check. On Paper and Folia the plugin listens to PlayerArmorChangeEvent. When a new piece goes on, it schedules a strip for the next tick on that player's own scheduler. The next tick, because the slot is still mid-update while the event fires. On Fabric, the equipment-change event queues the player, and they're handled at the end of the same server tick.

Right-click equipping, shift-clicking, dispensers, /item replace: every route ends in the slot changing, so every route is covered. The periodic check catches anything already worn when a player logs in.

The damage

Punish damage uses the starve damage type. Minecraft treats it as ignoring armor points, Protection enchantments and Resistance, so the full amount always lands. The catch: a player killed by it sees “starved to death”.

Thread safety

The config is parsed into one read-only object. A reload builds a new one and swaps it in. Checks on different Folia regions read whichever object is current, and nothing they read can change underneath them.

Integration

There's no Java API or custom event yet. Other plugins hook in through items and permissions, which is usually what you want anyway.

Making items exempt from code

Write the exempt tag yourself. Use the preventarmor namespace and whatever key the server has in nbt-exempt.key:

NamespacedKey exempt = new NamespacedKey("preventarmor", "armor_exempt");

ItemStack chest = new ItemStack(Material.DIAMOND_CHESTPLATE);
chest.editMeta(meta -> meta.getPersistentDataContainer()
        .set(exempt, PersistentDataType.STRING, "true"));

Works from kits, crates, MythicMobs drops, anything that can set persistent data or custom_data. The value has to be a string. An integer or byte tag with the same name won't count.

Granting access from code

Everything else is permissions, so use your permissions plugin's API. With LuckPerms:

LuckPerms lp = LuckPermsProvider.get();
lp.getUserManager().modifyUser(player.getUniqueId(), user ->
        user.data().add(Node.builder("preventarmor.wear.chest")
                .expiry(Duration.ofMinutes(10))
                .build()));

That gives ten minutes of chestplate access, as long as permissions.enabled is on. A timed preventarmor.bypass works the same way for a temporary free pass.

Cancelling a refusal

Not possible yet. The plugin doesn't fire an event before it acts. If you need per-situation control, exempt the item or grant a timed permission as shown above.

Building from source

JDK 21 and JDK 25 required.

git clone https://github.com/eyman26/PreventArmor.git
cd PreventArmor
./gradlew buildAll

Jars go to build/dist/. ./gradlew :paper:check also compiles the Paper code against the newest Paper API. :paper:runServer and :paper:runFolia start a dev server.

FAQ

Why can't players wear elytra or pumpkins?

With block-specific: false, anything in an armor slot counts. Switch to block-specific: true and list only the real armor pieces, or give everyone preventarmor.wear.chest with per-piece permissions on. Note that also allows chestplates.

I'm op and it still blocks me

That's expected. Ops don't get preventarmor.bypass automatically. Grant it, or switch to creative.

Why does the death message say “starved to death”?

The penalty uses starvation damage, because it's the one damage type that armor, enchantments and Resistance can't reduce. Use refuse mode if the message bothers you, since it deals no damage at all.

Does refuse mode drop armor on the ground?

Only when the inventory is full. Normally the piece goes straight back into the inventory.

Is there a bypass for a whole world?

Not built in. Most permissions plugins can grant preventarmor.bypass per world. LuckPerms does it with a world= context.

Do mob armor or armor stands count?

No. Only players are checked.

Troubleshooting

Common problems

Known limits

• No per-world settings in the plugin itself.
• No Java API or events.
• Item nodes use the vanilla id without the namespace, so two mods with an item of the same name share a node.

Support

Questions and bug reports go through the Discord.

Join the Discord

What to include in a report

• Server software and version (Paper, Folia, a fork, or Fabric)
• Your PreventArmor version
• Your config.yml or preventarmor.json
• The permissions the affected player has (/lp user <name> permission info)
• The console log from start-up