Skip to main content

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/achievements-all.jar  ✓
    plugins/achievements/achievements-all.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/achievements/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