# Changelog

# Changelog

## Version 3.1.7 - Guild Triggers (2026-11-10)

Not released yet and not tested in game.

### New

- **Guild triggers for KyuubiSoft Guilds.** The trigger catalog in the admin editor has a new group "Guilds": join a guild, found a guild, guild level (the level as target), lock chests or doors for the guild, and contribute materials to the guild (item, prefix, wildcard or any). Admins can build their own achievements on them; no shipped achievement uses them. Joining and founding count once per player, each locked spot counts once, and the guild level also unlocks for members who join or log in after the guild reached it.
- **Guild experience for achievements.** With KyuubiSoft Guilds, every unlocked achievement also gives the player's guild experience, within the guild's daily limit per member.
- **Check view.** The check shows a warning while KyuubiSoft Guilds is not running, because guild achievements would never unlock then; locking at new spots is marked as repeatable.

## Version 3.1.6 - Design & Feature Update (2026-11-09)

Release of the Design & Feature Update. It sums up the changes since 2.10.5.

### New

- **New achievement book.** `/ksachievements`, `/kstitles`, `/ksrewards` and the Achievement Book item open one book with an overview, your categories with search, filters and sorting, and a detail panel with progress, requirements, rewards and the title. Achievement chains show as one line with a stage path.
- **Rarity and secrets.** Each achievement shows how many players have it and who got it first; `display.showRarity` and `display.showServerFirst` switch this off. Hidden achievements stay "???" until unlocked, with an optional hint that admins add as `achievements.hint.<id>` in `localization/custom_<lang>.json`.
- **Titles and Rewards tabs.** Choose your title with a chat and nameplate preview; with KyuubiSoft Nameplates the title shows on your nameplate. Collect one reward, the rest or all at once and open lootbags; after joining, a hint tells you when rewards are waiting.
- **New tracker and unlock toast.** Up to 3 tracked achievements sit on the left edge of the screen, below the pet HUD, and one toast below the compass shows the achievement, points, title and reward together. Players change the tracker in the book's settings or in `/kssettings`.
- **Achievements admin window.** Admins with `ks.achievements.admin` open it with `/acadmin panel` or from the `/ksadmin` hub. Every change stays a draft until "Save", each save keeps a backup, and "Undo last save" brings the previous state back.
- **Edit every achievement in the game.** Change shipped achievements without copying them; players keep their progress, and "Reset to default" removes your change. Create achievements from templates, add stages to chains, edit categories and titles, and switch achievements off without losing player data.
- **Editor and check view.** Texts in every language, a trigger catalog with farming warnings, prerequisites, title, rewards and a list of everything that uses an achievement before you rename or delete it; renaming can keep player progress. The check view finds problems and jumps to them.
- **Players tool and statistics.** Unlock, revoke or reset achievements and set progress, points, rewards and titles for online and offline players; every action is logged and can be reverted. `/acadmin grant` and `revoke` work the same way, and statistics show the rarest achievements, server firsts and top points.
- **New triggers.** Dungeon runs with KyuubiSoft Dungeons 4.4.2 or newer (any dungeon, per biome, per rarity, without dying), wildcards in targets such as `Snake_*`, and `items_collected` (the most of an item held at once).

### Changed

- **One message per unlock.** Achievement, points, title and reward arrive together in one chat line or toast, in each player's own language. Players pick their language once in `/kssettings` for every KyuubiSoft mod.
- **Revoking takes back.** Revoking an achievement removes its points and the rewards that were not collected yet.
- **Settings that work.** `notifications.showRewardsInBanner`, `notifications.broadcastFormat` and the `tracking.*` switches had no effect and now work. Points per difficulty can be set with `points.easy` to `points.legendary`; the defaults are the old values.
- **Fixed tracker place.** The tracker position can no longer be changed, so the HUDs of the KyuubiSoft mods no longer overlap. Saved positions and `trackerHud.position` are ignored.
- **Optional and special achievements.** Achievements for optional skill or level mods only show when such a mod is installed. About 80 "Special" achievements (animals, fishing, farming, deaths, secrets) cannot be earned by playing yet.
- **Green Achievement Book.** The book item is now green instead of blue, so it is easy to tell apart from the Quest Book.

### Fixed

- **Achievements that could never unlock.** The wood achievements (chopped logs count now), wildcard targets, `items_collected`, `welcome` and Dungeon Diver now unlock with their titles, points and rewards.
- **No doubled rewards.** Item rewards with a full inventory are no longer handed out twice, a lootbag is rolled only once, and rewards are saved right after you collect them.
- **Your files are safe.** A broken player file falls back to its backup copy. Editing while `custom_achievements.json` had an error deleted all other custom achievements, and a broken `config.json` was replaced with defaults; unreadable files are never overwritten now.
- **Correct counting.** "Any block" achievements no longer count twice, playtime no longer loses about 10 %, creative mode counts for no achievement, and an achievement whose id equals a trigger type no longer takes that trigger's progress away from the others.
- **Admin tools stay with admins.** The `showcase_achievements` NPC opened the admin panel for every player; it now needs `ks.achievements.admin`.
- **Small fixes.** Hidden achievements no longer show through chains, the search or the tracker, titles keep a stable order, the tracker hides while the world map is open, and `/kslang` without an argument answers in chat.

### Before you update

- Update KyuubiSoft Core to 2.9.9 or newer first.
- Admins who add or change command rewards that run as the server console need `ks.core.admin.dialog.console`. New command rewards run as the player.
- The shipped `configs/achievements.json` is replaced by a new version and the old file is kept as a backup. If you changed standard achievements in that file, redo the changes in the admin window.

## Version 3.1.1 - Playtest Fix (2026-10-28)

### Fixed

- **Item picker in the admin window:** "Choose" (for example Settings › Points & book, or reward items) opened the item picker without a background, so the page behind showed through. It now opens as a framed window over a dimmed backdrop.

## Version 3.1.0 - New Admin Window (2026-10-27)

Needs KyuubiSoft Core 2.9.2 for live lootbag updates. Not tested in game yet.

### New: admin window

One admin window in the KyuubiSoft "Goldfiligran" look replaces the old admin panel (`/acadmin panel`, the `/ksadmin` hub, the `showcase_achievements` NPC). Every change is a draft until **Save**. See [Admin Window](./admin-panel).

- **Navigation** in three groups (content, players, settings), a global search and a footer with the list of changes (each can be reverted), Discard and Save.
- **Saving:** errors block saving and open the check view; warnings don't. Every save makes a backup set (last 20 kept), writes atomically, rolls back on failure and applies at once. Conflicts with another admin ask "Save anyway?"; other changes are merged. **Undo last save** loads the previous state as a draft.
- **Standard achievements can be edited without copies:** a change is stored as an override with the same id, so players keep their progress and titles. **Reset to default** removes it.
- **Achievement list and editor:** chains as one row, filters, templates, copies, "Add stage", texts per language, a trigger catalog with abuse hints, prerequisites, titles, rewards with item and lootbag pickers, a book preview, an impact preview and references before deleting or renaming. Rename with "keep progress" moves player data, also for offline players.
- **Check view** for duplicate ids, missing prerequisites, cycles, unknown items, lootbags or skills, ids equal to a trigger type, `skill_level` targets that never fire and abuse-prone triggers with rewards.
- **Categories** (name per language, icon, order, rename, delete when empty) and **Titles** (colour, granting achievements, unlock count, wearers).
- **Disable achievements:** not shown, counted or tracked; player data stays.
- **Players tool** for online and offline players: unlock, revoke, reset, set progress, points ±, deliver or remove waiting rewards, set or remove titles. Offline actions run at the next login; every action is logged and can be reverted.
- **Statistics:** rarest and never reached achievements, server firsts, achievements that cannot count on this server, top points, waiting rewards.
- **Settings** in five pages; the server language moved to `/kssettings`.
- On a showcase server visitors can browse the window read-only.

