MMO Skill Tree Integration

Complete integration with the MMO Skill Tree plugin for automatic skill-based achievements and XP rewards.

Overview

The Achievement System integrates with MMO Skill Tree to provide:

1. Automatic Skill Achievements - Plugin polls skill levels every 30 seconds and grants achievements
2. XP Bonus Rewards - Achievements can grant MMO Skill Tree XP as rewards
3. Conditional Loading - MMO achievements only load when MMO Skill Tree is installed

Key Features

• 121 new achievements across all 23 skills
• 98 new titles for skill mastery
• Fully automatic - No admin configuration required
• Soft dependency - Works without MMO Skill Tree installed
• Catch-up mechanism - Grants missed achievements on player join

---

How It Works

Automatic Tracking

┌─────────────────────────────────────────────────────────────┐
│  PLAYER JOIN                                                │
├─────────────────────────────────────────────────────────────┤
│  1. Fetch all skill levels via MMOSkillTreeAPI              │
│  2. Compare each skill level with milestones                │
│  3. Grant all reached achievements (catch-up)               │
│  4. Cache current levels                                    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  PERIODIC CHECK (every 30 seconds)                          │
├─────────────────────────────────────────────────────────────┤
│  For each online player:                                    │
│  1. Fetch current levels                                    │
│  2. Compare with cached levels                              │
│  3. On level-up → Check & grant achievements                │
│  4. Update cache                                            │
└─────────────────────────────────────────────────────────────┘

Conditional Loading

Server Start:
1. Achievement Plugin loads standard achievements
2. MMO Skill Tree integration is checked
3. If available: mmo_skills_achievements.json is loaded
4. SkillLevelTracker is activated

Without MMO Skill Tree:
- No MMO achievements in gallery
- No SkillLevelTracker active
- No performance cost

---

Setup

No Configuration Required!

The integration works fully automatically:

1. Install MMO Skill Tree plugin
2. Install Achievement plugin
3. Done!

The Achievement Plugin:

• Automatically detects if MMO Skill Tree is installed
• Loads MMO Skill achievements only when available
• Polls skill levels of all online players every 30 seconds
• Automatically grants achievements at reached milestones
• Catches up on missed achievements on player join

---

Supported Skills

MMO Skill Tree includes 23 skills across 4 categories:

Gathering Skills (5)

Skill	Description
Mining	Mining ores and stone
Woodcutting	Chopping trees
Excavation	Digging dirt and sand
Harvesting	Gathering crops
Fishing	Catching fish

Combat Skills (11)

Skill	Description
Swords	Sword combat
Daggers	Dagger combat
Polearms	Spear and polearm combat
Staves	Staff combat
Axes	Axe combat
Blunt	Mace and hammer combat
Archery	Bow and crossbow
Unarmed	Hand-to-hand combat
Defense	Damage reduction
Taming	Pet taming
Acrobatics	Dodge and fall damage

Crafting Skills (6)

Skill	Description
Crafting	General crafting
Repair	Item repair
Alchemy	Potion brewing
Enchanting	Enchantments
Cooking	Food preparation
Smithing	Metal working

Miscellaneous (1)

Skill	Description
Building	Construction

---

Achievement Structure

Per-Skill Achievements (23 Skills × 5 Levels = 115)

Level	Achievement ID	Difficulty	Title
10	{skill}_apprentice	Normal	-
25	{skill}_journeyman	Normal	Journeyman
50	{skill}_expert	Hard	Expert
75	{skill}_master	Hard	Master
100	{skill}_grandmaster	Epic	Grandmaster

Total Level Achievements (6)

Total Level	Achievement ID	Title
100	total_level_100	Adventurer
500	total_level_500	Veteran
1000	total_level_1000	Elite
1500	total_level_1500	Legend
2000	total_level_2000	Mythic
2300	total_level_max	Completionist

Category Mastery (Optional)

Achievement	Requirement	Title
gathering_master	All Gathering skills at 100	Gathering Master
combat_master	All Combat skills at 100	Combat Master
crafting_master	All Crafting skills at 100	Crafting Master

---

Titles

Skill Titles (4 per skill)

Level	Format	Example (Mining)	Color
25	{Skill} Journeyman	Mining Journeyman	#A0A0A0 (Gray)
50	{Skill} Expert	Mining Expert	#8B4513 (Brown)
75	{Skill} Master	Mining Master	#C0C0C0 (Silver)
100	Grandmaster {Skill}	Grandmaster Miner	#FFD700 (Gold)

Total Level Titles

Level	Title	Color
100	Adventurer	#90EE90 (Light Green)
500	Veteran	#4682B4 (Steel Blue)
1000	Elite	#9400D3 (Purple)
1500	Legend	#FF8C00 (Orange)
2000	Mythic	#DC143C (Crimson)
2300	Completionist	#FFD700 (Gold)

---

XP Rewards

Achievements can grant MMO Skill Tree XP as rewards using the mmo_xp reward type.

Configuration

{
  "type": "mmo_xp",
  "skill": "Mining",
  "amount": 5000
}

