API Reference
Technical reference for plugin developers and advanced users. Includes the public API for external plugin integration.
Achievement Definition Schema
Section titled “Achievement Definition Schema”interface Achievement { // Required id: string; // Unique identifier (snake_case) category: Category; // Category classification trigger: Trigger; // Unlock condition
// Optional iconItem?: string; // Item ID for icon (default: "Ore_Gold") hidden?: boolean; // Hide until unlocked (default: false) difficulty?: Difficulty; // Difficulty tier (default: "normal") requires?: string | string[]; // Prerequisite achievement ID(s) showRequires?: boolean; // Show requirements when locked (default: true) title?: Title; // Unlockable title reward rewards?: Reward[]; // Item/command rewards additionalInfo?: AdditionalInfo; // Custom info text custom?: boolean; // Mark as custom achievement}
type Category = "combat" | "progression" | "exploration" | "social" | "husbandry" | "secret";
type Difficulty = "easy" | "normal" | "hard" | "epic";Trigger Types
Section titled “Trigger Types”BlocksMined / BlocksPlaced
Section titled “BlocksMined / BlocksPlaced”interface BlockTrigger { type: "blocks_mined" | "blocks_placed"; target: string; // Block ID, "any", or prefix (e.g., "Ore_") count: number; // Required count}Target Matching:
"any"- Matches all blocks"Stone"- Exact match"Ore_"- Prefix match (matches Ore_Iron, Ore_Gold, etc.)
interface KillsTrigger { type: "kills"; target: string; // Entity ID, "any", "any_mob", "any_player" count: number;}Target Options:
| Value | Matches |
|---|---|
"any" | All entities |
"any_mob" | All non-player entities |
"any_player" | All players |
"Spider" | Exact entity type |
ItemsCrafted
Section titled “ItemsCrafted”interface CraftTrigger { type: "items_crafted"; target: string; // Item ID or "any" count: number;}ZonesDiscovered
Section titled “ZonesDiscovered”interface ZoneTrigger { type: "zones_discovered"; target: string; // Zone ID or "any" count: number;}ChatMessages
Section titled “ChatMessages”interface ChatTrigger { type: "chat_messages"; count: number;}PlaytimeMinutes
Section titled “PlaytimeMinutes”interface PlaytimeTrigger { type: "playtime_minutes"; count: number; // Minutes}DistanceWalked
Section titled “DistanceWalked”interface DistanceTrigger { type: "distance_walked"; count: number; // Blocks}FullArmorSet
Section titled “FullArmorSet”interface ArmorTrigger { type: "full_armor_set"; target: ArmorMaterial;}
type ArmorMaterial = | "iron" | "copper" | "bronze" | "steel" | "cobalt" | "mithril" | "thorium" | "adamantite" | "onyxium" | "prisma";EquipItem
Section titled “EquipItem”interface EquipTrigger { type: "equip_item"; target: string; // Item ID}Manual
Section titled “Manual”interface ManualTrigger { type: "manual";}AutoOnPrerequisites
Section titled “AutoOnPrerequisites”interface AutoTrigger { type: "auto_on_prerequisites";}WeekendLogin
Section titled “WeekendLogin”interface WeekendLoginTrigger { type: "weekend_login"; count: number; // Number of weekend logins required}Triggers when a player logs in on Saturday or Sunday. Useful for attendance-based achievements.
SkillLevel (MMO SkillTree)
Section titled “SkillLevel (MMO SkillTree)”interface SkillLevelTrigger { type: "skill_level"; target: string; // "MINING:50" (skill in upper case + milestone) or "total:1000" count: number; // 1}Only the milestones 10 / 25 / 50 / 75 / 100 per skill and total: 100 / 500 / 1000 / 1500 / 2000 / 2300 are sent. The old total_skill_level type is not counted; use skill_level with a total: target.
RpgLevel (RPG Leveling)
Section titled “RpgLevel (RPG Leveling)”interface RpgLevelTrigger { type: "rpg_level"; target: string; // Level number as string count: number; // Usually 1}RpgXp (RPG Leveling)
Section titled “RpgXp (RPG Leveling)”interface RpgXpTrigger { type: "rpg_xp"; target: "any"; count: number; // Total XP required}Reward Types
Section titled “Reward Types”Item Reward
Section titled “Item Reward”interface ItemReward { type: "item"; itemId: string; // Hytale item ID amount: number; // Quantity (1-64)}Command Reward
Section titled “Command Reward”interface CommandReward { type: "command"; command: string; // Command to execute (use {player} placeholder) executor: Executor; // Who runs the command}
type Executor = "console" | "player";Lootbag Reward
Section titled “Lootbag Reward”interface LootbagReward { type: "lootbag"; lootbagId: string; // ID from lootbags.json}Title Definition
Section titled “Title Definition”interface Title { id: string; // Title identifier (for localization) color?: string; // Hex color code (default: "#FFFFFF" white)}Additional Info
Section titled “Additional Info”interface AdditionalInfo { text: string; // Display text color?: string; // Hex color code (default: "#AAAAAA" gray)}Configuration Schema
Section titled “Configuration Schema”interface Config { language: "en-US" | "de-DE"; loadDefaultAchievements: boolean;
display: { displayMode: "nametag" | "chat" | "both"; titlePosition: "prefix" | "above" | "below"; nametagFormat: string; chatFormat: string; titleColor: string; showRpgLevel: boolean; rpgLevelFormat: string; rpgLevelColor: string; rpgLevelPosition: "before_name" | "after_name" | "after_title"; };
notifications: { enabled: boolean; displayMode: "chat" | "banner" | "both"; displayDurationMs: number; showRewardsInBanner: boolean; broadcastToChat: boolean; broadcastFormat: string; };
tracking: { saveIntervalSeconds: number; enableExploration: boolean; enableCombat: boolean; enableProgression: boolean; enableSocial: boolean; };
admin: { cascadeRevoke: boolean; cascadeRevokeWarning: boolean; bypassPrerequisites: boolean; };
export: { enabled: boolean; intervalSeconds: number; exportGlobalStats: boolean; exportLeaderboards: boolean; exportRecentUnlocks: boolean; leaderboardSize: number; recentUnlocksSize: number; includePlayerTotals: boolean; };
groupPrefixes: { [groupName: string]: { prefix: string; priority: number; }; };}Localization Keys
Section titled “Localization Keys”Achievement Keys
Section titled “Achievement Keys”achievements.name.<id> - Achievement display nameachievements.desc.<id> - Achievement descriptionachievements.title.<id> - Title display nameBook and Admin Keys
Section titled “Book and Admin Keys”The achievement book uses achievements.book.* keys (for example category names achievements.book.cat.<category>), the HUD achievements.hud.*, the settings achievements.settings.* and the admin window aadmin.*. Hints for hidden achievements are achievements.hint.<id>. Put your own texts into localization/custom_<lang>.json; see Localization.
Command Keys
Section titled “Command Keys”achievements.cmd.grant.success - Grant success messageachievements.cmd.grant.already - Already unlocked messageachievements.cmd.revoke.success - Revoke success messageachievements.cmd.revoke.not_unlocked - Not unlocked messageachievements.cmd.list.header - List header formatachievements.cmd.list.empty - Empty list messageTrigger Keys
Section titled “Trigger Keys”achievements.trigger.blocks_mined - "Mine {0} blocks"achievements.trigger.blocks_placed - "Place {0} blocks"achievements.trigger.kills - "Kill {0} {1}"achievements.trigger.items_crafted - "Craft {0} {1}"achievements.trigger.playtime_minutes - "Play for {0} minutes"achievements.trigger.distance_walked - "Walk {0} blocks"achievements.trigger.chat_messages - "Send {0} chat messages"achievements.trigger.zones_discovered - "Discover {0} zones"File Paths
Section titled “File Paths”mods/kyuubisoft_achievements/├── config.json - Main configuration├── configs/ - Standard configs (replaced on updates)│ ├── achievements.json│ ├── mmo_achievements.json│ ├── rpg_leveling_achievements.json│ └── lootbags.json├── custom/ - Custom configs (safe from updates)│ ├── custom_achievements.json│ └── custom_lootbags.json├── localization/ - Language files (9 languages + custom_<lang>.json)├── players/ - Player achievement data (<uuid>.json, file storage)├── stats/ - Statistics export and server records│ ├── global_stats.json│ ├── leaderboards.json│ ├── recent_unlocks.json│ └── server_records.json├── backups/ - Backup sets of the admin window└── admin/players/ - Players tool: action log and queued offline actionsEvents
Section titled “Events”Achievement Events (Internal)
Section titled “Achievement Events (Internal)”The plugin tracks these Hytale events:
| Event | Trigger Type |
|---|---|
BlockBreakEvent | blocks_mined |
BlockPlaceEvent | blocks_placed |
EntityDeathEvent | kills |
PlayerCraftEvent | items_crafted |
PlayerMoveEvent | distance_walked |
PlayerChatEvent | chat_messages |
ZoneEnterEvent | zones_discovered |
PlayerEquipEvent | equip_item, full_armor_set |
PlayerJoinEvent | weekend_login (checks day of week) |
Public API
Section titled “Public API”External plugins can interact with the Achievement System through a stable public API.
Getting the API Instance
Section titled “Getting the API Instance”import com.hytale.achievements.api.AchievementAPI;
// Get API instanceAchievementAPI api = AchievementAPI.getInstance();if (api == null) { // Achievement plugin not loaded return;}
// Or with availability checkif (AchievementAPI.isAvailable()) { AchievementAPI api = AchievementAPI.getInstance(); // ...}Achievement Query Methods
Section titled “Achievement Query Methods”| Method | Description |
|---|---|
hasAchievement(Player, String) | Check if player has achievement |
hasAchievement(UUID, String) | Check by UUID |
getProgress(Player, String) | Current progress |
getRequiredProgress(String) | Required progress to unlock |
getUnlockedAchievements(Player) | Set of all unlocked IDs |
getUnlockedCount(Player) | Number of unlocked achievements |
getTotalAchievementCount() | Total number of achievements |
getUnlockTimestamp(Player, String) | Unix timestamp of unlock |
getAllAchievementIds() | List of all achievement IDs |
getAchievementsByCategory(String) | Achievements in a category |
achievementExists(String) | Check if achievement exists |
Title Query Methods
Section titled “Title Query Methods”| Method | Description |
|---|---|
getActiveTitle(Player) | Id of the achievement whose title is active (or null) |
getActiveTitleId(Player) | Id of the active title (or null), since 3.0.0 |
getUnlockedTitles(Player) | Set of all unlocked titles |
getTitleDisplayName(Player, String) | Translated name of a title in the player’s language |
setActiveTitle(Player, String) | Set the active title (title id or achievement id; null clears) |
Modification Methods
Section titled “Modification Methods”| Method | Description |
|---|---|
grantAchievement(Player, String) | Grant achievement (with rewards) |
revokeAchievement(Player, String) | Revoke achievement: points back, uncollected rewards dropped, title refreshed |
setProgress(Player, String, int) | Set progress directly (does not unlock) |
incrementProgress(Player, String, int) | Increment progress of this achievement and check the unlock. An id that is a trigger type (e.g. dungeon_complete_any) counts as that trigger |
Points Methods
Section titled “Points Methods”| Method | Description |
|---|---|
getAchievementPoints(Player) | Current balance |
addAchievementPoints(Player, int) | Add points |
spendAchievementPoints(Player, int) | Spend points; false when the balance is too low |
Event Listeners
Section titled “Event Listeners”| Method | Description |
|---|---|
onAchievementUnlock(BiConsumer<Player, String>) | Listener for unlock events |
removeUnlockListener(BiConsumer) | Remove unlock listener |
onProgressUpdate(BiConsumer<Player, String>) | Listener for progress updates |
removeProgressListener(BiConsumer) | Remove progress listener |
Statistics Methods
Section titled “Statistics Methods”| Method | Description |
|---|---|
getTotalBlocksMined(Player) | Total blocks mined |
getTotalBlocksPlaced(Player) | Total blocks placed |
getTotalMobKills(Player) | Total mob kills |
getPlaytimeMinutes(Player) | Playtime in minutes |
Usage Examples
Section titled “Usage Examples”Check Achievement Status
Section titled “Check Achievement Status”AchievementAPI api = AchievementAPI.getInstance();
// Does the player have "monster_hunter_1"?if (api.hasAchievement(player, "monster_hunter_1")) { player.sendMessage("You are a monster hunter!");}
// Show progressint progress = api.getProgress(player, "blocks_mined_1000");int required = api.getRequiredProgress("blocks_mined_1000");player.sendMessage("Progress: " + progress + "/" + required);React to Achievement Unlocks
Section titled “React to Achievement Unlocks”AchievementAPI api = AchievementAPI.getInstance();
api.onAchievementUnlock((player, achievementId) -> { // Firework effect or similar spawnFirework(player.getLocation());
// Logging LOGGER.info(player.getDisplayName() + " unlocked " + achievementId + "!");});Grant Achievement Programmatically
Section titled “Grant Achievement Programmatically”AchievementAPI api = AchievementAPI.getInstance();
// Grant achievement on special eventif (specialEventTriggered) { boolean granted = api.grantAchievement(player, "special_event_2026"); if (granted) { // Successfully granted } else { // Player already had it or achievement doesn't exist }}Statistics for Leaderboard
Section titled “Statistics for Leaderboard”AchievementAPI api = AchievementAPI.getInstance();
int blocksMinedTotal = api.getTotalBlocksMined(player);int achievementCount = api.getUnlockedCount(player);long playtimeMinutes = api.getPlaytimeMinutes(player);
// Use for leaderboard...Thread Safety
Section titled “Thread Safety”- The API is thread-safe using
CopyOnWriteArrayListfor listeners; since 3.0.0 unlock and progress listeners really fire - All query methods can be called from any thread
- Modification methods should ideally be called from the main thread