Skip to content

API Reference

Technical reference for plugin developers and advanced users. Includes the public API for external plugin integration.

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";
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:

ValueMatches
"any"All entities
"any_mob"All non-player entities
"any_player"All players
"Spider"Exact entity type
interface CraftTrigger {
type: "items_crafted";
target: string; // Item ID or "any"
count: number;
}
interface ZoneTrigger {
type: "zones_discovered";
target: string; // Zone ID or "any"
count: number;
}
interface ChatTrigger {
type: "chat_messages";
count: number;
}
interface PlaytimeTrigger {
type: "playtime_minutes";
count: number; // Minutes
}
interface DistanceTrigger {
type: "distance_walked";
count: number; // Blocks
}
interface ArmorTrigger {
type: "full_armor_set";
target: ArmorMaterial;
}
type ArmorMaterial =
| "iron" | "copper" | "bronze" | "steel"
| "cobalt" | "mithril" | "thorium"
| "adamantite" | "onyxium" | "prisma";
interface EquipTrigger {
type: "equip_item";
target: string; // Item ID
}
interface ManualTrigger {
type: "manual";
}
interface AutoTrigger {
type: "auto_on_prerequisites";
}
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.

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.

interface RpgLevelTrigger {
type: "rpg_level";
target: string; // Level number as string
count: number; // Usually 1
}
interface RpgXpTrigger {
type: "rpg_xp";
target: "any";
count: number; // Total XP required
}
interface ItemReward {
type: "item";
itemId: string; // Hytale item ID
amount: number; // Quantity (1-64)
}
interface CommandReward {
type: "command";
command: string; // Command to execute (use {player} placeholder)
executor: Executor; // Who runs the command
}
type Executor = "console" | "player";
interface LootbagReward {
type: "lootbag";
lootbagId: string; // ID from lootbags.json
}
interface Title {
id: string; // Title identifier (for localization)
color?: string; // Hex color code (default: "#FFFFFF" white)
}
interface AdditionalInfo {
text: string; // Display text
color?: string; // Hex color code (default: "#AAAAAA" gray)
}
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;
};
};
}
achievements.name.<id> - Achievement display name
achievements.desc.<id> - Achievement description
achievements.title.<id> - Title display name

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.

achievements.cmd.grant.success - Grant success message
achievements.cmd.grant.already - Already unlocked message
achievements.cmd.revoke.success - Revoke success message
achievements.cmd.revoke.not_unlocked - Not unlocked message
achievements.cmd.list.header - List header format
achievements.cmd.list.empty - Empty list message
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"
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 actions

The plugin tracks these Hytale events:

EventTrigger Type
BlockBreakEventblocks_mined
BlockPlaceEventblocks_placed
EntityDeathEventkills
PlayerCraftEventitems_crafted
PlayerMoveEventdistance_walked
PlayerChatEventchat_messages
ZoneEnterEventzones_discovered
PlayerEquipEventequip_item, full_armor_set
PlayerJoinEventweekend_login (checks day of week)

External plugins can interact with the Achievement System through a stable public API.

import com.hytale.achievements.api.AchievementAPI;
// Get API instance
AchievementAPI api = AchievementAPI.getInstance();
if (api == null) {
// Achievement plugin not loaded
return;
}
// Or with availability check
if (AchievementAPI.isAvailable()) {
AchievementAPI api = AchievementAPI.getInstance();
// ...
}
MethodDescription
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
MethodDescription
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)
MethodDescription
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
MethodDescription
getAchievementPoints(Player)Current balance
addAchievementPoints(Player, int)Add points
spendAchievementPoints(Player, int)Spend points; false when the balance is too low
MethodDescription
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
MethodDescription
getTotalBlocksMined(Player)Total blocks mined
getTotalBlocksPlaced(Player)Total blocks placed
getTotalMobKills(Player)Total mob kills
getPlaytimeMinutes(Player)Playtime in minutes
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 progress
int progress = api.getProgress(player, "blocks_mined_1000");
int required = api.getRequiredProgress("blocks_mined_1000");
player.sendMessage("Progress: " + progress + "/" + required);
AchievementAPI api = AchievementAPI.getInstance();
api.onAchievementUnlock((player, achievementId) -> {
// Firework effect or similar
spawnFirework(player.getLocation());
// Logging
LOGGER.info(player.getDisplayName() + " unlocked " + achievementId + "!");
});
AchievementAPI api = AchievementAPI.getInstance();
// Grant achievement on special event
if (specialEventTriggered) {
boolean granted = api.grantAchievement(player, "special_event_2026");
if (granted) {
// Successfully granted
} else {
// Player already had it or achievement doesn't exist
}
}
AchievementAPI api = AchievementAPI.getInstance();
int blocksMinedTotal = api.getTotalBlocksMined(player);
int achievementCount = api.getUnlockedCount(player);
long playtimeMinutes = api.getPlaytimeMinutes(player);
// Use for leaderboard...
  • The API is thread-safe using CopyOnWriteArrayList for 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