# Troubleshooting

# Troubleshooting

Solutions for common issues with the Achievement & Title System.

## Installation Issues

### Plugin Not Loading

**Symptoms:**
- No log messages from plugin
- Commands not working

**Solutions:**
1. Check Java version (requires Java 25):
   ```bash
   java -version
   ```

2. Verify JAR is in correct folder:
   ```
   mods/KyuubiSoftAchievements-3.1.6.jar                            ✓
   mods/kyuubisoft_achievements/KyuubiSoftAchievements-3.1.6.jar    ✗
   ```

3. Make sure **KyuubiSoft Core** is installed (required; 3.1.6 needs Core 2.9.9 or newer)

4. Check for startup errors in server log

5. Ensure compatible Hytale server version (0.7.x)

### Missing Configuration Files

**Symptoms:**
- Config files not generated
- Errors about missing files

**Solutions:**
1. Ensure plugin loaded successfully
2. Check write permissions on the `mods/` folder
3. Restart server (not just reload)
4. Check for disk space issues

## Achievement Issues

### Achievements Not Unlocking

**Symptoms:**
- Progress updates but achievement doesn't unlock
- No notification when meeting requirements

**Solutions:**

1. **Check prerequisites:**
   ```bash
   /acadmin list YourName
   ```
   Verify all required achievements are unlocked. The detail panel of the book shows the requirements with met markers.

2. **Is the achievement disabled or "Special"?** Disabled achievements (admin window) are not counted. Achievements with the `manual` trigger only unlock by an admin grant.