### Changed

- Every way into the admin window and every action checks `ks.achievements.admin`. The old `achievements.admin` node never had an effect and is gone.
- Command rewards that run as the console need `ks.core.admin.dialog.console` to be added, changed or removed (editor, save and web editor import). New command rewards run as the player.
- `/acadmin grant` and `revoke` go through the players tool (logged, also for offline players). Player names are matched exactly; an ambiguous offline name asks for the UUID. `simulate` is capped at 10,000.
- A reload also reloads lootbags. With Core 2.9.2 changed and removed lootbags apply at once, with older Core after a restart. Autosave and export intervals apply without restart.
- New optional config fields `categoryOrder`, `categoryIcons` and `disabledAchievements`. Points, rewards and prices are unchanged.
- Localization version 15.

### Fixed

- Editing an achievement while `custom_achievements.json` had a syntax error deleted all other custom achievements; an unreadable file is now never overwritten. The same for an unreadable `config.json`.
- Custom MMO and RPG Leveling achievements were saved to the wrong file; deleting them did nothing.
- Duplicate ids were saved without effect; they are now reported.
- The `/ksadmin` hub opened the window without `ks.achievements.admin`.
- An achievement whose id equals a trigger type took over that trigger's counter from all other achievements of the type.

---

## Version 3.0.1 - KS Settings Page (2026-10-21)

- The tracker options (on/off, progress, auto-track next, hide when empty, number of achievements, position) also appear in KyuubiSoft Core's shared settings window `/kssettings`. Changes apply at once.
- The language line in the book settings opens the KS settings language page; one choice applies to all KyuubiSoft mods. The language system follows the server's default player language and the "players may choose" switch (Core 2.8.0).
- The `/ksadmin` hub entry shows the real version.
- A tracker HUD shown while the world map is open now starts hidden.
- Localization version 14.

---

## Version 3.0.0 - New Achievement Book (2026-10-21)

Needs KyuubiSoft Core 2.7.3. KyuubiSoft Dungeons 4.4.2 is needed for the Dungeon Diver achievements. Not tested in game yet.

### New

- **Achievement book** in the "Goldfiligran" look: one window for `/ksachievements` (overview), `/kstitles` (titles), `/ksrewards` (rewards), the Achievement Book item and the showcase gallery NPC. See [Achievement Book](./ui-pages).
- Overview with tiles, category progress, "Next title", "Almost done" and "Recently unlocked".
- Category tabs with search, filters and sorting; chains as one line with the current stage; a detail panel with stage path, requirements, rewards, title, share of players and server first.
- Rarity per achievement and server first (options `display.showRarity`, `display.showServerFirst`).
- Hidden achievements stay "???" everywhere until unlocked; optional hints `achievements.hint.<id>`.
- Titles tab with chat and nameplate previews; Rewards tab with partial collects, "Collect all" and history. See [Rewards](./rewards-ui).
- "Rewards waiting" hint after join (`notifications.pendingRewardHint`).
- New tracker HUD (up to 3 cards) and one unlock toast that bundles achievement, points, title and reward hint. See [Tracker HUD](./tracker-hud).
- Points per difficulty configurable (`points.*`, defaults unchanged).
- `items_collected` now counts (the most of an item held at once).
- Dungeons triggers `dungeon_complete_any`, `dungeon_complete_<biome>`, `dungeon_rarity_<rarity>`, `dungeon_no_death`.
- Wildcards in trigger targets (`Snake_*`).
- KyuubiSoft Nameplates support: the active title becomes a nameplate tag.
- New options are written into an existing `config.json` with their defaults.

### Changed

- One notification per unlock; `notifications.displayMode` defaults to `banner` on new installs.
- All texts use the player's language, including item names and dates.
- Lootbags use one registry (KyuubiSoft Core); standard lootbag file version 4 adds `copper_tools`.
- Revoking takes back the points, drops rewards not collected yet, and "total" achievements need their full count again.
- MMO Skill Tree and RPG Leveling achievements are only shown and counted when those mods are installed.
- Several options now really work: `notifications.showRewardsInBanner`, `notifications.broadcastFormat`, `trackerHud.position`, the `tracking.enable*` switches, `export.includePlayerTotals`, `showRequires`.
- Web editor translation edits go to `localization/custom_<lang>.json`.
- Standard achievements file version 4 (the old file is backed up, custom entries move to `custom/`).
- Tracker positions are six presets; old saved positions move to the nearest one.

### Fixed

- The `showcase_achievements` NPC opened the admin panel for every player.
- Item rewards with a full inventory no longer duplicate items on the next collect.
- Lootbags are rolled once and saved; a relog no longer re-rolls them.
- A broken player file falls back to the `.bak` copy instead of empty data; saves are atomic and rewards are saved right after collecting.
- Wood achievements count chopped logs; "any block" achievements no longer count twice; playtime no longer loses seconds; creative mode is ignored for totals too; `welcome` is reachable.
- Hidden achievements no longer leak through chains, search or auto-tracking.
- Stable title order; `AchievementAPI.setActiveTitle` and the progress listeners work.
- Many thread-safety and translation fixes.

### Removed

- The old gallery, title selection, rewards page, settings page, lootbag page and the unregistered `/kslootbags`, the old tracker HUD and toast.

### Not yet

- The 80 `manual` achievements (husbandry, fishing, farming, deaths, easter eggs) still have no trackers; they show as "Special".
- No anti-farming rules for place/break, chat, AFK playtime or alt kills.

---

## Version 2.10.x - Hytale 0.6 and 0.7 (2026-08 to 2026-10)

- Rebuilds for Hytale 0.6.0, 0.6.3 and 0.7.0 (Update 7); mandatory for those server versions.
- Commands declare their permissions upfront (Hytale 0.6.0 model); player commands stay open with their `ks.achievements.user.*` checks.
- The HUD icon was shrunk so it fits the shared custom UI texture atlas of Hytale 0.6.0.
- `/kslang` without argument answers in chat instead of opening a removed window (2.10.6).

---

## Version 2.8.x / 2.9.x - Hytale May 2026 Updates

- Migration to the keyed multi-HUD API; the MHUD integration was removed (no longer needed).
- Player commands work again after the Hytale command sender change.
- Restored 8 button icons on setups without the Runeteria core.

---

## Version 2.7.1

- Creating a new custom achievement no longer deletes the existing ones.
- `grant`, `revoke` and `list` can be run from the console.
- Custom achievements in `configs/achievements.json` are moved to `custom/custom_achievements.json` before the file is replaced on an update.

