This is a massive update. Took several months to get to this point and there MAY be additional issues with outdated skills. If you catch bugs, please let us know.


Change Notes:

• Update InventoryFramework dependency for /hero menu for 1.21+
• Enhance item roll selection logic by validating player eligibility
  
• Edit AdminProfCommand.java to fix /hero admin prof
  
• Introduce EXPERTISE weapon and defense system (Akin to World of Warcraft)
• Update effect lib for Skills
  
• Modernize and update for 1.21 in various areas

READ MORE ON THE WIKI ABOUT NEW SYSTEMS


OPTIONAL EXPERTISE SYSTEM! Toggle on in config.yml

Weapon & Defense Expertise System
Overview
The Expertise System adds depth to combat by tracking your proficiency with different weapon types and your ability to defend against attacks. As you use weapons and take damage, you'll gain expertise that affects your combat effectiveness.

Key Features:

• Track expertise for 15+ different weapon types
  
  
• Build defense expertise by taking hits
  
  
• Land devastating EXPERT hits when your skill exceeds enemy defenses
  
  
• Suffer reduced damage from Glancing blows when under-skilled
  
  
• Face CRUSHING BLOWS from powerful mobs
  
  
• Class and race bonuses modify your expertise
  

Weapon Types
The system tracks expertise for the following weapon types:

Weapon Type

Examples

SWORD

Wooden Sword, Stone Sword, Iron Sword, Diamond Sword, Netherite Sword

AXE

Wooden Axe, Stone Axe, Iron Axe, Diamond Axe, Netherite Axe

BOW

Bow

CROSSBOW

Crossbow

MACE

Mace

UNARMED

Empty hand / fists

GREATHAMMER

Custom weapon (check with admins)

GREATAXE

Custom weapon (check with admins)

How Expertise Works
Gaining Expertise
Weapon Expertise:

• Gain weapon expertise by landing successful hits with that weapon type
  
  
• Each hit has a chance to increase your expertise by 1 point
  
  
• Requires 100–500 hits per point (randomized, configurable)
  
  
• Rate limited to prevent rapid grinding (max 1 point per minute by default)
  

Defense Expertise:

• Gain defense expertise by taking melee hits from enemies
  
  
• Each hit has a chance to increase your defense by 1 point
  
  
• Requires 100–500 hits per point (randomized, configurable)
  
  
• Rate limited to prevent rapid grinding (max 1 point per minute by default)
  

Expertise Caps
Your expertise is capped based on your primary class level: Maximum Weapon Expertise = Level × 5 Maximum Defense Expertise = Level × 5

Global Hard Cap: 400 points

So: Level 1, Weapon Expertise 0 → lots of glances, weak glancing hits. Level 1, Weapon Expertise 5 (cap) → almost no glances, strong hits. When you hit Level 2 (cap = 10), your current 5/10 is now 50% of cap: You still feel better than when you were 0/5, but not perfect. You get some glances again, but not as harsh as being completely unskilled.

### Default config
# ========================================
# Heroes Expertise System Configuration
# ========================================
# This file contains all settings for the weapon and defense expertise system.
# Expertise allows players to become more proficient with specific weapon types
# and improve their defensive capabilities through combat experience.

# Enable or disable the entire expertise system
enabled: true

# ========================================
# Weapon Types Configuration
# ========================================
# List of MMOItems weapon type IDs that should be tracked for expertise.
# Add or remove weapon types based on your server's MMOItems configuration.
# These are case-insensitive and will be matched against MMOItems type IDs.
weapon-types:
- FIST
- DAGGER
- SWORD
- THRUSTING_SWORD
- LONG_SWORD
- KATANA
- GREATSWORD
- AXE
- GREATAXE
- SPEAR
- LANCE
- HAMMER
- GREATHAMMER
- HALBERD
- WHIP
- BOW
- GREATBOW
- CROSSBOW
- MUSKET
- WAND
- STAFF
- GREATSTAFF
- LUTE