3. **MMO skill levels:** only the milestones 10 / 25 / 50 / 75 / 100 and the total milestones are sent; other `skill_level` targets never unlock. The check view of the [admin window](./admin-panel#check-view) lists such problems.

4. **Check trigger type matches action:**
   - `blocks_mined` = Breaking blocks (not placing)
   - `kills` = Dealing final blow (not assists)

5. **Check target matching:**
   - Exact match: `"Spider"` only matches Spider
   - `"any"` matches everything
   - Prefix match: `"Ore_"` matches Ore_Iron, Ore_Gold, etc.
   - Wildcards: `"Snake_*"` matches every snake

6. **Verify count threshold:**
   ```json
   "trigger": {
     "type": "kills",
     "target": "Spider",
     "count": 50  ← Must reach exactly 50+
   }
   ```

### Progress Not Tracking

**Symptoms:**
- Progress stays at 0
- Actions not being counted

**Solutions:**

1. **Check tracking is enabled:**
   ```json
   "tracking": {
     "enableCombat": true,    ← Check these
     "enableProgression": true
   }
   ```

2. **Verify correct trigger type:**
   - Mining stone? Use `blocks_mined`
   - Crafting sword? Use `items_crafted`

3. **Check server logs for errors:**
   Look for tracking-related exceptions

### Hidden Achievement Stuck

**Symptoms:**
- Hidden achievement shows "???" even after unlocking

**Solutions:**
1. Refresh UI (close and reopen `/ksachievements`)
2. Check achievement is actually unlocked:
   ```bash
   /acadmin list YourName
   ```
3. Verify `hidden: true` is set in achievement definition

## Title Issues

### Title Not Showing on Nametag

**Symptoms:**
- Title selected but not visible
- Nametag shows only username

**Solutions:**

1. **Check display mode:**
   ```json
   "display": {
     "displayMode": "both"  ← Should include "nametag" or "both"
   }
   ```

2. **Verify title is selected:**
   - Open `/kstitles`
   - Check the active title at the top of the Titles tab

3. **Check title position:**
   ```json
   "display": {
     "titlePosition": "prefix"  ← Try different positions
   }
   ```

4. **KyuubiSoft Nameplates installed?** Then the title is shown as a nameplate tag of that mod, not in the nameplate text.

5. **Restart/rejoin:** Title updates may require reconnecting

### Title Not in the Titles Tab

**Symptoms:**
- Achievement unlocked but title not available

**Solutions:**

1. **Verify achievement has title:**
   ```json
   "title": {
     "id": "my_title",
     "color": "#FFD700"
   }
   ```

2. **Check title ID has translation:**
   ```properties
   achievements.title.my_title=My Title Name
   ```

## LuckPerms Issues

### Prefix Not Showing

**Symptoms:**
- LuckPerms prefix not appearing in chat
- Only achievement title shows

**Solutions:**

1. **Verify LuckPerms is installed:**
   ```bash
   /lp info
   ```

2. **Check prefix is set:**
   ```bash
   /lp user YourName info
   ```

3. **Verify prefix syntax:**
   ```bash
   # Correct
   /lp group admin meta setprefix 100 "<red>[Admin]</red> "

   # Wrong (missing space at end)
   /lp group admin meta setprefix 100 "<red>[Admin]</red>"
   ```

4. **Check server logs for:**
   ```
   [KyuubiSoft Achievements] LuckPerms integration enabled
   ```

### Colors Not Working

**Symptoms:**
- Prefix shows but without colors
- Raw tags visible: `<red>[Admin]</red>`

**Solutions:**

1. **Use correct MiniMessage syntax:**
   ```
   <red>Text</red>           ✓
   &cText                    ✓ (legacy)
   <#FF5555>Hex</end>        ✗ (wrong close tag)
   <#FF5555>Hex</#FF5555>    ✓
   ```

2. **Check for unclosed tags:**
   ```
   <bold><red>Text</red>     ✗ (missing </bold>)
   <bold><red>Text</red></bold>  ✓
   ```

## HUD/Toast Issues

### Toast Not Appearing

**Symptoms:**
- Achievement unlocks but no banner
- Only chat message shows

**Solutions:**

1. **Check notification settings:**
   ```json
   "notifications": {
     "enabled": true,
     "displayMode": "banner"  ← or "both"
   }
   ```

2. **The world map is open:** the HUD and toast hide while the map is open.

3. **HUD conflicts are no longer an issue:** since 3.0.0 every mod has its own HUD slot. If another mod or a window removed custom HUDs, the tracker is put back automatically. No extra HUD mod is needed.

4. **Toast shows lower than usual:** since 3.1.6 the toast appears right below the compass and shares those rows with the toasts of the other KyuubiSoft mods. It takes the highest free row and moves lower only while another toast is still on screen. This needs KyuubiSoft Core 2.9.9 or newer.

## Performance Issues

### Server Lag

**Symptoms:**
- Lag spikes when achievements unlock
- Slow UI loading

**Solutions:**

1. **Increase save interval:**
   ```json
   "tracking": {
     "saveIntervalSeconds": 600  ← Increase from 300
   }
   ```

2. **Disable unused tracking:**
   ```json
   "tracking": {
     "enableExploration": false  ← If not needed
   }
   ```

3. **Reduce export frequency:**
   ```json
   "export": {
     "intervalSeconds": 600
   }
   ```

### High Memory Usage

**Symptoms:**
- Memory increases over time
- OutOfMemoryError

**Solutions:**

1. **Check player data accumulation:**
   - Large number of unique players = more memory
   - Consider archiving old player data

2. **Reduce leaderboard size:**
   ```json
   "export": {
     "leaderboardSize": 50  ← Reduce from 100
   }
   ```

## Data Issues

### Lost Progress

**Symptoms:**
- Achievement progress reset
- Unlocked achievements missing

**Solutions:**

1. **Check for save errors in logs**

2. **Verify data file exists:**
   ```
   mods/kyuubisoft_achievements/players/<uuid>.json
   ```
   A broken player file is kept as `<uuid>.json.corrupt-<time>` and the `.bak` copy is loaded instead of empty data.

3. **Check disk space**

4. **Content lost after a save in the admin window?** Use **Undo last save** in the General settings page; every save keeps a backup set (last 20).

### Duplicate Achievements

**Symptoms:**
- Same achievement shows multiple times
- Warnings in server log

**Solutions:**

1. **Check for duplicate IDs:** the check view of the admin window lists them with **Go to**.

2. **Regenerate the standard file:** delete `configs/achievements.json` and restart; your entries in `custom/` stay.

## Getting Help

If none of the above solutions work:

1. **Check server logs** for detailed error messages

2. **Enable debug logging:**
   Set Java logging level to FINE for detailed output

3. **Gather information:**
   - Server version
   - Plugin version
   - Relevant config sections
   - Error messages from logs

4. **Report issue:**
   Create an issue with all gathered information