# Achievement & Title System

**KyuubiSoft Achievements adds achievements, titles and achievement points to a Hytale server. Players unlock achievements by playing normally, wear the titles they earn in chat and on their nameplate, collect item and lootbag rewards in the achievement book and follow up to three goals on a tracker HUD. Admins edit everything in one admin window in the game.**

---

## How it works

- The server counts what players do: blocks mined, chopped, dug and placed, creatures defeated, damage, crafting, zones discovered, distance, playtime, chat, NPC talks, dungeon runs and more. Every achievement has one **trigger** and a **count**.
- When the count is reached, the achievement unlocks. The player gets **achievement points** (by difficulty), an optional **title** and optional **rewards**.
- Rewards wait in the **Rewards** tab of the achievement book until the player collects them. A full inventory loses nothing: what does not fit keeps waiting.
- Achievements can form **chains** (Miner I to V). The book shows a chain as one line with the current stage.
- Achievement points are a shop currency (`achievement_points`) for KyuubiSoft Core shops. See [Achievement Points](./achievement-points).

---

## Features

### Content

- **432 achievements ship with the mod**: 277 standard ones (combat, progression, exploration, husbandry, social, secret), 121 for MMO Skill Tree and 34 for RPG Leveling. The MMO and RPG Leveling achievements are only shown and counted when those mods are installed.
- **About 340 titles** in their own colours.
- Hidden achievements show as "???" until they are unlocked, with an optional hint.
- Every achievement shows how many players have it ("14 % of players") and who was first on the server.
- Points per difficulty can be set in the config (defaults 10 / 10 / 25 / 50 / 10 for easy / normal / hard / epic / legendary).

### Rewards

- **Items**, **lootbags** (rolled once and saved, so a relog never re-rolls them), **commands** and **MMO skill XP**.
- "Collect all" in the book, partial collects when the inventory is full, and a "Rewards waiting" hint after join.

### Integrations

- **[LuckPerms](./luckperms-integration)**: group prefixes in chat.
- **[MMO Skill Tree](./mmo-skilltree-integration)** and **[RPG Leveling](./rpg-leveling-integration)**: skill and level achievements.
- **KyuubiSoft Dungeons**: dungeon runs, biomes, rarities and runs without dying.
- **KyuubiSoft Nameplates**: the active title is shown as a nameplate tag.
- **KyuubiSoft Core NPCs and dialogs**: talking to an NPC and finishing a dialog count as triggers. See [NPC Integration](./npc-integration).
- **Endless Leveling** and **LevelingCore**: level, XP, class and race achievements.

---

## Windows and HUD

| Window | What it shows |
|--------|---------------|
| **Achievement book** | `/ksachievements`, `/kstitles`, `/ksrewards` or the Achievement Book item. Overview, one tab per category, titles and rewards, with search, filters and a detail panel. See [Achievement Book](./ui-pages) |
| **Book settings** | What the tracker shows, the language |
| **Tracker HUD** | Up to 3 tracked achievements with progress, plus one unlock toast. See [Tracker HUD](./tracker-hud) |
| **Admin window** | `/acadmin panel` or the `/ksadmin` hub: achievements, categories, titles, players, statistics and settings. See [Admin Window](./admin-panel) |

All windows use the KyuubiSoft "Goldfiligran" look. The textures come from the shared KyuubiSoft UI kit inside the jar.

---

## What's new in 3.x

- **3.0.0 - new achievement book.** One window for overview, categories, titles and rewards replaces the old gallery, title selection, rewards page and lootbag page. New tracker HUD and one combined unlock toast. Many fixes: wood, wildcard, `items_collected`, `welcome` and Dungeon Diver achievements can now be unlocked; item rewards with a full inventory no longer duplicate; lootbags are rolled once; revoking an achievement takes its points back.
- **3.0.1 - KS settings.** The tracker options also appear in the shared KyuubiSoft settings window (`/kssettings`), and the language is chosen there for all KyuubiSoft mods.
- **3.1.0 - new admin window.** One window replaces the old admin panel: edit standard achievements without copies, a check view, categories, titles, disabling achievements, a players tool for online and offline players, statistics and five settings pages. Every change is a draft until **Save**.
- **3.1.1 - playtest fix.** The item picker of the admin window opens as a framed window over a dimmed backdrop.

:::note
The 3.x windows have not been tested in game yet.
:::

See the [Changelog](./changelog) for the full list.

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing, the files the mod creates, a first test |
| [Configuration](./configuration) | Every option in `config.json` |
| [Achievements](./achievements) | How an achievement is built: triggers, rewards, titles, chains |
| [Custom Achievements](./custom-achievements) | Adding and changing achievements in files |
| [Lootbags](./lootbags) | The lootbag rewards of this mod |
| [Achievement Points](./achievement-points) | Points per difficulty and points shops |
| [Achievement Book](./ui-pages) | The player window |
| [Rewards](./rewards-ui) | Waiting rewards and how collecting works |
| [Tracker HUD](./tracker-hud) | The HUD and its settings |
| [Commands](./commands) | Player and admin commands |
| [Permissions](./permissions) | Permission nodes |
| [Admin Window](./admin-panel) | The in-game admin window |
| [Localization](./localization) | Languages and translation files |
| [API Reference](./api-reference) | Java API for other plugins |
| [Troubleshooting](./troubleshooting) | Common problems |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Plugin** | KyuubiSoft Achievements (manifest `kyuubisoft:achievements`) |
| **Version** | 3.1.6 (2026-11-09) |
| **Jar** | `KyuubiSoftAchievements-3.1.6.jar` |
| **Player commands** | `/ksachievements` (`/achievement`, `/ac`), `/kstitles` (`/title`), `/ksrewards` (`/reward`, `/rw`) |
| **Admin command** | `/ksachievementadmin` (alias `/acadmin`) with `panel`, `list`, `grant`, `revoke`, `simulate` |
| **Admin permission** | `ks.achievements.admin` |
| **Data folder** | `mods/kyuubisoft_achievements/` |
| **Localization** | 9 languages, version 18 |
| **Required** | KyuubiSoft Core (2.9.9 or newer) |
| **Optional** | LuckPerms, MMO Skill Tree, RPG Leveling, Endless Leveling, LevelingCore, KyuubiSoft Nameplates, KyuubiSoft Dungeons |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0)
- Java 25
- KyuubiSoft Core. Version 3.0.0 needs at least Core 2.7.3; with Core 2.9.2 changed and removed lootbags apply at once after a reload instead of after a restart.

## Download

[![CurseForge](https://img.shields.io/badge/CurseForge-Download-orange?style=for-the-badge&logo=curseforge)](https://www.curseforge.com/hytale/mods/kyuubisoft-achievements-titles-rewards)

## Support

- **Discord**: [KyuubiSoft Discord](https://dc.gg/kyuubisoft)