# ========================================
# Expertise Cap Settings
# ========================================
# These settings control the maximum expertise values players can achieve.

# Base weapon expertise cap per player level
# Example: At level 20 with base-cap-per-level of 5, max weapon expertise is 100
base-cap-per-level: 5

# Base defense expertise cap per player level
# Example: At level 20 with base-defense-cap-per-level of 5, max defense expertise is 100
base-defense-cap-per-level: 5

# Global maximum weapon expertise (hard cap regardless of level)
global-max-expertise: 400

# Global maximum defense expertise (hard cap regardless of level)
global-max-defense: 400

# ========================================
# Damage Modifiers
# ========================================
# These settings control how expertise affects damage output.

# Maximum bonus damage percentage from high expertise
# Example: 10.0 means up to +10% damage at max expertise
max-bonus-damage-percent: 10.0

# ========================================
# Glancing Blow System
# ========================================
# Glancing blows occur when attacking enemies with higher defense expertise.
# They reduce damage dealt based on the skill difference.

glancing:
# Chance of glancing blow by virtual level difference
# Virtual level = (expertise / base-cap-per-level)
# Format: level_diff: chance (0.0 to 1.0)
chance_by_virtual_level_diff:
0: 0.00 # No level difference = 0% glancing chance
1: 0.10 # 1 level difference = 10% glancing chance
2: 0.25 # 2 level difference = 25% glancing chance
3: 0.40 # 3 level difference = 40% glancing chance
4: 0.55 # 4+ level difference = 55% glancing chance

# Maximum virtual level difference to consider for glancing calculations
max_virtual_level_diff: 4

# Base damage multiplier for glancing blows (before penalties)
# Example: 0.70 means glancing blows deal 70% damage
base_multiplier: 0.70

# Maximum additional penalty for large skill differences
# Example: 0.40 means damage can be reduced by up to 40% more
max_penalty_extra: 0.40

# Maximum bonus damage reduction for high attacker skill
# Example: 0.20 means glancing penalty can be reduced by up to 20%
max_bonus_reduction: 0.20

# Divisor for normalizing skill differences in calculations
normalize_divisor: 20.0

# Minimum damage multiplier for glancing blows (floor)
min_multiplier: 0.10

# Maximum damage multiplier for glancing blows (ceiling)
max_multiplier: 0.95

# ========================================
# Normal Hit Scaling
# ========================================
# These settings control damage scaling for non-glancing hits.

normal-hit:
# Minimum damage multiplier at zero weapon expertise
# Example: 0.80 means 80% damage with no expertise
min_multiplier_at_zero_skill: 0.80

# Maximum damage multiplier at expertise cap
# Example: 1.00 means 100% damage at max expertise
max_multiplier_at_cap: 1.00

# ========================================
# Expertise Gain Settings
# ========================================
# These settings control how players gain weapon expertise through combat.

gain:
# Enable or disable expertise gain
enabled: true

# Minimum hits required to gain 1 expertise point
min-hits-per-point: 1

# Maximum hits required to gain 1 expertise point
max-hits-per-point: 40

# Randomize the required hits within the min-max range
# If false, always uses max-hits-per-point
randomize-within-range: true

# Maximum expertise points that can be gained per minute (rate limiting)
# Prevents rapid expertise farming
max-points-per-minute: 1

# ========================================
# Defense Expertise Gain Settings
# ========================================
# These settings control how players gain defense expertise by taking damage.

defense-gain:
# Enable or disable defense expertise gain
enabled: true

# Minimum hits taken to gain 1 defense expertise point
min-hits-per-point: 1

# Maximum hits taken to gain 1 defense expertise point
max-hits-per-point: 40

# Randomize the required hits within the min-max range
# If false, always uses max-hits-per-point
randomize-within-range: true

# ========================================
# UI Feedback Settings
# ========================================
# These settings control visual and audio feedback for the expertise system.

ui:
# Sound effect for glancing blows (dull hits)
dull-hit-sound:
# Enable or disable the sound effect
enabled: true

