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 17+):

   java -version

2. Verify JAR is in correct folder:

   plugins/KyuubiSoftAchievements-X.X.X.jar  ✓
   plugins/KyuubiAchievements/KyuubiSoftAchievements-X.X.X.jar  ✗

3. Check for startup errors in server log

4. Ensure compatible Hytale server version

Missing Configuration Files

Symptoms:

• Config files not generated
• Errors about missing files

Solutions:

1. Ensure plugin loaded successfully
2. Check write permissions on plugins 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:

   /achievementadmin list YourName

   Verify all required achievements are unlocked.

2. Check trigger type matches action:

   • blocks_mined = Breaking blocks (not placing)
   • kills = Dealing final blow (not assists)

3. Check target matching:

   • Exact match: "Spider" only matches Spider
   • "any" matches everything
   • Prefix match: "Ore_" matches Ore_Iron, Ore_Gold, etc.

4. Verify count threshold:

   "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:

   "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 /achievements)
2. Check achievement is actually unlocked:

   /achievementadmin 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:

   "display": {
     "displayMode": "both"  ← Should include "nametag" or "both"
   }

2. Verify title is selected:

   • Open /titles
   • Check “Current Title” shows your title

3. Check title position:

   "display": {
     "titlePosition": "prefix"  ← Try different positions
   }

4. Restart/rejoin: Title updates may require reconnecting

Title Not in /titles Menu

Symptoms:

• Achievement unlocked but title not available

Solutions:

1. Verify achievement has title:

   "title": {
     "id": "my_title",
     "color": "#FFD700"
   }

2. Check title ID has translation:

   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:

   /lp info

2. Check prefix is set:

   /lp user YourName info

3. Verify prefix syntax:

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

   "notifications": {
     "enabled": true,
     "displayMode": "banner"  ← or "both"
   }

2. Check for HUD conflicts:

   • If another plugin uses Custom HUD, toasts are skipped
   • Install MHUD for compatibility

3. Check server logs for:

   Skipping toast - another plugin's HUD is active

“Failed to apply CustomUI HUD commands” Error

Symptoms:

• Client crash or disconnect
• Error in server log

Solutions:

1. Update to version 1.5.0+ (this bug was fixed)

2. Install MHUD for proper multi-HUD support

3. Check for conflicting plugins using Custom HUD

Multiple Toasts Not Showing

Symptoms:

• Only first toast shows
• Subsequent achievements missed

Solutions:

• This is expected behavior without MHUD
• Toasts queue but conflicts may skip them
• Install MHUD for reliable toast queuing

Performance Issues

Server Lag

Symptoms:

• Lag spikes when achievements unlock
• Slow UI loading

Solutions:

1. Increase save interval:

   "tracking": {
     "saveIntervalSeconds": 600  ← Increase from 300
   }

2. Disable unused tracking:

   "tracking": {
     "enableExploration": false  ← If not needed
   }

3. Reduce export frequency:

   "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:

   "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:

   plugins/KyuubiAchievements/playerdata/

3. Check disk space

4. Restore from backup if available

Duplicate Achievements

Symptoms:

• Same achievement shows multiple times
• Warnings in server log

Solutions:

1. Check for duplicate IDs:

   • Search achievements.json for duplicates
   • Check custom_achievements.json

2. Clear and regenerate:

   • Delete achievements.json
   • Restart server

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