---

## Version 2.6.0 - LevelingCore, ShowcaseCompat & Objective Expansion

### New Features

#### Per-Player Language (Full Implementation)
All achievement notifications, gallery UI, title display, and admin popups now respect each player's individual language setting (via `/kslang`). Supported languages: `en-US`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `it-IT`, `pl-PL`, `ru-RU`, `ja-JP`.

#### LevelingCore Integration
Replaced the direct RPGLeveling dependency with the new LevelingCore abstraction layer. This allows the achievement system to work with any leveling plugin that implements the LevelingCore API.

#### 9-Language Admin Popup
The admin achievement management popup now renders in all 9 supported languages based on the admin's language setting.

#### ShowcaseCompat
Added compatibility layer for the Showcase mod. Achievements can now be displayed in Showcase displays and interacted with through the Showcase UI.

#### 10 New Objective Types
Added the following missing objective trigger types:
- `items_consumed` — Track food/potion consumption
- `items_dropped` — Track items dropped
- `items_picked_up` — Track items picked up
- `deaths` — Track player deaths
- `damage_dealt` — Track total damage dealt
- `damage_taken` — Track total damage taken
- `jumps` — Track player jumps
- `sprinting_distance` — Track sprinting distance
- `swimming_distance` — Track swimming distance
- `fishing_catches` — Track fishing catches

### Bug Fixes

- **Memory Leak Fix** — Additional cleanup pass for cached UI state that was not being released on player disconnect
- **Custom Achievement Persistence Fix** — Custom achievements defined in `custom/*.json` are now correctly preserved across server restarts when using MySQL storage
- **Localization After Save Fix** — Language strings are now correctly resolved after a player data save/reload cycle (previously fell back to `en-US` after save)

---

## Version 2.5.0 - Per-Player Language & Memory Fixes

### New Features

#### Per-Player Language Support
Players can now set their preferred language with `/kslang`. Achievement notifications, gallery UI, and title display all respect the player's language setting.

### Bug Fixes

- **Memory Leak Fix** — Player achievement data is now properly cleaned up on disconnect. Prevents memory growth on long-running servers.
- **Endless Level Tracker** — Fixed cumulative XP threshold tracking for Endless leveling integration.

---

## Version 2.4.0 - Endless Leveling Integration

### New Features

#### Endless Leveling Support
Full integration with the Endless leveling system. New trigger type `endless_xp` tracks cumulative XP thresholds. New reward type `endless_xp` grants Endless XP from achievement rewards.

### Improvements

- **Announcement Padding Fix** — Info Hub announcement display padding corrected.

---

## Version 2.3.0 - MySQL Storage, Tracker Config & Performance

### New Features

#### Tracker HUD Toggle
The Achievement Tracker HUD can now be globally disabled via configuration.

```json
"trackerHud": {
  "enabled": true,
  "position": "right"
}
```

Set `enabled` to `false` to completely disable the tracker for all players.

#### MySQL Storage Backend
Player achievement data can optionally be stored in MySQL for cross-server setups. Requires Core v1.4.0+ with MySQL storage configured.

- Automatic legacy file migration on first load
- Table: `ks_achievement_players` (UUID, Username, JSON-Blob, Timestamp)
- Fully backwards compatible — file storage remains the default

### Improvements

#### Debug Gate (Performance)
Over 20 files updated to gate detail-level logging behind `CoreAPI.isDebug()`. This massively reduces console spam in production. Only startup summaries, shutdown messages, and achievement unlock notifications remain ungated.

### Bug Fixes

- **RPG Level Chat Display** — Player level now shows correctly in chat (cache was not populated on join)
- **Nameplate Cleanup** — Achievement titles are cleared from nameplates on plugin shutdown (no more orphaned titles)
- **Language Propagation** — Language changes in the admin panel now correctly propagate to all mods
- **WARN Spam** — Playtime tick warnings and toast HUD conflict warnings downgraded to FINE level

---

## Version 1.8.7 - UI Fix

### Bug Fixes

- **Fixed UI crash** when MMO Skill Tree or RPG Leveling mods are not installed
  - Filter buttons now correctly check if the mod is actually available
  - Fixed incorrect UI visibility property usage

### Documentation

- **Documented Hytale nameplate limitations**
  - Nameplates only support plain text (no colors)
  - Multiline text is not supported in nameplates
  - `titlePosition` options `"above"` and `"below"` behave like `"prefix"` and `"suffix"`
  - Color settings (`titleColor`, `rpgLevelColor`) only work in chat

---

## Version 1.8.6 - Custom Localization Support

### New Features

#### Custom Translation Files

Server admins can now add their own translations without losing them during updates.

- New template files: `custom_en-US.json.example`, `custom_de-DE.json.example`
- Copy to `custom_en-US.json` and add your translations
- Custom translations are **NEVER overwritten** by plugin updates
- Keys starting with `_` are treated as comments and ignored

**Example:**
```json
{
  "lootbag.name.my_server_reward": "Server Reward",
  "lootbag.desc.my_server_reward": "A special gift from our server!",
  "achievements.name.custom_quest": "Custom Quest",
  "achievements.desc.custom_quest": "Complete the server quest"
}
```

See [Localization](./localization.md) for complete documentation.

---

## Version 1.8.5 - Lootbag Localization

### New Features

#### Lootbag i18n Support

All lootbag names, descriptions, and rarities are now fully localizable.

**Translation Keys:**
| Key Pattern | Description |
|-------------|-------------|
| `lootbag.name.<id>` | Lootbag name |
| `lootbag.desc.<id>` | Lootbag description |
| `lootbag.rarity.<rarity>` | Rarity label (common, uncommon, rare, epic, legendary) |

If no translation exists, the plugin falls back to the value from `lootbags.json`.

### Technical Changes

- Localization version bumped to v4 (auto-updates existing installations)
- Lootbag translations moved from `.lang` files to JSON (`localization/*.json`)

---

## Version 1.8.3 - French Language Support

### New Features

- Added French language support (`fr-FR`)
- All three languages (en-US, de-DE, fr-FR) are now auto-extracted on first start

---

## Version 1.8.2 - Multi-Target & Filter Improvements

### New Features

#### Multi-Target Support

Achievement triggers now support comma-separated targets for matching multiple entities or items:

```json
{
  "trigger": {
    "type": "kills",
    "target": "Spider,Spider_Cave,Spider_Frost",
    "count": 100
  }
}
```

#### Smart Filter Visibility

- MMO Skills filter auto-hides when MMO SkillTree plugin is not installed
- RPG Leveling filter auto-hides when RPG Leveling plugin is not installed

### Bug Fixes

- **Fixed Config Migration** - Version constants updated to trigger auto-updates correctly
- **Fixed 16+ Invalid Item IDs** - All items validated against server item list

---

## Version 1.8.1 - Config Migration Fix

### Bug Fixes

- Config version fix (migration now works correctly)

---

## Version 1.8.0 - API & UI Updates

### Summary

This version adds three major features: Unlock dates are now displayed in the achievement gallery UI, a public API allows external plugins to interact with the achievement system, and player levels from RPGLeveling can optionally be shown in nametags and chat.

### New Features

