⭐ hRune ⭐ [1.21.11-26.X] | PAPI, Vault, and more support!

hRune is a custom rune item plugin. A rune is an item that gives effects to the player while it is placed in a specific location: inventory, hotbar, main hand, off hand, any hand or armor slots.
You can create different rune types through the configuration: speed runes, night vision runes, damage runes, defensive runes, health runes, hunger control runes, passive healing runes, saturation runes and many other custom artifacts.
The plugin is useful for RPG, PvP, Survival, factions-like servers, custom progression systems, donor items, quest rewards, crates and seasonal items.
Main Features

• Custom rune items — every rune is configured in config.yml.
• Unlimited rune types — create as many custom runes as your server needs.
• Multiple activation modes — activate runes from inventory, hotbar, hands or armor slots.
• Permanent potion effects — effects stay active while the rune is active and are removed when the rune is no longer active.
• Player attributes — add health, movement speed, attack damage and other Bukkit/Paper attributes.
• Incoming damage modifier — reduce or increase damage received by the player.
• Outgoing damage modifier — increase or reduce damage dealt by the player, including projectile damage.
• Damage cause cancellation — fully block selected damage causes such as fall or fire damage.
• Auto extinguish — constantly remove fire ticks from the player.
• Freeze protection — reset freeze ticks while the rune is active.
• Hunger control — reduce or disable hunger drain.
• Passive healing — restore health over time.
• Passive saturation — add or modify player saturation over time.
• Stack scaling — effects can scale based on the amount of rune items in the stack.
• Active item limit — limit how many items in a stack can increase the effect.
• CustomModelData support — use custom resource pack models.
• BaseHead support — create rune items using custom head textures.
• MiniMessage and HEX colors — use gradients, colors and styled text in names, lore and messages.
• ItemFlags and enchantments — customize the item appearance and add visual glint.
• Rune block placement protection — rune items cannot be accidentally placed as blocks.
• PersistentDataContainer identification — runes are detected by an internal ID, not only by name or lore.
• Optimized profile recalculation — rune effects are recalculated only when relevant inventory changes happen.
• Optional hPvP support — compatibility with duel mechanics and potion effect restoration.

How it works
A server owner creates a rune in the configuration, sets the item appearance, activation mode and effects.
After the rune is given to a player, it works automatically when placed in the correct slot.
Examples:

• a rune in the inventory gives permanent speed;
• a rune in the main hand increases outgoing damage;
• a rune in the off hand reduces incoming damage;
• a rune in armor slots adds player attributes;
• a rune in the hotbar gives passive healing;
• a rune can protect from fall, fire or other damage causes.

Players do not need to run commands to activate a rune. They only need to keep it in the required slot.
Activation Modes
Each rune can use one activation mode.
INVENTORY — active while the rune is in the player inventory.
HOTBAR — active only while the rune is in the hotbar.
MAIN_HAND — active only in the main hand.
OFF_HAND — active only in the off hand.
ANY_HAND — active in either hand.
ARMOR — active in armor slots.
This allows you to create many different item types: passive charms, hand-held combat runes, armor runes, inventory artifacts and more.
Stack Scaling
hRune can scale rune effects by item amount.
Main options:
scaleByItemAmount — if enabled, the rune power depends on the amount of items in the stack.
maxActiveItems — limits how many items can increase the effect.
For example, you can make a stack of runes stronger than a single rune, but limit the maximum effect to 8 active items.
Potion Effects
Runes can apply potion effects to the player.
Examples:

• speed;
• night vision;
• strength;
• resistance;
• jump boost;
• regeneration;
• any other PotionEffectType supported by your server version.

Each potion effect can have:

• effect type;
• amplifier;
• ambient setting;
• particles setting;
• HUD icon setting.

The active potion effect is maintained while the rune is active and removed when the rune becomes inactive.
Attributes
hRune supports Bukkit/Paper attributes.
You can configure:

• extra health;
• movement speed;
• attack damage;
• armor;
• attack speed;
• other available server attributes.

