Installation

Five minutes. ElementalArms needs no other plugin: MythicMobs, MMOCore and PlaceholderAPI are optional.

Requirements

Step by step

1. Put the jar in plugins/Download it from your panel on the website and drop it in the server's plugins folder.
2. Start the server onceIt creates plugins/ElementalArms/ with the config, the example items and the languages. The console will say it disables itself because there is no licence yet: that is normal.
3. Paste your licenceOpen config.yml and put the licence from your panel in license: "...".
4. Choose the languageIn the same file: language: en (English) or language: es (Spanish).
5. RestartRestart the server (do not use Bukkit's /reload). Type /ea help: if you see the command list, you are done.

What is in the folder

The licence

The plugin checks the licence against the website every 3 minutes. If the website does not answer, it keeps working for 48 hours (grace period) and warns you in the console; it only disables itself if the outage lasts longer. If the licence is revoked or used on two servers at once, it disables itself right away.

Updating to a new version

Replace the jar and restart. Your files are never overwritten: new options are added by themselves to config.yml and to the language files, with their explanation, and whatever you changed stays as it was. The details of each version are in

Updating from older versions.

Your first 10 minutes

A guided tour to see everything working before you configure anything. Do it as an operator (op) on your test server.

1 · Get a weapon and look at it

Hover over it in your inventory. The text under the name (the lore) is drawn by the plugin: stats, elemental damage, abilities with their trigger, gem sockets, requirements, durability and the tier at the end. Excalibur is an example that uses almost every system at once.

2 · Hit a mob

Hit any mob. You will see floating numbers (white for normal damage, gold for a crit, the element's colour for elemental damage) and a health bar above the mob for 6 seconds. Right-click the air: Excalibur casts a fireball where you aim.

3 · Open your equipment and character sheet

In /ea inventory drag the ring into one of the ring slots on the right. Close it and open /ea stats: its damage and crit are now added up, with a breakdown of where every point comes from (gear, set or accessories).

4 · Upgrade the weapon

In your inventory, pick up the stone with the mouse and click on Excalibur. It goes to +1 and all its stats grow by 8%. Do the same with the gem: it goes into one of its sockets and adds crit. It is the same gesture for stones, gems, reforging and identification.

5 · Create your own item

1. Open the editor/ea editor and choose the Swords category.
2. Create a new oneClick the Create New Item star and type an ID in chat, for example FROST_BLADE.
3. Shape itSet id to DIAMOND_SWORD, set Attack Damage to 8, open Elemental Damage and give it 6 ice. In Item Abilities add freeze with the on hit trigger.
4. SaveClick Save Changes (the green dye). If you do not save, the changes are lost on restart.
5. Try it/ea give <you> FROST_BLADE and hit a mob: it slows it down and the ice damage shows in blue.

6 · Place a station

Place a smithing table, look at it and type /ea station place FORGE. The Blacksmith's Forge hologram appears with particles. Right-click: it opens with its recipes. Only that table opens the station; every other table in the world stays normal.

Items

An ElementalArms item is an entry in a YAML file. Here is every field it can have, and what it really does.

Where they live

The plugin reads every .yml in items/ and in items/misc/. You can create new files with any name (for example items/boss-loot.yml). Each top-level key is one item, and that key is its ID: what you type in /ea give, in recipes and in drops.

A complete item, commented

Every field

The types

Translated names

The name and lore from the YAML can be overridden per language in lang/<language>.yml, in the items section. That way the same item is called Frost Blade in English and Hoja de Escarcha in Spanish without duplicating it:

Changing an item players already have

Every copy stores its stats inside. If you change the YAML, new copies get the new values, but old ones do not change by themselves. To update them, raise revision-id (for example from 1 to 2): when each player joins, their copies are rebuilt from the new YAML keeping their roll, upgrade, gems, durability and owner. In config.yml → item-revision.keep-data you decide whether enchantments, an anvil name and lore lines are kept too.

Included items

A fresh install ships 58 items ready to use or to copy as templates:

Tiers and rolls

The tier is the quality of a copy: it gives it a colour, a name and, above all, how good its numbers turn out.

The tiers it ships with

How a roll works

When a copy is generated, every stat is multiplied by a random number between its tier's min and max. Each stat rolls separately: a sword can come out with high damage and low crit. The result is rounded to two decimals and stored in the item forever.

Fixed, random or from a list

When it rolls

• With /ea give, when crafting a replaced vanilla recipe, at a station, in a drop from drops.yml or MythicMobs.
• When using a reforge stone: it re-rolls the stats within the same tier (the tier does not change).
• At the smithing table (diamond → netherite) the roll comes from the original copy, so removing and re-adding the ingot does not give a new one.

Creating or editing a tier

Save items/configurations/tiers.yml and use /ea reload. The tier name can also be translated in lang/<language>.yml → tier.

The 89 stats

Everything an item can give a player, with what it really does and its cap. You write them on the item under stats:.

How to write them

• Percentages: chance, bonus and resistance stats are written as whole numbers. 25 is 25%, not 2500%.
• Negatives: allowed. movement-speed: -0.02 on heavy armor makes you slower.
• Caps: the plugin clamps the stats that would break the game (dodge at 80%, resistances at 90%…). You can go over on the item, but the effect stops there.

Where they count

Every stat is added up from everything the player has equipped. Having the same thing twice counts twice.

Two kinds of stats

With an upgrade (+N) or the tier roll, every plugin stat grows; among attributes only damage, armor, armor-toughness, max-health and max-absorption grow.

⚔️ Offense (21)

🛡️ Defense (20)

🔥 Elemental resistances (12)

One per element: resist-fire, resist-water, resist-earth, resist-wind, resist-light, resist-dark, resist-poison, resist-holy, resist-lightning, resist-ice, resist-nature and resist-arcane. Each one removes that % of the damage of that element dealt to you, capped at 90%. In the editor they have their own menu (Elemental Resistances).

✨ Abilities and mana (10)

🧰 Utility (9)

🏃 Movement and exploration (17, vanilla)

All of them are Minecraft attributes: the number is added to the player's base. In brackets, the vanilla base so you know how much is a lot.

How a hit is calculated

The exact order in which ElementalArms decides how much damage a hit deals. If a number does not add up, this is where to look.

Melee hit with an ElementalArms weapon

1. Can they use it?If the player does not meet the requirements, the weapon is bound to another soul or its durability is 0 in UNUSABLE mode, the hit is cancelled.
2. Base damageThe weapon's damage (with its roll, upgrade and gems) + the damage from the rest of your gear (armor, accessories, set). All of it is scaled by the attack charge: spam-clicking hits less, and vanilla's falling crit, Sharpness and Strength still count.
3. Critcrit-chance (from all your gear) is rolled. If it hits, the physical part is multiplied by 1 + crit-damage/100. If the target is a player, their crit-resistance cuts the extra.
4. ElementsEach element from the weapon and the rest of your gear is added separately: damage × target weakness × charge × (1 + elemental-power) × (1 − the victim's resistance to that element).
5. MultipliersAll of the above is multiplied by 1 + the sum of: vs players/mobs, ranged/melee, undead, berserk, backstab, first strike and combo. Then execute multiplies separately if the target is low on health.
6. Victim's defenseIf the victim is a player: dodge-chance (minus your accuracy) and block-chance can cancel the hit; ranged/melee-resistance reduce it; defense (minus your armor-penetration) subtracts.
7. MinecraftVanilla armor, toughness, Protection and the Resistance effect apply on top of that number, as always.
8. Last safeguardsdamage-cap limits the hit and second-wind can save from death.
9. After the hitLifesteal, thorns, mana steal, double strike, ON_HIT / WHEN_DAMAGED abilities and durability use.

An example with numbers

A sword with damage: 8, crit-chance: 25, crit-damage: 50 and fire: 5. The player wears a ring with damage-vs-mobs: 20. They hit a mob weak to fire (fire=1.5) at full charge:

Other kinds of damage

The floating numbers

• White: weapon damage. Gold with CRIT!: a crit.
• Element colour: elemental damage. ▲ the target is weak to it, ▼ it resists it.
• Blue with ✦: ability damage. You will also see Dodge!, Block!, x2 and Second Wind!.

Turn them off with damage-indicators.enabled: false. With show-all: false they only show on hits with ElementalArms weapons. The texts are in lang/<language>.yml → indicator.

Elemental damage

Twelve elements that are added to hits. Mobs can be weak or resistant to each one, and players protect themselves with resistances.

1 · Giving an item elemental damage

In game: /ea editor → the item → Elemental Damage → click the element and type the number (0 removes it). It grows with upgrades (+8% per level).

2 · Making a mob weak or resistant

Weaknesses are set on MythicMobs mobs with the elementalWeakness mechanic. One number per element decides what it is:

The mechanic also answers to setWeakness and eaWeakness. The ▲ / ▼ marks show in the mob's health bar if health-bars.show-elements is on. Vanilla mobs have no weaknesses.

3 · Protecting players

Players do not use the mechanic: they use the resist-<element> stats on their gear (capped at 90%). And elemental-power raises all the elemental damage they deal.

Adding or renaming elements

Elements live in items/configurations/elements.yml (key: name with colour). If you add one (blood: '&4■ Blood'), it works in the editor, the MythicMobs mechanic and the health bar. Its player resistance would be resist-blood; add it to stats.yml too so it shows in the editor. The name per language is translated in lang/<language>.yml → elements.

Abilities

Effects an item casts by itself: on click, on hit, when damaged or on kill. There are 20 native ones, and you can use any MythicMobs skill.

Step by step: your first ability

1. Open the item/ea editor → category → the item → Item Abilities button (the fire charge).
2. Add itAdd Ability (the star) and pick one from the list. It is added with example values and its settings open.
3. Choose when it firesThe Triggered by lever cycles: right-click → left-click → on hit → when damaged → on kill.
4. Tune the numbersClick each setting (cooldown, chance, mana, damage…) and type the value in chat. remove puts it back to default.
5. SaveGo back to the editor and click Save Changes. If you do not save, it is lost on restart.

In the file

The 5 triggers

How clicks aim: the entity in your crosshair; if there is none, the block you look at; if you look at the air, the end of the ray. The reach is the largest range of the item's click abilities (30 by default) × ability-range.

The 20 native abilities

In brackets, the value used if you do not set it. radius: with a focused target only that target is affected; aiming at the air or a block, everything alive within that radius is affected.

MythicMobs skills

It is cast from the player, with the target if there is one. Trigger, cooldown, chance and mana work the same; damage settings go inside the MythicMobs skill. Without MythicMobs installed, the console warns and nothing happens.

Cooldowns, mana and consumables

• Cooldown: every ability on every item has its own. On clicks, the action bar says how long is left. cooldown-reduction shortens it (80% cap).
• Mana: with MMOCore, its mana is spent. Without MMOCore, ElementalArms' own mana: the maximum comes from your gear's max-mana and refills with mana-regen. A player without max-mana casts for free.
• If it fails: if the ability does not actually cast (for example a teleport with no free spot), it spends no mana and starts no cooldown.
• Consumables: with consumable: true, the item uses up one unit each time it casts a right-click ability (potions, scrolls).
• Vanilla use: if an item casts an ability on right-click, its normal use is cancelled (a pearl is not thrown, a potion is not drunk). Change it in abilities.cancel-vanilla-use.
• Requirements: if the player does not meet the item's requirements, it is bound to someone else or unidentified, nothing fires with any trigger.

Improving items

Four ways to improve an item you already have, all with the same gesture: pick up the stone with the mouse and click on the item in your inventory.

⬆️ Upgrade (+N)

• Each level adds 8% of the base stats (not compounding): +10 = +80%. Plugin stats, elemental damage and damage, armor, armor-toughness, max-health, max-absorption grow. Gems do not.
• The maximum is upgrade.max-level (10) or the item's max-upgrade. The level shows in the name: Excalibur (+3).
• upgrade.success-chance (100 by default) lets it fail: on failure the stone is used up and the level does not rise (it never drops).
• It works on everything except materials (MISC) and gems.

♻️ Reforge

Rolls every stat again with the range of its tier (the tier does not change). It can come out better… or worse. It only works on items with a tier. With reforge.keep-upgrade-level: true it keeps the +N.

◆ Gems and sockets

1. Give the item socketsmax-sockets: 2 in its file (or Gem Sockets in the editor). They show in the lore as empty ◇.
2. Create the gemAn item with type: GEM and its stats in gem-stats.
3. Socket itPick up the gem and click on the item. It fills one socket and its stats are added for good.

📜 Unidentified items

A drop with unidentified: true (in drops.yml) drops hidden: named ✦ Unidentified item, only its quality shows and it gives no stats, does not hit with them and casts no abilities. Click a scroll on it to reveal it, keeping the roll it already had.

Which item is which

All four are normal ElementalArms items (in items/misc/stones.yml and gems.yml). You can change how they look or use others: the ID that is consumed is set in config.yml (upgrade.stone-item, reforge.stone-item, identify.scroll-item). Any type: GEM item is a gem.

Durability, binding and requirements

The rules you can put on an item so it is not for anyone and does not last forever.

🔧 Custom durability

• It spends 1 point per melee hit with the item in hand. Abilities and bounces do not spend it.
• The item becomes unbreakable in vanilla terms and the lore shows Durability: 640/800. Below 15% (custom-durability.warn-below-percent) it warns.
• At 0, depending on custom-durability.on-zero: BREAK breaks and disappears; UNUSABLE stays but cannot hit, shoot or cast abilities.

🔒 Soulbound

• It binds to the first player who picks it up (soulbound.bind-mode: PICKUP) or uses it (USE). The lore says 🔒 Bound to Steve.
• Nobody else can pick it up, hit with it, wear it or cast its abilities (prevent-use-by-others), and its owner cannot drop it (prevent-drop).
• If the owner dies it drops like any item, but only they can pick it up again.

📋 Requirements

If they are not met, the player cannot attack with the item, use it or cast its abilities, and gets a warning. The lore lists them under Requirements:.

✋ Two-handed

hand-style: TWO_HANDED: while you hold it, whatever is in your off hand goes back to your inventory (or the ground if it does not fit), and /ea inventory locks the off hand and the shield.

Equipment, accessories and sets

/ea inventory puts everything you wear in one menu and adds 5 accessory slots. /ea stats adds it all up and tells you where each point comes from.

The equipment menu

• Drag your gear into its slot: each slot only accepts its own kind and tells you why if something does not fit.
• Minecraft limits: the elytra and the chestplate use the same real slot, as do the shield and the off hand. Only one of each pair can be filled; the other shows as locked with the reason.
• With a two-handed weapon, the off hand and the shield are locked.
• Accessories are saved with the player: they stay equipped after leaving and joining. Their stats and abilities (ON_HIT, WHEN_DAMAGED, ON_KILL) work while they are in their slot.

The character sheet

/ea stats (or the button in the equipment menu) shows your health, damage and protection at the top, and below that offense, defense and mobility with the gear / accessories / set breakdown of each stat. On the side, an icon with your total elemental damage, another with the rest of your plugin stats and another with the active set bonuses.

Armor sets

A set gives extra stats depending on how many of its pieces you wear. Bonuses stack: with 4 pieces you get the 2-piece and the 4-piece bonus.

1. Define the setIn items/configurations/sets.yml, with its piece thresholds.
2. Mark the piecesPut set: FROST on each armor piece (or Armor Set in the editor).
3. Reload/ea reload. When the pieces are put on, chat says ✦ Set active: Frost Guard (2).

How items are obtained

Three ways to make them: stations with their own recipes, the usual crafting table recipes and the smithing table.

🔨 Crafting stations

A station is a recipe menu placed on one exact block in the world, with a hologram and particles. Three come included: FORGE, ALTAR (arcane altar) and JEWELER.

1. Place the blockAny block works (a smithing table looks good for the forge).
2. Turn it into a stationLook at it (6 blocks or less) and type /ea station place FORGE.
3. Use itRight-click opens the recipes. While sneaking, the block works as normal. Each recipe shows the ingredients you have (green) and those missing (red).
4. Remove itLook at it and /ea station remove. They are saved in stations-placed.yml.

Creating a station

• The result comes with its tier roll: every craft is different.
• Ingredients are taken from the backpack and hotbar, never from worn armor or the off hand. A vanilla material does not accept an ElementalArms item of the same material.
• Up to 45 recipes per station. A recipe with an item that does not exist is skipped and the console warns.

🧱 Replaced vanilla recipes

With vanilla-crafting.replace-recipes: true, crafting a normal sword, axe, bow, shield or armor piece at the crafting table gives the ElementalArms version, with its roll. Netherite recipes are removed: netherite is obtained at the smithing table. Everything is decided in items/configurations/vanilla-recipes.yml:

⚒️ Smithing table

Netherite upgrade template + an ElementalArms diamond item + netherite ingot = its netherite version. It keeps the upgrade (+N), gems, owner, enchantments and an anvil name. The new roll is fixed for that item: removing and re-adding the ingot does not give another one.

The included diamond swords, axes and armor already know what to become. An ElementalArms item with no netherite version cannot be upgraded (so you do not lose the ingot on something that would stay diamond).

Mob and block drops

Make vanilla mobs and blocks drop ElementalArms items, with their roll, in items/configurations/drops.yml.

Anti-farming rules

• A block placed by a player drops nothing when broken (drops.ignore-placed-blocks), so an ore mined with Silk Touch cannot be placed and broken forever.
• If the block drops nothing with that tool (a diamond ore by hand), it does not drop the item either. Never in creative.
• Protected regions (WorldGuard and the like) are respected: if the break is cancelled, nothing drops.

MythicMobs drops

For MythicMobs mobs use their own drop table with the elementalarms drop (also eaItem or ea). It comes with tier and roll, just like from drops.yml:

The in-game editor

/ea editor creates and changes items with menus, without opening a single file. Everything you do here ends up written in items/.

1 · Categories

Inside a category, items are sorted by tier (COMMON to MYTHIC) and by ID, 45 per page. The Create New Item star (bottom right) creates a new one in that category.

2 · Creating an item

1. Type its IDNo spaces and not already taken (FROST_BLADE). It is created right away as stone, tier COMMON, in its category's file (items/sword.yml, items/misc/accessories.yml…).
2. Change the materialClick id and type a Minecraft material (DIAMOND_SWORD).
3. Fill in the restName, tier, stats, elements, abilities, lore… (see the menu below).
4. SaveSave Changes. Until you save, changes only exist in memory.

3 · An item's menu

4 · Configuring an ability

For each setting type a number, or remove so it uses its default. The list of settings of each ability is in Abilities.

Skill amplifiers

Skill Amplifiers has nothing to do with the item's abilities: it stores a bonus for skills of other plugins that read it through the API (ElementalArmsAPI.getSkillModifier). If no plugin uses it, it does nothing and the menu says so.

Health bars and visual effects

Everything you see without opening a menu: the bar above mobs, damage numbers, the glow of items on the ground and station holograms. None of it needs another plugin or is saved into your world.

💚 Health bar above mobs

It appears when you hit a mob and hides itself after 6 seconds. Below it shows the mob's elemental weaknesses (▲ and how much) and resistances (▼).

✨ Damage numbers

The numbers that pop up on hits. What each colour means: Combat.

🌟 Glow on the ground

An ElementalArms item lying on the ground glows with its tier's colour, so you can spot a legendary from afar. COMMON does not glow by default. Change it per tier with glow in tiers.yml (false, a colour like GOLD or a code '&6'; only the 16 Minecraft colours) and turn it all off with ground-glow.enabled: false.

🏷️ Station holograms

Every placed station has its floating text and particles, set in stations.yml (hologram and particles). See Crafting.

🖼️ Custom textures

custom-model-data: 1001 on an item uses model 1001 from your resource pack (ItemsAdder, Oraxen, Nexo or your own pack). Leather pieces are dyed with color. The ElementalArms resource pack (in your downloads panel) only adds the RPG frame of the equipment menu (texture-pack.enabled).

Commands and permissions

A single command, /ea (also /elementalarms and /earms). /ea help only shows what each player can use.

Permissions

Placeholders

With PlaceholderAPI installed they register by themselves. Use them in scoreboards, TAB, holograms or menus.

Integrations

ElementalArms works on its own. If you have any of these plugins, it detects them on startup and adds what they bring; there is nothing to turn on.

MythicMobs step by step

The file plugins/ElementalArms/MythicMobs-Example.yml has all of this commented. Summary:

More about weaknesses in Elements; about skills on items, in Abilities.

MMOCore

• requirements.level uses the MMOCore level instead of the experience level.
• requirements.class compares with the MMOCore class (its ID or name).
• Ability mana is taken from MMOCore mana; ElementalArms' own mana (max-mana) is no longer used.
• MMOCore does not give abilities to items: native abilities or MythicMobs do that.

config.yml, option by option

Every option with its default value. New options in each version are added to your file by themselves without touching what you changed.

General

Items

Systems

The other files

How the lore looks

In lore-formats.yml, the format list decides the order of the lore blocks: move the lines and the item is drawn in that order (a block you delete from the list is drawn at the end). entries decides how they look: titles, the format of each stat (stat_entry.crit-chance…), which stats show % (percent-stats) and the separator bar. Existing items are redrawn when their revision-id goes up.

Languages

Everything the player sees is in lang/en.yml and lang/es.yml: messages, menus, stat names, elements, tiers, abilities, and even each item's name and lore (items). Your changes are kept when updating and new keys are added by themselves. Another language? Copy en.yml as fr.yml, translate it and set language: fr; anything missing shows in English.

Updating from older versions

Replace the jar and restart. You do not need to delete anything or touch your files.

1. BackupSave the plugins/ElementalArms folder, just in case.
2. Replace the jarDelete the old jar from plugins/, put the new one and restart (not /reload).
3. DoneNew options appear in config.yml and in the language files. Players' items are rebuilt when they join if needed, keeping roll, upgrade, gems, durability, owner and enchantments.

1.2.0: IDs switch to English

Since 1.2.0 the items and stations that come with the plugin have English IDs. If you already had the plugin, it does not affect you: ElementalArms never overwrites your items/*.yml, stations.yml or drops.yml, so you keep the old IDs and everything works the same (the smithing table recognises both). Only a new install gets the new ones.

Developer API

To hook another plugin into ElementalArms. Add the jar as a compileOnly dependency and softdepend: [ElementalArms] in your plugin.yml. Everything is in com.infinity3113.elementalarms.api.ElementalArmsAPI.

Example: mana from your plugin

Damage from your skills

If your plugin deals damage on behalf of a player holding an ElementalArms weapon, mark the player with the ea:skill_damage metadata while you apply the damage. That way ElementalArms does not recalculate it as a weapon hit and treats it as ability damage.

Frequently asked questions

The most common questions, with a straight answer.

I changed an item and players still have the old one

Raise its revision-id (1 → 2). When players join, their copies are rebuilt keeping roll, upgrade and gems. Copies in chests update once the player carries them and joins again.

My MythicMobs mob's weakness does nothing

Two causes: the weapon has no elemental-damage (the weakness only multiplies elemental damage), or the mechanic is missing @self ~onSpawn.

An ability does not fire

Use /ea debug and try again: it tells you if it is on cooldown, the chance failed, mana is missing or the player does not meet the requirements. Remember that an unidentified item casts nothing and that ON_HIT comes from the weapon in hand or accessories, not armor.

CRIT! shows but the damage is the same

crit-damage is missing. crit-chance decides whether there is a crit; crit-damage decides how much harder it hits (50 = ×1.5).

A player has too many or too few hearts

/ea fix <player> clears set and accessory bonuses and applies them again. If it is still wrong, /ea fix <player> force removes every health modifier (including other plugins') and restores the base.

A mob's name shows twice

The normal name tag already hides itself. If it is a MythicMobs mob with its own Nameplate, turn it off at the mob's root (not inside Options), or set health-bars.show-name: false.

I do not want the crafting table to give ElementalArms items

vanilla-crafting.replace-recipes: false and restart. Or remove only the recipes you do not want from vanilla-recipes.yml.

Every smithing table opens the forge

You have stations.block-mode: ANY. With PLACED (the default) only blocks placed with /ea station place open it.

I hold a ring in my hand and it gives nothing

That is on purpose: accessories count in their /ea inventory slot, and armor when worn. In the hand they add nothing.

Get the item! gives me the item without a tier

That button gives the template, without a roll. An item with tier: RANDOM has no tier until it is generated: use /ea give.

The plugin disables itself

Check the console: empty or badly copied licence, licence used on two servers at once, or your host blocks the connection to infinity3113.mc-paradise.com for more than 48 hours.

My two-handed weapon removes my shield

That is what hand-style: TWO_HANDED does: it empties the off hand while you hold it. Change it to ONE_HANDED if you do not want that.

Version history

Every release and what changed in it.

Discussion

Comment and share your experience on each plugin version.

Player reviews

What server owners think of this plugin.