#### Unlock Date Display

Completed achievements now show the unlock date in the achievement gallery.

- **German (de-DE):** `dd.MM.yyyy` (e.g., "02.02.2026")
- **English (en-US):** `MM/dd/yyyy` (e.g., "02/02/2026")

#### Public API

External plugins can now interact with the Achievement System through a stable API.

```java
import com.hytale.achievements.api.AchievementAPI;

// Get API instance
AchievementAPI api = AchievementAPI.getInstance();

// Check availability
if (AchievementAPI.isAvailable()) {
    // Use API methods
}
```

**Available API Features:**
- Query achievement status, progress, and statistics
- Grant/revoke achievements programmatically
- Listen for unlock and progress events
- Access player statistics (blocks mined, mob kills, playtime)

See [API Reference](./api-reference.md) for complete documentation.

#### RPG Level Display

Player levels from the RPGLeveling plugin can optionally be displayed in nametags and chat.

**Configuration:**
```json
{
  "display": {
    "showRpgLevel": true,
    "rpgLevelFormat": "Lv.{level}",
    "rpgLevelColor": "#55FFFF",
    "rpgLevelPosition": "after_name"
  }
}
```

**Available Positions:**
| Position | Example |
|----------|---------|
| `before_name` | `[Title] [Lv.15] Username` |
| `after_name` | `[Title] Username [Lv.15]` |
| `after_title` | `[Title] [Lv.15] Username` |

**Requirements:**
- RPGLeveling plugin must be installed
- `showRpgLevel` must be set to `true`

### File Changes

| File | Changes |
|------|---------|
| `AchievementGallery.ui` | Added `#UnlockedDate` label to all entry elements |
| `AchievementGalleryPage.java` | Added `formatUnlockDate()` method and display logic |
| `api/AchievementAPI.java` | **NEW** - Complete public API class |
| `AchievementPlugin.java` | API initialization in `setup()`, RPGLevelingIntegration passed to TitleDisplayManager |
| `AchievementService.java` | Unlock notifications to API listeners |
| `AchievementConfig.java` | New display options for RPG Level |
| `TitleDisplayManager.java` | Level display integrated in nametag and chat |

### Migration

**For Server Admins:**
- No action required
- UI update loads automatically
- API is immediately available for other plugins

**For Plugin Developers:**
- API available via `AchievementAPI.getInstance()`
- Always check `isAvailable()` before calling API methods
- Listeners are automatically called when achievements unlock

---

## Version 1.7.0 - Item Validation & Bug Fixes

### Summary

Comprehensive overhaul of all Item IDs in configuration files. All Minecraft-style Item IDs have been replaced with valid Hytale Item IDs. Additionally, two important bugs were fixed.

### Bug Fixes

#### Weekend Warrior Achievement Not Unlocking - FIXED
- **Root Cause:** Trigger was set to `"type": "manual"` - no automatic detection
- **Solution:** New trigger type `weekend_login` implemented
- Weekend check on player login in `AchievementPlugin.java`
- Achievement now automatically unlocks when player logs in on Saturday or Sunday

#### Chat Broadcasts for All Achievements - FIXED
- **Problem:** `broadcastToChat` was sending broadcasts for ALL unlocked achievements
- **Desired Behavior:** Broadcasts only for achievements with title unlocks
- **Solution:** Added condition in `AchievementService.java` to check for title presence

### Item ID Corrections

Corrected **150+ invalid item IDs** across all configuration files.

#### Global Naming Conventions (Minecraft → Hytale)

| Minecraft-Style | Hytale-Style | Description |
|-----------------|--------------|-------------|
| `Tool_Axe_*` | `Tool_Hatchet_*` | Axes are called Hatchets |
| `Food_Apple` | `Plant_Fruit_Apple` | Fruits under Plant_ |
| `Food_Bread` | `Consumable_Food_Bread` | Food under Consumable_ |
| `Armor_Chestplate_*` | `Armor_*_Chest` | Armor pieces named differently |
| `Armor_Helmet_*` | `Armor_*_Head` | |
| `Shield_*` | `Weapon_Shield_*` | Shields under Weapon_ |
| `Weapon_Bow_*` | `Weapon_Shortbow_*` | Bows called Shortbow |
| `Weapon_Dagger_*` | `Weapon_Daggers_*` | Daggers are plural |
| `Potion_*` | `Consumable_Potion_*` | Potions under Consumable_ |
| `Material_*` | `Ingredient_*` | Materials called Ingredients |
| `Diamond` Tier | `Adamantite` Tier | No Diamond in Hytale |

#### Specific Corrections

**Materials → Ingredients:**
- `Material_String` → `Ingredient_Fibre`
- `Material_Poison` → `Ingredient_Venom`
- `Material_Fur` → `Ingredient_Hide_Thick`
- `Material_Leather` → `Ingredient_Hide_Medium`
- `Material_Bone` → `Ingredient_Bone_Fragment`
- `Ingredient_Feather` → `Ingredient_Feathers_Light`

**Gems:**
- `Gem_Ruby` → `Rock_Gem_Ruby`
- `Gem_Emerald` → `Rock_Gem_Emerald`
- `Gem_Sapphire` → `Rock_Gem_Sapphire`

**Workstations:**
- `Bench_Carpenter` → `Bench_WorkBench`
- `Bench_Stonecutter` → `Bench_Builders`
- `Bench_Anvil` → `Bench_Armory`

**Potions:**
- `Consumable_Potion_Health_Weak` → `Potion_Health_Lesser`
- `Consumable_Potion_Health_Strong` → `Potion_Health_Greater`
- `Consumable_Potion_Health` → `Potion_Health`

**Wood:**
- `Wood_Oak_Log` → `Wood_Oak_Trunk`
- `Wood_Birch_Log` → `Wood_Birch_Trunk`

### File Changes

| File | Changes |
|------|---------|
| `lootbags.json` | ~45 Item IDs corrected |
| `achievements.json` | iconItems corrected, weekend trigger fixed |
| `mmo_skills_achievements.json` | Weapon/Tool/Bench corrections |
| `rpg_leveling_achievements.json` | Material→Ingredient corrections |
| `AchievementPlugin.java` | Weekend-login trigger added |
| `AchievementService.java` | Broadcast condition for title-only |

### New Trigger Type

```json
{
  "trigger": {
    "type": "weekend_login",
    "count": 1
  }
}
```

Triggers when a player logs in on Saturday or Sunday.

### Migration

**For Server Admins:**
- Configs are automatically updated on server start
- Old configs backed up as `.backup-vX`
- Check your `custom/` files for the same item errors

**For Players:**
- No action required
- Existing achievements are preserved
- Weekend Warrior now unlocks automatically on weekend login

### Known Limitations

- `Material_Orb_Experience` doesn't exist → Replaced with `Rock_Gem_Sapphire`
- `Material_Orb_Time` doesn't exist → Replaced with `Rock_Gem_Sapphire`
- No `Flesh_Rotten` item → Replaced with `Food_Wildmeat_Raw`
- No `Paper` item → Replaced with `Deco_Book_Pile_Small`

---

## Version 1.6.1 - Event-Based RPG Leveling & Filter Icon Fixes

### Summary

