# RPG Leveling Integration

# RPG Leveling Integration

The Achievement Plugin integrates with the **RPGLeveling** plugin to provide achievements based on character level, total XP, and mob kills.

## Overview

**Features:**
- **Character Level Achievements** - Unlock achievements at level milestones (5, 10, 25, 50, 75, 100)
- **XP Milestones** - Track total XP earned (1,000 / 10,000 / 100,000)
- **Mob Kill Achievements** - Track kills for specific mob types (Trork, Skeleton, Zombie, Scarak, Goblin)
- **Soft Dependency** - Works without RPGLeveling installed (achievements just won't trigger)

## How It Works

### Soft Dependency

The integration uses reflection to avoid a hard dependency on RPGLeveling. If RPGLeveling is not installed, the integration simply won't activate - no errors, no crashes.

### Polling-Based Tracker

The `RPGLevelTracker` polls player data periodically to detect level/XP changes:
- Checks every 5 seconds for level/XP changes
- Compares with cached values
- Triggers achievements when thresholds are reached

---

## Trigger Types

### `rpg_level` - Character Level

Triggers when the player reaches a specific character level.

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

### `rpg_xp` - Total XP

Triggers when the player accumulates a total amount of XP.

```json
{
  "trigger": {
    "type": "rpg_xp",
    "target": "any",
    "count": 100000
  }
}
```

### `kills` - Mob Kills

Triggers when the player kills a specific number of a mob type.

```json
{
  "trigger": {
    "type": "kills",
    "target": "Trork",
    "count": 100
  }
}
```

---

## Default Achievements

### Level Milestones

| ID | Level | Title | Difficulty |
|----|-------|-------|------------|
| `rpg_level_5` | 5 | - | Easy |
| `rpg_level_10` | 10 | Adventurer | Normal |
| `rpg_level_25` | 25 | Veteran | Normal |
| `rpg_level_50` | 50 | Elite | Hard |
| `rpg_level_75` | 75 | Champion | Hard |
| `rpg_level_100` | 100 | Legend | Epic |

### XP Milestones

| ID | XP Required | Title | Difficulty |
|----|-------------|-------|------------|
| `rpg_xp_1000` | 1,000 | - | Easy |
| `rpg_xp_10000` | 10,000 | - | Normal |
| `rpg_xp_100000` | 100,000 | XP Hunter | Hard |

### Mob Kill Chains

Each mob type has a kill chain: 10 → 50 → 100 → 500 → 1000

#### Trork Chain
| ID | Kills | Title |
|----|-------|-------|
| `trork_slayer_10` | 10 | - |
| `trork_slayer_50` | 50 | - |
| `trork_slayer_100` | 100 | Trork Hunter |
| `trork_slayer_500` | 500 | Trork Slayer |
| `trork_slayer_1000` | 1000 | Trork Bane |

#### Skeleton Chain
| ID | Kills | Title |
|----|-------|-------|
| `skeleton_slayer_100` | 100 | Bone Collector |
| `skeleton_slayer_500` | 500 | Undead Hunter |
| `skeleton_slayer_1000` | 1000 | Skeleton Bane |

#### Zombie Chain
| ID | Kills | Title |
|----|-------|-------|
| `zombie_slayer_100` | 100 | Zombie Hunter |
| `zombie_slayer_500` | 500 | Zombie Slayer |
| `zombie_slayer_1000` | 1000 | Zombie Bane |

#### Scarak Chain
| ID | Kills | Title |
|----|-------|-------|
| `scarak_slayer_100` | 100 | Bug Squasher |
| `scarak_slayer_500` | 500 | Scarak Slayer |
| `scarak_slayer_1000` | 1000 | Scarak Bane |

#### Goblin Chain
| ID | Kills | Title |
|----|-------|-------|
| `goblin_slayer_100` | 100 | Goblin Hunter |
| `goblin_slayer_500` | 500 | Goblin Slayer |
| `goblin_slayer_1000` | 1000 | Goblin Bane |

---

## Custom Achievements

Create `custom/custom_rpg_leveling_achievements.json`:

```json
{
  "configVersion": 3,
  "achievements": [
    {
      "id": "rpg_level_150",
      "category": "rpg_leveling",
      "iconItem": "Weapon_Sword_Adamantite",
      "difficulty": "epic",
      "requires": "rpg_level_100",
      "title": { "id": "transcendent", "color": "#FF00FF" },
      "trigger": { "type": "rpg_level", "target": "150", "count": 1 },
      "rewards": [
        { "type": "item", "itemId": "Ingredient_Bar_Gold", "amount": 100 }
      ]
    }
  ]
}
```

---

## Localization Keys

Add to your language files in `localization/`:

```json
{
  "achievements.ui.filter_rpg_leveling": "RPG Leveling",
  "achievements.trigger.rpg_level": "Reach Character Level {0}",
  "achievements.trigger.rpg_xp": "Collect {0} XP total",

  "achievements.name.rpg_level_5": "First Steps",
  "achievements.desc.rpg_level_5": "Reach Character Level 5",
  "achievements.name.rpg_level_10": "Rising Hero",
  "achievements.desc.rpg_level_10": "Reach Character Level 10",
  "achievements.name.rpg_level_25": "Seasoned Warrior",
  "achievements.desc.rpg_level_25": "Reach Character Level 25",
  "achievements.name.rpg_level_50": "Elite Fighter",
  "achievements.desc.rpg_level_50": "Reach Character Level 50",
  "achievements.name.rpg_level_75": "Champion",
  "achievements.desc.rpg_level_75": "Reach Character Level 75",
  "achievements.name.rpg_level_100": "Living Legend",
  "achievements.desc.rpg_level_100": "Reach Character Level 100",

  "achievements.title.adventurer": "Adventurer",
  "achievements.title.veteran": "Veteran",
  "achievements.title.elite": "Elite",
  "achievements.title.champion": "Champion",
  "achievements.title.legend": "Legend",
  "achievements.title.xp_hunter": "XP Hunter"
}
```

---

## Files

| File | Location | Description |
|------|----------|-------------|
| `rpg_leveling_achievements.json` | `configs/` | Default achievement definitions |
| `custom_rpg_leveling_achievements.json` | `custom/` | Custom achievements (optional) |

---

## Activation

The integration is automatically activated on plugin startup if RPGLeveling is detected:

- Plugin checks for RPGLeveling on startup
- If found, the `RPGLevelTracker` is started
- Achievements from `configs/rpg_leveling_achievements.json` are loaded
- Custom achievements from `custom/custom_rpg_leveling_achievements.json` are merged

**Without RPGLeveling:**
- No error messages
- RPG Leveling achievements won't appear in the book
- No performance impact

---

## Troubleshooting

### Achievements Not Triggering

1. **Verify RPGLeveling is installed:**
   Check your plugins folder for RPGLeveling

2. **Check server logs:**
   Look for "RPGLeveling integration activated" message

3. **Verify player level:**
   Use RPGLeveling commands to check current level

### Mob Kills Not Counting

1. Ensure the mob type matches exactly (case-sensitive)
2. Check that the kill was registered by RPGLeveling
3. Wait for the next polling cycle (5 seconds)

### Custom Achievements Not Loading

1. Check JSON syntax is valid
2. Verify `configVersion: 2` is set
3. Check server logs for loading errors