Field	Type	Description
type	string	"mmo_xp"
skill	string	Skill name or "all" for all skills
amount	number	XP amount to grant

Examples

Single Skill XP:

{
  "rewards": [
    { "type": "mmo_xp", "skill": "Mining", "amount": 5000 }
  ]
}

All Skills XP:

{
  "rewards": [
    { "type": "mmo_xp", "skill": "all", "amount": 1000 }
  ]
}

XP Reward in Total Level Achievements

{
  "id": "total_level_1000",
  "category": "mmo_skills",
  "iconItem": "Material_Gold_Ingot",
  "difficulty": "epic",
  "requires": "total_level_500",
  "title": { "id": "elite", "color": "#9400D3" },
  "trigger": { "type": "manual" },
  "rewards": [
    { "type": "mmo_xp", "skill": "all", "amount": 10000 }
  ]
}

---

Custom MMO Achievements

You can create custom achievements using the skill_level trigger type.

Trigger Configuration

{
  "trigger": {
    "type": "skill_level",
    "target": "MINING",
    "count": 50
  }
}

Field	Type	Description
type	string	"skill_level"
target	string	Skill name, "any", or "total"
count	number	Minimum level required

Target Options

Target	Description
"MINING"	Specific skill (use uppercase)
"any"	Any skill reaches the level
"total"	Total level (sum of all skills)

Example: Custom Achievement

{
  "id": "dual_master",
  "category": "mmo_skills",
  "iconItem": "Tool_Pickaxe_Diamond",
  "difficulty": "epic",
  "trigger": { "type": "manual" },
  "title": { "id": "dual_master", "color": "#FFD700" },
  "rewards": [
    { "type": "lootbag", "lootbagId": "legendary_hoard" },
    { "type": "mmo_xp", "skill": "all", "amount": 5000 }
  ]
}

---

Localization

Achievement Names

# Skill Achievements
achievements.name.mining_apprentice=Mining Apprentice
achievements.name.mining_journeyman=Mining Journeyman
achievements.name.mining_expert=Mining Expert
achievements.name.mining_master=Mining Master
achievements.name.mining_grandmaster=Grandmaster Miner

# Total Level
achievements.name.total_level_100=First Steps
achievements.name.total_level_500=Veteran Adventurer
achievements.name.total_level_1000=Elite Status
achievements.name.total_level_1500=Living Legend
achievements.name.total_level_2000=Mythic Being
achievements.name.total_level_max=The Completionist

Achievement Descriptions

achievements.desc.mining_apprentice=Reach Mining level 10
achievements.desc.mining_expert=Reach Mining level 50
achievements.desc.mining_grandmaster=Reach Mining level 100

achievements.desc.total_level_100=Reach a total skill level of 100
achievements.desc.total_level_max=Reach maximum total skill level (2300)

Titles

titles.name.mining_journeyman=Mining Journeyman
titles.name.mining_expert=Mining Expert
titles.name.mining_master=Mining Master
titles.name.grandmaster_miner=Grandmaster Miner

titles.name.adventurer=Adventurer
titles.name.veteran=Veteran
titles.name.elite=Elite
titles.name.legend=Legend
titles.name.mythic=Mythic
titles.name.completionist=Completionist

Reward Messages

achievements.reward.mmo_xp=+{amount} XP for {skill}!
achievements.reward.mmo_xp_all=+{amount} XP for all skills!

---

Troubleshooting

Achievements Not Appearing

1. Verify MMO Skill Tree is installed:

   Check plugins folder for MMOSkillTree.jar

2. Check server logs:

   Look for "MMO Skill Tree integration enabled"

3. Restart the server: Integration is checked on startup

XP Rewards Not Working

1. Check skill name spelling: Use exact skill names (e.g., "Mining", not "mining")

2. Verify MMO Skill Tree API: Check server logs for API errors

3. Test with admin command:

   /achievementadmin grant <player> total_level_100

Skill Level Not Updating

1. Wait for polling cycle: Levels are checked every 30 seconds

2. Force check on rejoin: Player disconnect/reconnect triggers catch-up

3. Check cached levels: Cache may be out of sync after server issues

---

Technical Details

API Integration

The plugin uses reflection to access MMO Skill Tree API:

// Level queries
MMOSkillTreeAPI.getLevel(store, ref, skillType)
MMOSkillTreeAPI.getTotalLevel(store, ref)
MMOSkillTreeAPI.getAllLevels(store, ref)

// XP manipulation
MMOSkillTreeAPI.addXp(store, ref, skillType, amount)

// Skill enumeration
MMOSkillTreeAPI.getSkillTypes()

Soft Dependency Pattern

The integration follows the same pattern as LuckPerms:

• Lazy initialization on first access
• Graceful fallback if not available
• No hard dependency in plugin.yml

Performance

• Polling interval: 30 seconds
• Per-player cost: Minimal (single API call)
• Cache strategy: Level changes only trigger checks
• No performance impact when MMO Skill Tree is not installed