Critical update that completely rewrites the RPG Leveling integration from polling-based to event-based, fixing achievements not triggering on level-up. Also fixes missing filter icons in the Achievement Gallery.

:::warning Breaking Changes
**RPG Leveling Plugin Version Requirement:**
- **Minimum: v0.2.0-beta-5** (or newer)
- Older versions (e.g., 0.1.10) do NOT have the required event API
- The event-based integration requires `LevelUpListener` and `ExperienceGainedListener` interfaces
:::

### Bug Fixes

#### RPG Leveling Achievements Not Triggering - FIXED
- **Root Cause:** Previous implementation used wrong API class paths
- **Old (broken):** `org.zuxaw.plugin.api.events.LevelUpEvent`
- **New (correct):** `org.zuxaw.plugin.api.LevelUpEvent`
- **Old (broken):** Used `Consumer<T>` for listener registration
- **New (correct):** Uses `LevelUpListener` and `ExperienceGainedListener` interfaces
- **Solution:** Complete rewrite using Java Dynamic Proxy for interface implementation

#### Achievement Gallery Filter Icons Not Showing - FIXED
- **Root Cause:** Invalid ItemIds for filter icons
- **Old (broken):** `Material_Experience_Orb`, `Weapon_Sword_Adamantite`, `Greenscreen`
- **New (correct):** `Tool_Pickaxe_Cobalt`, `Weapon_Sword_Cobalt`, `Ore_Prisma`
- Affected filters: MMO Skills, RPG Leveling, Completed

#### Localization JSON Parse Failure - FIXED
- **Root Cause:** Duplicate key `bug_squasher` in localization files
- Renamed conflicting title to `bug_squasher_title`
- Added localization versioning system (now v3) with auto-update and backup

### Technical Changes

#### RPGLevelingIntegration.java - COMPLETE REWRITE

| Aspect | Old (v1.6.0) | New (v1.6.1) |
|--------|--------------|--------------|
| **Approach** | Polling (every 5s) | Event-based (real-time) |
| **API Version** | Unknown | 0.2.0-beta-5 |
| **Event Classes** | `.api.events.LevelUpEvent` | `.api.LevelUpEvent` |
| **Listener Type** | `Consumer<T>` | `LevelUpListener` interface |
| **PlayerLevelInfo** | `.api.PlayerLevelInfo` | `.api.RPGLevelingAPI$PlayerLevelInfo` |
| **Registration** | Direct Consumer | Java Dynamic Proxy |

**New Implementation Details:**
```java
// Java Dynamic Proxy for interface implementation
InvocationHandler levelUpHandler = (proxy, method, args) -> {
    if ("onLevelUp".equals(method.getName())) {
        handleLevelUpEvent(args[0]);
    }
    return null;
};
levelUpListenerProxy = Proxy.newProxyInstance(
    levelUpListenerClass.getClassLoader(),
    new Class<?>[] { levelUpListenerClass },
    levelUpHandler
);
registerLevelUpListenerMethod.invoke(apiInstance, levelUpListenerProxy);
```

#### File Changes

| File | Change | Description |
|------|--------|-------------|
| `RPGLevelingIntegration.java` | REWRITTEN | Event-based API, Dynamic Proxy |
| `RPGLevelTracker.java` | MODIFIED | Removed polling, added event handlers |
| `AchievementPlugin.java` | MODIFIED | Removed scheduler, added listener registration |
| `AchievementGalleryPage.java` | MODIFIED | Fixed filter icon ItemIds |
| `PluginI18n.java` | MODIFIED | Added versioning system |
| `en-US.json` | MODIFIED | Fixed duplicate key, added version |
| `de-DE.json` | MODIFIED | Fixed duplicate key, added version |

### Server Log Examples

**Successful Initialization:**
```
[KyuubiSoft Achievements] RPGLevelingAPI class loaded successfully
[KyuubiSoft Achievements] Loading event and listener classes...
[KyuubiSoft Achievements] Caching listener methods...
[KyuubiSoft Achievements] RPGLeveling API integration enabled!
[KyuubiSoft Achievements] Registered LevelUp listener with RPGLevelingAPI (dynamic proxy)
[KyuubiSoft Achievements] Registered ExperienceGained listener with RPGLevelingAPI (dynamic proxy)
```

**Level-Up Achievement Trigger:**
```
[KyuubiSoft Achievements] [RPGLeveling] LevelUp event: PlayerName leveled up from 1 to 2
[KyuubiSoft Achievements] [RPGLevelTracker] LevelUp: PlayerName from 1 to 2
[KyuubiSoft Achievements] Unlocking achievement test_rpg_level_2 for PlayerName
[KyuubiSoft Achievements] PlayerName reached RPG Level 2!
```

### Upgrade Notes

1. **Update RPGLeveling Plugin** to v0.2.0-beta-5 or newer
2. Delete old `localization/` folder (will be regenerated with v3)
3. Restart server
4. Verify in logs: "Registered LevelUp listener with RPGLevelingAPI (dynamic proxy)"

---

## Version 1.6.0 - Config Folder Structure & RPG Leveling Integration

### Summary

Major update introducing a new organized folder structure for configurations and full RPG Leveling plugin integration with 35 new achievements.

### New Features

#### New Config Folder Structure
- **Separated Standard and Custom Configs** - Clear distinction between plugin defaults and server customizations
- **configs/ Folder** - Standard configs that ship with the plugin (DO NOT MODIFY!)
  - `achievements.json` - Core achievements
  - `mmo_achievements.json` - MMO Skill Tree achievements
  - `rpg_leveling_achievements.json` - RPG Leveling achievements
- **custom/ Folder** - Server admin customizations (NEVER overwritten!)
  - `custom_achievements.json` - General custom achievements
  - `custom_mmo_achievements.json` - Custom MMO skill achievements
  - `custom_rpg_leveling_achievements.json` - Custom RPG leveling achievements
  - `.example` template files for each type
- **Automatic Folder Creation** - Folders are created automatically on first start
- **Safe Updates** - Standard configs can be updated without losing custom achievements
- **Individual Config Toggle** - Each standard config can be disabled individually:
  - `loadDefaultAchievements` - Toggle core achievements
  - `loadMmoAchievements` - Toggle MMO Skill Tree achievements
  - `loadRpgLevelingAchievements` - Toggle RPG Leveling achievements
- **Config Versioning** - All standard configs have version numbers for automatic updates

