Milestones - Framework and Tracking

Implements features allowing content packs to add trackable milestones with various reward functionality

Description

Milestones - Framework and Tracking

Plugin Overview

This plugin centres around a system of creating "milestones" within the asset editor that can be tracked within game for player progression, direction and rewarding exploration. Upon completion of a milestone either items can be awarded or complex interaction chains can be started.

Read for players

This mod itself adds no milestones to the game, it just creates the base framework for packs to add their own milestones so will be a dependency for any packs that utilise this plugin. For a basic pack of milestones you can download the Simple Milestones Pack with 162 generic milestones with various rewards. If you would like to add your own milestones read on.

Read for mod creators

Purpose

Currently and primarily this plugin is intended to be used via the asset editor however as I expand its functionality and scope I will build an API for code based integration. My goal is to create a centralised system for various event based tracking and allowing pack creators a high degree of control over how these milestones are tracked and interacted with allowing connection with other systems for complex world progression.

Functionality Overview

The Milestones plugin provides comprehensive tracking for various player activities:

Block Breaking - Track when players break specific blocks or block types
Block Placing - Monitor when players place blocks
Block Using - Track interactions with blocks (campfires, workbenches, etc.)
Interactive Pickups - Monitor when players pick up items with F key (crops, mushrooms, placed items)
Automatic Pickups - Track items automatically collected from the ground (drops, inventory transfers, mob loot)
Crafting - Track when players craft specific items
Entity Killing - Record when players defeat entities
Zone Discovery - Track when players enter new zones
Biome Discovery - Monitor when players discover new biomes
Runtime Refresh - New milestones created in the Asset Editor are immediately available without server restart

Each milestone type supports:

Exact matching - Target a specific block/item/entity ID
Partial matching - Match any ID containing the target string (e.g., "Ore" matches all ore types)
Unique tracking - Count unique types instead of total quantity (works with partial matching)
Target lists - Track progress across multiple specific IDs
Zone context - Limit tracking to specific zones (biome discovery)

Commands

The plugin provides several in-game commands:

/milestones - Opens the milestone UI browser with category filtering
/listmilestones - Lists all registered milestones (admin/debug)
/availablemilestones - Shows milestones available to the player

All commands respect Hytale's permission system.

Usage

Asset Overview

Milestones are created as JSON asset files placed in the Server/Milestones/ directory of your asset pack. Each milestone is a standalone JSON file that the plugin will automatically load on server start.

Basic Structure:

{
  "DisplayName": "Milestone Name",
  "Description": "What the player needs to do",
  "IconText": "🎯",
  "Type": "BREAK_BLOCK",
  "TargetId": "Block_Stone",
  "RequiredCount": 10,
  "Category": "Mining",
  "ShowReward": true,
  "Rewards": [
    {
      "ItemId": "Tool_Pickaxe",
      "Quantity": 1
    }
  ],
  "XpReward": 50
}

Available Types:

BREAK_BLOCK - Track blocks broken
PLACE_BLOCK - Track blocks placed
USE_BLOCK - Track block interactions
INTERACTABLE_PICKUP - Track interactive item pickups (F key - harvesting crops, picking up placed items)
ITEM_PICKUP - Track automatic item pickups (dropped items from ground, inventory transfers, mob drops)
ITEM_COLLECTION - (Legacy, use INTERACTABLE_PICKUP instead)
CRAFTING - Track items crafted
ENTITY_KILL - Track entities killed (supports TrackUnique for counting unique entity types)
ZONE_DISCOVERY - Track zones entered
BIOME_DISCOVERY - Track biomes discovered

Track Unique: Most types support "TrackUnique": true with "PartialMatch": true to count unique variants instead of total quantity:

ENTITY_KILL with TrackUnique - Count unique enemy types killed (e.g., 5 different goblin variants = 5 progress)
CRAFTING with TrackUnique - Count unique recipes crafted
BREAK_BLOCK with TrackUnique - Count unique block types broken
And more…

Common Fields:

DisplayName - Shown in UI (required)
Description - Shown in UI (required)
IconText - Emoji or text icon (optional)
IconItemId - Item ID to use as icon (optional)
Type - Milestone type (required)
Category - UI category grouping (optional)
ShowReward - Show rewards in UI (default: false)
XpReward - XP awarded on completion (optional)
Rewards - List of item rewards (optional)

Asset Deep-dive

Matching Modes:

Specific Matching (default):

{
  "Type": "BREAK_BLOCK",
  "TargetId": "Alchemy_Cauldron",
  "PartialMatch": false,
  "RequiredCount": 2
}

Tracks only exact matches of "Alchemy_Cauldron".

Partial Matching:

{
  "Type": "ITEM_COLLECTION",
  "TargetId": "Armor",
  "PartialMatch": true,
  "RequiredCount": 5
}

Tracks any item ID containing "Armor" (e.g., Armor_Bronze_Chest, Armor_Wood_Chest).

Track Unique:

{
  "Type": "BREAK_BLOCK",
  "TargetId": "Rock",
  "PartialMatch": true,
  "TrackUnique": true,
  "RequiredCount": 2
}

Counts how many different types matching "Rock" have been broken (not total quantity).

Target ID Lists:

{
  "Type": "CRAFTING",
  "TargetIds": [
    "Armor_Bronze_Chest",
    "Armor_Wood_Chest",
    "Armor_Leather_Heavy_Chest"
  ],
  "RequiredCount": 2
}

Tracks total count across all listed IDs.

Zone Context (Biome Discovery only):

{
  "Type": "BIOME_DISCOVERY",
  "TargetId": "biome",
  "PartialMatch": true,
  "TrackUnique": true,
  "ZoneContext": "Devastated_Lands",
  "RequiredCount": 2
}

Only counts biomes discovered within the specified zone.

Rewards System:

Item Rewards:

"Rewards": [
  {
    "ItemId": "Armor_Bronze_Chest",
    "Quantity": 1
  },
  {
    "ItemId": "Container_Bucket",
    "Quantity": 5
  }
]

XP Rewards:

"XpReward": 100

Note: XP rewards are currently stored but have no in-game functionality yet. This feature is planned for future updates.

Interaction Chains:

"OnCompleteInteractionId": "CustomRewardInteraction"

Triggers a custom interaction when milestone completes (requires custom interaction assets).

Prerequisites:

"PrerequisiteMilestones": [
  "Beginner_Mining_Quest",
  "First_Ore_Collection"
]

Milestone only becomes available after completing prerequisites.

Custom Interactions

The plugin provides two custom interactions that can be used in the Asset Editor for NPCs, blocks, items, and other interactive content:

CheckMilestone Interaction

ID: *CheckMilestone

Checks if a player has completed a specific milestone and provides feedback via notifications.

Use Cases:

Gate NPC dialogue or quest progression behind milestone completion
Lock doors or areas until specific milestones are achieved
Create conditional rewards or interactions based on milestone status
Provide progress feedback to players

Configuration:

{
  "Type": "*CheckMilestone",
  "Milestone ID": "my_milestone_id"
}

Behavior:

If Complete: Sends green success notification showing milestone name + "Complete", returns Finished state (interaction succeeds)
If Incomplete: Sends yellow warning notification showing progress (e.g., "Mining Challenge - Progress: 3/10"), returns Failed state (interaction fails)
If Invalid: Sends red danger notification if milestone ID not found, returns Failed state

Example Usage - Gated NPC Dialogue:

{
  "RootInteractions": [
    {
      "Type": "*CheckMilestone",
      "Milestone ID": "Complete_Basic_Training"
    },
    {
      "Type": "*Dialogue",
      "DialogueId": "Advanced_Trainer_Welcome"
    }
  ]
}

The dialogue only triggers if the "Complete_Basic_Training" milestone is finished.

OpenMilestonesUI Interaction

ID: *OpenMilestonesUI

Opens the milestone browser UI for the player, providing easy access to view all available milestones and their progress.

Use Cases:

Add milestone boards or quest givers to your world
Create dedicated milestone viewing stations
Provide quick UI access from NPCs or signs
Design milestone hubs or achievement halls

Configuration:

{
  "Type": "*OpenMilestonesUI"
}

Behavior:

Opens the full milestone UI with category filtering
Shows all available milestones, progress, and rewards
Always returns Finished state

Example Usage - Quest Board:

{
  "RootInteractions": [
    {
      "Type": "*OpenMilestonesUI"
    }
  ]
}

Attach to a block or NPC to create an interactive milestone viewer.

Combination Setups

Progressive Quest Chains:

// milestone_mining_1.json
{
  "DisplayName": "First Steps in Mining",
  "Type": "BREAK_BLOCK",
  "TargetId": "Block_Ore_Copper",
  "RequiredCount": 1,
  "Rewards": [{"ItemId": "Tool_Pickaxe_Basic", "Quantity": 1}]
}

// milestone_mining_2.json
{
  "DisplayName": "Ore Collector",
  "Type": "BREAK_BLOCK",
  "TargetId": "Ore",
  "PartialMatch": true,
  "RequiredCount": 2,
  "PrerequisiteMilestones": ["First_Steps_in_Mining"]
}

Collection Challenges:

{
  "DisplayName": "Armor Collector",
  "Type": "ITEM_COLLECTION",
  "TargetIds": [
    "Armor_Bronze_Chest",
    "Armor_Wood_Chest",
    "Armor_Leather_Heavy_Chest",
    "Armor_Cloth_Cotton_Chest"
  ],
  "RequiredCount": 2,
  "ShowReward": true
}

Exploration Achievements:

{
  "DisplayName": "World Explorer",
  "Type": "ZONE_DISCOVERY",
  "TargetIds": [
    "Zone_Emerald_Grove",
    "Zone_Howling_Sands",
    "Zone_Borea",
    "Zone_Devastated_Lands"
  ],
  "RequiredCount": 2
}

Pack Distribution

This plugin is distributed without milestone assets. To use it:

Install the Plugin - Download and install this plugin JAR file
Download Milestone Packs - Get separate milestone asset packs that define actual milestones
Install Packs - Place milestone pack assets in your server's asset directory

For Pack Creators:

Create your own milestone JSON files in Server/Milestones/
Include this plugin as a dependency
Distribute your pack separately as an asset pack

Related Mods/Packs

Simple Milestones Pack - Starter collection of 162 generic milestones with various rewards (distributed separately)

Development & Support

Asset Editor integration for easy milestone creation
Persistent data storage using Hytale's ECS