# MMO Skill Tree Integration

# 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](https://github.com/ziggfreed/MMOSkillTree) 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 the book
- 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}_10` (e.g. `mining_10`) | Normal | - |
| 25 | `{skill}_25` | Normal | Journeyman |
| 50 | `{skill}_50` | Hard | Expert |
| 75 | `{skill}_75` | Hard | Master |
| 100 | `{skill}_100` | 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_2300` | 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

```json
{
  "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:**
```json
{
  "rewards": [
    { "type": "mmo_xp", "skill": "Mining", "amount": 5000 }
  ]
}
```

**All Skills XP:**
```json
{
  "rewards": [
    { "type": "mmo_xp", "skill": "all", "amount": 1000 }
  ]
}
```

### XP Reward in Total Level Achievements

```json
{
  "id": "total_level_1000",
  "category": "mmo_skills",
  "iconItem": "Ingredient_Bar_Gold",
  "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

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

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `"skill_level"` |
| `target` | string | `SKILL:LEVEL` (skill in upper case) or `total:LEVEL` |
| `count` | number | `1` |

### Target Options

| Target | Description |
|--------|-------------|
| `"MINING:50"` | The skill reached this level. Only the milestones 10, 25, 50, 75 and 100 are sent |
| `"total:1000"` | The total level (sum of all skills) reached this value. Only 100, 500, 1000, 1500, 2000 and 2300 are sent |

:::caution
A level that is not a milestone never unlocks. The check view of the [admin window](./admin-panel#check-view) warns about such targets.
:::

### Example: Custom Achievement

```json
{
  "id": "dual_master",
  "category": "mmo_skills",
  "iconItem": "Tool_Pickaxe_Adamantite",
  "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

```properties
# 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

```properties
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

```properties
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

```properties
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:**
   ```
   /acadmin 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:

```java
// 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
- Optional dependency in the mod manifest (no hard dependency)

### 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