#### RPG Leveling Integration
- **Soft Dependency** - Works without RPGLeveling installed (achievements just won't trigger)
- **Reflection-Based API** - No hard dependency, graceful fallback
- **Polling-Based Tracker** - Checks player level/XP every 5 seconds
- **35 New Achievements:**
  - 6 Level Milestones (5, 10, 25, 50, 75, 100)
  - 3 XP Milestones (1,000 / 10,000 / 100,000)
  - 26 Mob Kill Achievements (Trork, Skeleton, Zombie, Scarak, Goblin chains)

#### New Trigger Types
- **`rpg_level`** - Triggers when reaching a specific character level
- **`rpg_xp`** - Triggers when accumulating total XP

#### Custom MMO Achievements
- **New File: `custom_mmo_achievements.json`** - Server admins can now add custom MMO skill achievements
- **Template Included** - `.example` file with usage examples
- **Override Support** - Custom achievements can override default MMO achievements

### New Files

| File | Location | Description |
|------|----------|-------------|
| `RPGLevelingIntegration.java` | `integration/` | Reflection-based API wrapper |
| `RPGLevelTracker.java` | `tracking/` | Polling tracker for level/XP changes |
| `rpg_leveling_achievements.json` | `defaults/` | 35 default RPG Leveling achievements |
| `custom_rpg_leveling_achievements.json.example` | `defaults/` | Template for custom RPG achievements |
| `custom_mmo_achievements.json.example` | `defaults/` | Template for custom MMO achievements |

### Configuration

#### New Folder Structure

```
KyuubiAchievements/
├── config.json                              # Main config (root)
├── README.md
├── configs/                                 # Standard configs (DO NOT MODIFY!)
│   ├── achievements.json
│   ├── mmo_achievements.json
│   └── rpg_leveling_achievements.json
└── custom/                                  # Custom configs (safe from updates)
    ├── custom_achievements.json
    ├── custom_achievements.json.example
    ├── custom_mmo_achievements.json
    ├── custom_mmo_achievements.json.example
    ├── custom_rpg_leveling_achievements.json
    └── custom_rpg_leveling_achievements.json.example
```

#### Custom RPG Leveling Achievement Example

```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": "Currency_Coin_Gold", "amount": 100 }
      ]
    }
  ]
}
```

### Default RPG Leveling 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 (10 → 50 → 100 → 500 → 1000)
- **Trork Chain** - Titles: Trork Hunter, Trork Slayer, Trork Bane
- **Skeleton Chain** - Titles: Bone Collector, Undead Hunter, Skeleton Bane
- **Zombie Chain** - Titles: Zombie Hunter, Zombie Slayer, Zombie Bane
- **Scarak Chain** - Titles: Bug Squasher, Scarak Slayer, Scarak Bane
- **Goblin Chain** - Titles: Goblin Hunter, Goblin Slayer, Goblin Bane

### Migration from v1.5.x

1. The plugin will automatically create the new folder structure on first start
2. Existing configs in root folder should be manually moved:
   - `achievements.json` → `configs/achievements.json`
   - `mmo_achievements.json` → `configs/mmo_achievements.json`
   - `custom_achievements.json` → `custom/custom_achievements.json`
3. Or simply delete old configs and let the plugin regenerate them

---

## Version 1.5.2 - Lootbag & Pending Rewards System

### Summary

Major update introducing the Lootbag Reward System and Pending Rewards UI. Players can now receive lootbags from achievements and collect rewards manually via the new `/rewards` command.

### New Features

#### Lootbag Reward System
- **New Reward Type: Lootbag** - Achievements can now reward lootbags instead of direct items
- **Lootbag Templates** - Reusable lootbag definitions in `lootbags.json`
- **Three Lootbag Types:**
  - Fixed Items: Player receives all defined items
  - Random Pool: Player receives X weighted random items
  - Hybrid: Guaranteed items + random picks
- **Weighted Random Algorithm** - Each pool item has a weight for probability control
- **14 Default Templates** - Ready-to-use lootbags (starter packs, ore bundles, food crates, etc.)
- **Auto-Export** - `lootbags.json` is auto-generated in server config on first start

#### Pending Rewards UI (`/rewards`)
- **New Rewards Command** - View and collect all pending rewards
- **Support for All Reward Types** - Items, Lootbags, Commands
- **Interactive Buttons:**
  - "Collect" for items and commands
  - "Open" for lootbags (reveals contents, then collect)
  - "Collect All" to grab everything at once
- **Visual Feedback** - Item icons, rarity colors, source achievement display
- **Chat Notifications** - When opening a lootbag, contents are shown in chat

#### Achievement Toast Improvements
- **Lootbag Display** - Toast now shows "Lootbag" in rewards line when achievement grants a lootbag

#### Block Tracking Fix
- **Grass Block Fix** - `Soil_Grass_Full` and similar soil blocks now correctly count for mining achievements
- Previous filter was too aggressive, excluding all blocks containing "grass"

#### Creative Mode Ignore
- **New Config Option** - `tracking.ignoreCreativeMode` (default: `true`)
- Players in Creative mode don't earn achievement progress
- Prevents "cheating" achievements via Creative mode

### Configuration

#### New File: `lootbags.json`

```json
{
  "lootbags": {
    "welcome_gift": {
      "name": "Willkommensgeschenk",
      "description": "Ein kleines Startpaket für neue Spieler",
      "icon": "Chest_Wood",
      "rarity": "common",
      "items": [
        { "itemId": "Food_Bread", "amount": 10 },
        { "itemId": "Torch", "amount": 16 }
      ]
    },
    "random_gems": {
      "name": "Gem Lottery",
      "rarity": "rare",
      "pickCount": 2,
      "allowDuplicates": false,
      "pool": [
        { "itemId": "Gem_Ruby", "amount": 1, "weight": 20 },
        { "itemId": "Gem_Emerald", "amount": 1, "weight": 30 }
      ]
    }
  }
}
```

#### Achievement Reward Example

```json
{
  "id": "welcome_achievement",
  "rewards": [
    { "type": "lootbag", "lootbagId": "welcome_gift" }
  ]
}
```

#### Config Option

```json
"tracking": {
  "ignoreCreativeMode": true
}
```

### Default Lootbag Templates

| ID | Name | Rarity | Type |
|----|------|--------|------|
| `starter_pack` | Starter Pack | Common | Fixed |
| `welcome_gift` | Willkommensgeschenk | Common | Fixed |
| `copper_bundle` | Kupfer-Erzbündel | Uncommon | Fixed |
| `iron_tools` | Eisen-Werkzeugset | Rare | Fixed |
| `miner_reward` | Miner's Treasure | Uncommon | Fixed |
| `ore_bundle_common` | Erzbündel (Basis) | Common | Fixed |
| `ore_bundle_rare` | Erzbündel (Selten) | Rare | Fixed |
| `ore_bundle_epic` | Erzbündel (Episch) | Epic | Fixed |
| `food_crate` | Proviantkiste | Common | Random Pool |
| `combat_loot` | Warrior's Cache | Rare | Hybrid |
| `explorer_chest` | Explorer's Chest | Epic | Random Pool |
| `legendary_hoard` | Dragon's Hoard | Legendary | Hybrid |
| `playtime_bronze` | Bronze-Treuebelohnung | Common | Fixed |
| `playtime_silver` | Silber-Treuebelohnung | Uncommon | Fixed |
| `playtime_gold` | Gold-Treuebelohnung | Rare | Hybrid |

---

## Version 1.5.1 - Gradient & Rainbow Support

### New Feature

- **Gradient & Rainbow on Username** - Trailing `<gradient:...>` or `<rainbow>` tags from LuckPerms prefix now apply to the username
- **Gradient & Rainbow on Chat Message** - Trailing `<gradient:...>` or `<rainbow>` tags from LuckPerms suffix now apply to the chat message
- Each character gets individually colored for smooth gradient/rainbow effects
- Example: Prefix `<gradient:#ff85fb:#85fbff>` → Username appears with pink-to-cyan gradient
- Example: Prefix `<rainbow>` → Username appears with rainbow colors

### Technical

- New `AdventureConverter.TrailingGradient` class for extracting gradient/rainbow info
- New `AdventureConverter.applyGradient()` method for per-character color interpolation
- New `AdventureConverter.applyRainbow()` method for HSV-based rainbow coloring
- HSV to RGB conversion for smooth color transitions

---

## Version 1.5.0 - LuckPerms & MHUD Release

### Summary

This is a major release consolidating all 1.4.x improvements into a stable version.

### New Features

#### LuckPerms Integration (since 1.4.0)
- **Automatic Prefix Retrieval** - LuckPerms prefixes are fetched automatically from the API
- **Full Color Support** - Rainbow, gradients, legacy codes (&a, &b), hex colors
- **Trailing Style Support** - Active styles at the end of prefix apply to username (color, bold, italic, underlined, strikethrough)
- **Separate Prefix/Suffix Styling** - Prefix styles → Username, Suffix styles → Message color
- **Combined Chat Format** - `[LuckPerms-Prefix] [Achievement-Title] Username: message`
- **Lazy Initialization** - Works regardless of plugin load order

#### MHUD Integration (since 1.4.7)
- **Multiple HUD Support** - Full integration with [MHUD](https://github.com/Buuz135/MHUD) plugin
- **Conflict Prevention** - No more crashes when multiple plugins use Custom HUDs
- **Graceful Fallback** - Works with or without MHUD installed
- **Smart Detection** - Automatically detects and uses MHUD when available

#### Technical
- Adventure MiniMessage library for color parsing (same as LuckPerms uses)
- `AdventureConverter` utility class for MiniMessage → Hytale Message conversion
- `MHUDIntegration` class for MHUD communication via reflection
- Shadow JAR includes relocated Adventure libraries

### Bug Fixes
- Fixed color inheritance for complex LuckPerms prefixes
- Fixed LuckPerms load order issues with lazy initialization
- Fixed "Failed to apply CustomUI HUD commands" crash with MHUD
- Fixed crash when multiple plugins use Custom HUD without MHUD
- Removed debug logging (now uses FINE level)

### Dependencies

**Optional:**
- LuckPerms (for prefix/suffix integration)
- MHUD (for multiple HUD support)

---

## Version 1.4.9 - MHUD Double-Show Fix

### Bugfix

- **Fixed "Failed to apply CustomUI HUD commands" crash when using MHUD** - Removed duplicate `show()` call
- MHUD internally calls `build()` and `update()` when adding a HUD
- Calling `show()` after that caused conflicting UI commands and client crash
- Now: When using MHUD, only `setCustomHud()` is called, no additional `show()`

---

## Version 1.4.8 - HUD Crash Prevention

### Bugfix

- **Fixed crash when multiple plugins use Custom HUD without MHUD** - Toasts are now completely skipped if another plugin's HUD is active
- Early detection: Toast queue is not even started if conflict is detected
- Clear warning in server log recommending MHUD installation
- No more retry loops that could cause crashes
- Chat notifications still work (from AchievementService) when toast is skipped

---

## Version 1.4.7 - MHUD Integration

### New Feature

- **MHUD Integration** - Full support for [MHUD](https://github.com/Buuz135/MHUD) (Multiple HUD) plugin
- When MHUD is installed, toast notifications use the MHUD system allowing multiple HUDs simultaneously
- No more conflicts with other plugins that use Custom HUDs
- Automatic detection and lazy initialization of MHUD at runtime
- Falls back to standard HUD system if MHUD is not available
- Added MHUD as optional dependency in manifest.json

### Technical

- New `MHUDIntegration` class handles MHUD communication via reflection
- `ToastManager` now prefers MHUD when available, with graceful fallback
- HUD identifier: `KyuubiSoft_Achievements`

---

## Version 1.4.6 - HUD Conflict Prevention & Debug Logging

### Bugfix

- **Fixed HUD conflict with other plugins** - Toast notifications now check if another plugin's HUD is active
- If another plugin has a Custom HUD active, our toast waits and retries after 2 seconds
- Prevents server crashes when multiple plugins try to use Custom HUD simultaneously
- Only our own HUDs (AchievementToastHud, EmptyHud) are replaced - other plugins' HUDs are respected

### Debug

- **Added detailed logging for suffix color extraction** - Helps debug `<#ffffff>` format parsing
- Logs now show step-by-step extraction: input, positions, intermediate values

---

## Version 1.4.5 - Separate Prefix/Suffix Styling

### Change

- **Prefix styles → Username** - Trailing styles from LuckPerms Prefix are applied to the username
- **Suffix styles → Message color** - Trailing color from LuckPerms Suffix is applied to the chat message
- **Style inheritance** - Unclosed styles (bold, italic) from Prefix carry over to the message
- Example: Prefix `<bold>[Mythic] <#be8fff>` → Username purple + bold, Message also bold
- Example: Suffix `<#aaaaaa>` → Message appears in gray

---

## Version 1.4.4 - LuckPerms Load Order Fix

### Bugfix

- **Fixed LuckPerms load order** - Added `OptionalDependencies` in manifest.json
- Plugin now always loads AFTER LuckPerms (if installed)
- Works with `--accept-early-plugins` flag
- Combined with lazy initialization from 1.4.3 for maximum compatibility

---

## Version 1.4.3 - Lazy LuckPerms Initialization

### Bugfix

- **Fixed LuckPerms loading order issue** - LuckPerms integration now uses lazy initialization
- Previously: `LuckPerms found but not yet loaded - prefix integration disabled`
- Now: LuckPerms API is initialized on first use (when player sends first chat message)
- Works regardless of plugin load order - no more `--accept-early-plugins` needed

---

## Version 1.4.2 - Trailing Styles for Username

### New Feature

- **Trailing Style Support** - All active styles at the end of the LuckPerms prefix are applied to the username
- Supported styles: **color**, **bold**, **italic**, **underlined**, **strikethrough**
- Example: `<bold><#2b2b2b>[<gradient:#ff85fb:#85fbff>Mythic</gradient><#2b2b2b>] <#be8fff>`
  → Username appears in `#be8fff` (purple) and **bold**
- New `AdventureConverter.TrailingStyle` class contains all trailing formatting info
- New `AdventureConverter.getTrailingStyle()` method extracts color + styles from formatted text

---

## Version 1.4.1 - Color Inheritance Fix

### Bugfix

- **Fixed color inheritance for complex LuckPerms prefixes** - Colors now properly inherit to child elements
- Example: `<bold><#2b2b2b>[<gradient>Mythic</gradient><#2b2b2b>]` now correctly colors the closing bracket
- Adventure Component styles (color, bold, italic) are now properly passed down to children

---

## Version 1.4.0 - LuckPerms Integration

### New: LuckPerms Chat Prefix Integration

- **Automatic Prefix Retrieval** - LuckPerms prefixes are now automatically fetched from the API
- **Full Color Support** - All LuckPerms color formats are supported:
  - `<rainbow>Text</rainbow>` - Rainbow effect
  - `<gradient:#FF0000:#00FF00>Text</gradient>` - Color gradients
  - `&a`, `&b`, `&c`, etc. - Legacy Minecraft color codes
  - `<color:#FF5555>Text</color>` - Hex colors
- **Combined Chat Format** - LuckPerms prefix + Achievement title in one line:
  ```
  [LuckPerms-Prefix] [Achievement-Title] Username: message
  ```
- **Soft-Dependency** - Works with or without LuckPerms installed
- **No Manual Config Required** - Prefixes are pulled directly from LuckPerms groups

### Technical Changes

- Added Adventure MiniMessage library for color parsing (same as LuckPerms uses)
- New `AdventureConverter` utility class for MiniMessage → Hytale Message conversion
- `LuckPermsIntegration` now retrieves prefixes via multiple fallback methods:
1. User cached metadata (contextual)
2. User cached metadata (non-contextual)
3. Primary group cached metadata
4. Direct group node parsing (`meta.prefix.*` format)
- Shadow JAR now includes relocated Adventure libraries (`com.hytale.achievements.lib.kyori`)

---

## Version 1.3.0 - Display Options & Localization

### New Features

#### Achievement Toast Banner
- **Display Mode Config** - Choose how achievement unlocks are displayed:
  - `chat` - Classic chat message (default)
  - `banner` - Toast notification in the top-right corner
  - `both` - Both chat and banner
- **Toast Features:**
  - Shows achievement name, title reward, item rewards
  - Achievement icon on the left
  - Auto-hides after configurable duration
  - New toast cancels previous one (no stacking)
  - Fixed width (300px), dynamic height

#### Default Achievements Toggle
- **`loadDefaultAchievements`** config option
- Set to `false` to use only custom achievements
- Perfect for servers with fully custom achievement sets

#### Localization Improvements
- Chat messages now localized ("Achievement Unlocked", "Title Unlocked")
- All notification messages support DE/EN

---

## Version 1.2.0 - Complete Overhaul

### Custom Achievements System

- **Custom Achievements File** - Server operators can define custom achievements in `custom_achievements.json`
- Custom achievements can override default achievements (same ID)
- Automatically merged with default achievements on load
- Template file `custom_achievements.json.example` is auto-generated

**New Field: `additionalInfo`**
- Displays additional information below the reward line in the gallery
- Ideal for event hints, special conditions, etc.
- Configurable with text and color

```json
{
  "id": "summer_event_special",
  "additionalInfo": {
    "text": "Only available during the summer event!",
    "color": "#FF9900"
  }
}
```

### Session-Based Playtime Tracking

**Before (Scheduler-based)**
- Playtime was incremented every minute via scheduler
- On server crash: Loss of entire session since last save

**Now (Session-based)**
- Session start time is saved on player connect
- Playtime is calculated on player disconnect
- 15-minute checkpoints: Automatic intermediate saves every 15 minutes
- Live calculation: UI always shows current playtime in real-time
- Maximum data loss: 15 minutes instead of entire session

### Achievement Gallery (`/achievements`)

**New Features**
- **Search Field** - Search achievements by name, description, ID, and category
- **"Completed" Filter Tab** - New filter shows all unlocked achievements
- **Smart Chain Display** - For achievement chains, only the next incomplete achievement is shown (completed ones appear in the "Completed" tab)
- **Chain Progress Counter** - Shows progress like `[2/5]` for chains
- **Progress with Units** - Progress now shows units (e.g., "162 / 300 Minutes", "25 / 50 Messages")
- **Live Playtime** - Playtime achievements always show current session time
- **AdditionalInfo Display** - Shows extra info for custom achievements (highlighted in orange)
- **Hover Effects** - All filter buttons and pagination buttons

**Chain Detection**
- Now supports both naming patterns:
  - Numeric: `spider_hunter_1` -> `spider_hunter_2` -> `spider_hunter_3`
  - Requires-based: `first_hour` -> `five_hours` -> `ten_hours`
- Chain counter now correctly increases (1/4, 2/4, 3/4) when completing achievements

**UI Improvements**
- Entry height increased to 85px for better readability
- Status column widened to 95px (no text truncation)
- Chain display shows "Current:" instead of "Next:" label
- Trigger descriptions now show actual progress (e.g., "0 / 50 Messages" instead of "0/4 completed")

### Title Selection (`/title`)

**Full Localization (DE/EN)**
- Title, current label, no title, clear button
- Pagination: Prev, Next, Page
- Statistics: "Titles: X/Y unlocked"
- Origin: "From: \{Achievement\}"
- Select button, active indicator

**UI Improvements**
- Pagination buttons widened to 180px (no text truncation)
- Proper spacing from top border

### Bug Fixes

- Fixed double-colon in reward display ("Reward:: Title" -> "Reward: Title")
- Fixed chain counter going down instead of up when completing achievements
- Fixed various German translation issues (umlauts, numbers)

---

## Version 1.1.0 - Initial Release

### Features
- 487 built-in achievements across 6 categories
- Achievement Gallery UI
- Title Selection UI
- Player commands (`/achievements`, `/titles`)
- Admin commands (`/achievementadmin`)
- Progress tracking for all trigger types
- Item and command rewards
- Multi-language support (EN, DE)
- Statistics export

### Categories
- Combat (49 achievements)
- Progression (102 achievements)
- Exploration (32 achievements)
- Social (20 achievements)
- Husbandry (29 achievements)
- Secret (37 achievements)

---

## Upgrade Notes

### Upgrading to 2.6.0

- LevelingCore replaces the direct RPGLeveling dependency. If you use RPGLeveling, ensure LevelingCore is also installed.
- 10 new trigger types are available — no migration needed, they are additive.
- ShowcaseCompat is automatic if the Showcase mod is present.

### Upgrading to 2.3.0

- **MySQL Storage** is optional. File storage remains the default. To enable MySQL, configure the Core plugin's MySQL settings first.
- Tracker HUD can be disabled via `trackerHud.enabled: false` in `config.json`.

### Upgrading to 1.6.1

1. **Update RPGLeveling Plugin** to v0.2.0-beta-5 or newer (required for event API)
2. Delete old `localization/` folder (will be regenerated with v3)
3. Restart server
4. Verify in logs: "Registered LevelUp listener with RPGLevelingAPI (dynamic proxy)"

### Upgrading to 1.6.0

**Automatic Migration:** The plugin will automatically:
1. Create the new folder structure (`configs/`, `custom/`)
2. Generate default achievement files
3. Create template files for custom achievements

**Manual Steps:**
- Move existing custom achievements to `custom/custom_achievements.json`
- Review new config options (`loadMmoAchievements`, `loadRpgLevelingAchievements`)

### Upgrading to 1.5.0

No breaking changes. The plugin is fully backwards compatible.

**Optional:** Install MHUD for better HUD compatibility with other plugins.

### Upgrading to 1.2.0

> **Recommendation:** When updating from 1.1.x, we recommend deleting the existing `achievements.json` file and restarting the server. The plugin will automatically generate a new default file. Custom achievements should be moved to the `custom_achievements.json` file so they are not overwritten by future updates.

### Fresh Install

1. Place the JAR in your plugins folder
2. Start the server
3. Configure `config.json` as needed
4. Add custom achievements to `custom/custom_achievements.json`