Supported attribute name styles include:
GENERIC_MAX_HEALTH
MAX_HEALTH
minecraft:max_health
minecraft:generic.max_health
Supported operations:
ADD_NUMBER
ADD_SCALAR
MULTIPLY_SCALAR_1
This makes it possible to create runes that work as real character upgrades, not only visual items.
Combat Modifiers
hRune can also modify combat behavior.
Available options:

• incomingDamageMultiplier — multiplier for damage received by the player.
• outgoingDamageMultiplier — multiplier for damage dealt by the player.
• cancelDamageCauses — fully cancel selected damage causes.

Example use cases:

• reduce all incoming damage by 20%;
• increase outgoing damage by 20%;
• block fall damage;
• block fire damage;
• create special PvP artifacts;
• create defensive survival charms.

Outgoing damage modifiers also work with projectiles if the projectile shooter is a player.
Passive Modifiers
Runes can provide passive utility effects.
Supported passive modifiers include:

• extinguish fire;
• reset freeze ticks;
• reduce hunger drain;
• restore health over time;
• add saturation over time.

This is useful for survival artifacts, rare relics, PvP charms, farming items and progression rewards.
Rune Item Customization
Every rune can have its own item appearance.
You can configure:

• material;
• custom BaseHead texture;
• display name;
• lore;
• glow;
• unbreakable state;
• CustomModelData;
• maximum stack size used when giving the rune;
• ItemFlags;
• enchantments;
• hidden attributes;
• MiniMessage colors and gradients.

Material examples:
NETHER_STAR
basehead-<base64>
Rune items store an internal rune ID through PersistentDataContainer. This means players cannot create a working rune just by renaming an item or copying its lore.
Optimization
hRune does not constantly recalculate every player without a reason.
The plugin includes:

• dirty profile queue;
• maximum profile recalculations per tick;
• recalculation only after relevant inventory changes;
• held slot tracking;
• hand swap tracking;
• active profile cache;
• passive ticker for healing, saturation, fire and freezing;
• careful potion effect handling after death and respawn.

This helps keep the rune system responsive while avoiding unnecessary server load.
Commands
All commands require hrune.admin.
/hrune give <player> <rune_id> [amount] — give a rune to a player.
/hrune reload — reload the plugin configuration.
If the amount is not specified, the plugin uses the default amount from the configuration.
If the target player's inventory is full, leftover rune items are dropped near the player.
Permissions
hrune.admin — access to all administrative commands.
This permission allows:

• giving runes;
• reloading the configuration;
• using tab completion for players, rune IDs and amounts.

What can be configured?

• plugin prefix;
• plugin messages;
• passive update interval;
• maximum dirty profile recalculations per tick;
• default rune amount for the give command;
• rune ID;
• item material;
• BaseHead texture;
• display name and lore;
• glow;
• unbreakable state;
• CustomModelData;
• maximum stack size used when giving the rune;
• ItemFlags;
• enchantments;
• activation mode;
• scaling by item amount;
• maximum active items;
• potion effects;
• attributes;
• incoming damage multiplier;
• outgoing damage multiplier;
• cancelled damage causes;
• auto extinguish;
• freeze tick reset;
• hunger drain multiplier;
• passive healing;
• passive saturation.

Requirements
Required:

• Java 21
• Paper/Purpur 1.21.x

Optional:

• hPvP — for compatibility with duel mechanics and potion effect restoration.

Important: hRune uses Paper API features, so regular Spigot should not be listed as the supported platform.
Installation

1. Make sure your server runs Java 21 and Paper/Purpur 1.21.x.
2. Put hRune.jar into your plugins folder.
3. Start the server.
4. Open config.yml.
5. Create or edit runes in the runes section.
6. Give a rune using /hrune give <player> <rune_id> [amount].
7. After configuration changes, run /hrune reload.

Why use hRune?
hRune lets you create real custom artifacts instead of simple renamed items.
You can build PvP runes, donor charms, RPG relics, crate rewards, quest items, seasonal artifacts and progression items that only work when placed in the correct slot.
The system is flexible enough for simple potion-effect runes and advanced items with attributes, damage modifiers, passive healing, hunger control and protection from selected damage types.