# Bukkit Sound enum name
sound: ITEM_SHIELD_BLOCK

# Volume (0.0 to 1.0)
volume: 0.4

# Pitch (0.5 to 2.0)
pitch: 0.8

# Cooldown between sound plays in milliseconds
# Prevents sound spam
cooldown-ms: 800

# ========================================
# Auto-Save Settings
# ========================================
# These settings control how often expertise data is saved to the database.
# Expertise data is always saved when players log out or the server shuts down.
# This auto-save provides additional protection against data loss from crashes.

# Interval in minutes between automatic saves of dirty player data
# Lower values = more frequent saves = less potential data loss but more database load
# Higher values = less frequent saves = more potential data loss but less database load
# Recommended: 5-10 minutes for most servers
auto-save-interval-minutes: 5

# ========================================
# Swing Softening System
# ========================================
# Swing softening reduces the vanilla attack cooldown penalty on early swings.
# This is applied AFTER all expertise calculations (glancing, expert, crushing, etc.)
# to slightly buff damage when attacking before the weapon is fully charged.
#
# EXPERTISE GATING:
# - Only applies when your weapon expertise EXCEEDS the defender's defense expertise
# - If your expertise <= defender's defense: NO softening (vanilla penalty stays)
# - Higher expertise advantage = stronger softening effect
#
# The vanilla cooldown system remains active - this just softens its impact.
# Only applies to melee white attacks (normal left-click hits) where expertise is enabled.
#
# SCALING:
# - 20+ point expertise advantage: Full softening benefit (min-factor applies)
# - 10 point advantage: 50% softening benefit
# - 0 point advantage (equal): NO softening
# - Negative (disadvantage): NO softening
#
# DAMAGE BOOST EXAMPLES (with min-factor: 0.5):
# - 0% cooldown + full advantage: 2x damage (50% boost)
# - 50% cooldown + full advantage: 1.33x damage (33% boost)
# - 100% cooldown: 1x damage (no change, regardless of expertise)

swing-soften:
# Enable or disable swing softening
enabled: true

# Minimum softening factor (applied at 0% cooldown with full expertise advantage)
# Lower values = bigger buff on early swings
# Example: 0.5 means at 0% cooldown with 20+ expertise advantage, damage is divided by 0.5 (2x = 50% boost)
# 0.67 means at 0% cooldown with 20+ expertise advantage, damage is divided by 0.67 (1.5x = 33% boost)
# At 100% cooldown, damage is always divided by 1.0 (no change)
# Range: 0.5 to 1.0 (0.5 = 50% boost, 0.67 = 33% boost, 0.8 = 25% boost)
min-factor: 0.01

# ========================================
# Debug Settings
# ========================================
# These settings are for debugging and performance monitoring.

debug:
# Enable debug logging
enabled: false

# Log a warning if expertise calculations take longer than this (in milliseconds)
performance-warning-threshold-ms: 1

# ========================================
# Crushing Blow System (Mob Attacks on Players)
# ========================================
# Crushing blows are the reverse of glancing blows - when mobs attack players
# with lower defense expertise, they can deal increased damage.

crushing:
# Enable or disable crushing blows
enabled: true

# Weapon skill per mob level (used to calculate mob "expertise")
weapon-skill-per-level: 5

# Base chance for crushing blow (percentage)
base-chance-percent: 5.0

# Additional chance per skill point difference (percentage)
chance-per-skill-point-percent: 0.5

# Maximum crushing blow chance (percentage)
max-chance-percent: 40.0

# Damage multiplier for crushing blows
# Example: 1.5 means crushing blows deal 150% damage
damage-multiplier: 1.5

# Minimum skill difference required for crushing blows
min-skill-diff-for-crushing: 5

# Only allow crushing blows on players (not on other mobs)
only-on-players: true

# Only allow crushing blows from MythicMobs (not vanilla mobs)
only-from-mythicmobs: false