Skip to main content

API Reference

Technical reference for plugin developers and advanced users.

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​

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

Kills​

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

ItemsCrafted​

interface CraftTrigger {
  type: "items_crafted";
  target: string;  // Item ID or "any"
  count: number;
}

ZonesDiscovered​

interface ZoneTrigger {
  type: "zones_discovered";
  target: string;  // Zone ID or "any"
  count: number;
}

ChatMessages​

interface ChatTrigger {
  type: "chat_messages";
  count: number;
}

PlaytimeMinutes​

interface PlaytimeTrigger {
  type: "playtime_minutes";
  count: number;  // Minutes
}

DistanceWalked​

interface DistanceTrigger {
  type: "distance_walked";
  count: number;  // Blocks
}

FullArmorSet​

interface ArmorTrigger {
  type: "full_armor_set";
  target: ArmorMaterial;
}

type ArmorMaterial =
  | "iron" | "copper" | "bronze" | "steel"
  | "cobalt" | "mithril" | "thorium"
  | "adamantite" | "onyxium" | "prisma";

EquipItem​

interface EquipTrigger {
  type: "equip_item";
  target: string;  // Item ID
}

Manual​

interface ManualTrigger {
  type: "manual";
}

AutoOnPrerequisites​

interface AutoTrigger {
  type: "auto_on_prerequisites";
}

Reward Types​

Item Reward​

interface ItemReward {
  type: "item";
  itemId: string;  // Hytale item ID
  amount: number;  // Quantity (1-64)
}

Command Reward​

interface CommandReward {
  type: "command";
  command: string;     // Command to execute (use {player} placeholder)
  executor: Executor;  // Who runs the command
}

type Executor = "console" | "player";

Title Definition​

interface Title {
  id: string;     // Title identifier (for localization)
  color: string;  // Hex color code (e.g., "#FFD700")
}

Additional Info​

interface AdditionalInfo {
  text: string;   // Display text
  color: string;  // Hex color code
}

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;
  };

  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​

Achievement Keys​

achievements.name.<id>     - Achievement display name
achievements.desc.<id>     - Achievement description
achievements.title.<id>    - Title display name

UI Keys​

achievements.ui.gallery    - Gallery window title
achievements.ui.search     - Search placeholder
achievements.ui.all        - "All" filter
achievements.ui.combat     - "Combat" filter
achievements.ui.progression - "Progression" filter
achievements.ui.exploration - "Exploration" filter
achievements.ui.social     - "Social" filter
achievements.ui.completed  - "Completed" filter
achievements.ui.locked     - "Locked" status
achievements.ui.unlocked   - "Unlocked" status
achievements.ui.progress   - "Progress" label
achievements.ui.requires   - "Requires" label
achievements.ui.reward     - "Reward" label
achievements.ui.title      - "Title" label
achievements.ui.prev       - "Previous" button
achievements.ui.next       - "Next" button
achievements.ui.page       - "Page" label

Command Keys​

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

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​

Plugin Data​

plugins/achievements/
├── config.json              - Main configuration
├── achievements.json        - Default achievements (auto-generated)
├── custom_achievements.json - Custom achievements (user-created)
├── playerdata/              - Player achievement data
│   └── <uuid>.json
└── export/                  - Statistics export
    ├── global_stats.json
    ├── leaderboard.json
    └── recent_unlocks.json

Resource Files​

Server/Languages/
├── en-US/
│   └── achievements.lang
└── de-DE/
    └── achievements.lang

Common/UI/Custom/Pages/Achievements/
├── AchievementGallery.ui
├── AchievementToast.ui
└── TitleSelection.ui

Java Package Structure​

com.hytale.achievements/
├── AchievementPlugin.java       - Main plugin class
├── commands/
│   ├── AchievementCommand.java  - /achievements command
│   ├── TitleCommand.java        - /titles command
│   └── AchievementAdminCommand.java
├── config/
│   ├── AchievementConfig.java   - Config model
│   ├── AchievementDefinition.java
│   ├── Reward.java
│   └── AdditionalInfo.java
├── data/
│   └── PlayerAchievementData.java
├── display/
│   ├── TitleDisplayManager.java
│   ├── ToastManager.java
│   ├── AchievementToastHud.java
│   └── EmptyHud.java
├── export/
│   └── StatsExporter.java
├── integration/
│   ├── LuckPermsIntegration.java
│   └── MHUDIntegration.java
├── service/
│   └── AchievementService.java
├── tracking/
│   ├── BlockBreakTrackerSystem.java
│   ├── BlockPlaceTrackerSystem.java
│   ├── CombatTracker.java
│   ├── ExplorationTracker.java
│   ├── MovementTracker.java
│   └── SocialTracker.java
├── ui/
│   ├── AchievementGalleryPage.java
│   └── TitleSelectionPage.java
└── util/
    └── AdventureConverter.java

Events​

Achievement Events (Internal)​

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

Listening to Achievement Unlocks​

Currently, achievement unlocks are internal events. Future versions may expose an API for external plugins to listen.