Skip to content

Troubleshooting

Solutions for common issues with the Achievement & Title System.

Symptoms:

  • No log messages from plugin
  • Commands not working

Solutions:

  1. Check Java version (requires Java 25):

    Terminal window
    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)

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

Symptoms:

  • Progress updates but achievement doesn’t unlock
  • No notification when meeting requirements

Solutions:

  1. Check prerequisites:

    Terminal window
    /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 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:

    "trigger": {
    "type": "kills",
    "target": "Spider",
    "count": 50 ← Must reach exactly 50+
    }

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

Symptoms:

  • Hidden achievement shows ”???” even after unlocking

Solutions:

  1. Refresh UI (close and reopen /ksachievements)
  2. Check achievement is actually unlocked:
    Terminal window
    /acadmin list YourName
  3. Verify hidden: true is set in achievement definition

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 /kstitles
    • Check the active title at the top of the Titles tab
  3. Check title position:

    "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

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

Symptoms:

  • LuckPerms prefix not appearing in chat
  • Only achievement title shows

Solutions:

  1. Verify LuckPerms is installed:

    Terminal window
    /lp info
  2. Check prefix is set:

    Terminal window
    /lp user YourName info
  3. Verify prefix syntax:

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

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

Symptoms:

  • Achievement unlocks but no banner
  • Only chat message shows

Solutions:

  1. Check notification settings:

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

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
    }

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
    }

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).

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.

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