Skip to content
BattleStudio

Information

OptimalMilestones features, categories, progress types, commands, permissions, placeholders and tokens in one reference.

BattleStudio plugin

OptimalMilestones

Numbered milestone tracks per category, fed by block, mob and prison events or any PlaceholderAPI number. Players claim each milestone once for its rewards.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryPlaceholderAPI
Buy on BuiltByBitInstallation guideGet support

OptimalMilestones gives players one or more milestone categories - Blocks, Playtime, Mobs, whatever you define - and each category is a numbered track of milestones. A milestone has a cumulative Required threshold and a set of reward commands. Reach the threshold and the milestone becomes claimable; the player claims it once in /milestones and the rewards run from console.

Every category is one file in the milestones/ folder. Add a file and you get a new track, with its own selector icon in the menu, its own milestone icons and its own placeholders.

OptimalMilestones runs on top of OptimalLibrary, a separate free plugin that has to be installed alongside it. See Installation.

How it works

Section titled “How it works”
  • Progress is a number per player and category. Where it comes from depends on the category’s Progress.Type (see below).
  • Thresholds are cumulative. Milestone 3 at Required: 5000 means 5,000 in total, not 5,000 more than milestone 2.
  • Unlocking happens the moment progress reaches a milestone’s Required. A timer checks every online player every Settings.Notify-Interval seconds and sends MILESTONE-UNLOCKED (with a screen title and a sound) once per newly reached milestone.
  • Claiming is always manual: the player clicks the milestone in /milestones. The claim is saved to the database straight away, so a crash can never let the same milestone be claimed twice, then the milestone’s Commands run from console with {player} filled in.
  • Claims never expire and the plugin never resets progress on its own. Only /milestonesadmin reset clears them.

The unlock notification list is not saved. When a player joins, everything already claimable is marked as notified, so relogging never re-sends old unlock messages.

Progress types

Section titled “Progress types”
Type Progress comes from Admin-adjustable
API A counter stored by the plugin, fed by one named event source. Every matching event adds +1. Yes
PLACEHOLDER A numeric PlaceholderAPI placeholder, read live whenever progress is needed. No

API sources:

Source Counts
BLOCK_BREAK Blocks broken (cancelled breaks are ignored)
BLOCK_PLACE Blocks placed (cancelled places are ignored)
MOB_KILL Non-player entities killed by a player
PINNAPRISON PinnaPrison block mines (needs PinnaPrison)
EDDUNGEONS EdDungeons sword swings (needs EdDungeons)
RIVALHARVESTERHOE RivalHarvesterHoes block breaks (needs RivalHarvesterHoes)

There are no filters: no world, block or mob whitelist and no chance roll. Several categories may use the same source and each one gets its own +1. Full details are in Creating Categories.

Features

Section titled “Features”
  • Any number of categories, one file each, each with its own selector icon and menu slot
  • Two progress types: a built-in event counter or a live PlaceholderAPI value
  • Per-category Locked / Unclaimed / Claimed milestone icons with their own primary and secondary colors
  • Cumulative thresholds, Roman-numeral milestone labels and a configurable progress bar
  • Paged milestone grid that opens on the player’s first unclaimed milestone
  • Unlock notifications with a chat message, screen title and sound
  • Temporary feedback icons on refused clicks
  • Per-category PlaceholderAPI placeholders
  • Admin tools to give, take, set and reset progress, for online and offline players
  • SQLite storage with write-behind saving and instant claim saves
  • Folia-ready

Commands

Section titled “Commands”

Player - /milestones (aliases /ms, /milestone):

  • /milestones - open the menu on the default category (the enabled category with the lowest Order) · optimalmilestones.use
  • /milestones <category> - open the menu on a specific enabled category · optimalmilestones.use

Admin - /milestonesadmin (aliases /msadmin, /milestoneadmin) · all optimalmilestones.admin:

  • /milestonesadmin progress <give|take|set> <player> <category> <amount> - change a player’s counter. API categories only: a PLACEHOLDER category answers CATEGORY-NOT-TRACKED. <amount> must be a whole number of 0 or more. take never goes below 0.
  • /milestonesadmin reset <player> [category] - set progress to 0 and clear every claim, for one category or for all of them.
  • /milestonesadmin reload - reload config.yml, messages.yml, the menu file and every category file.

/milestonesadmin with no arguments, or with a wrong one, shows the MILESTONES-ADMIN-HELP panel. Both admin edits work on offline players, as long as the server has seen them before (they are in the server’s user cache). Otherwise the reply is INVALID-PLAYER. The confirmation message is sent once the change has been applied.

See Managing Progress for examples.

Permissions

Section titled “Permissions”
  • optimalmilestones.use - /milestones and the menu (default: everyone)
  • optimalmilestones.admin - every /milestonesadmin command (default: op)

Categories and milestones have no permission nodes of their own. Every player sees every enabled category.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. The identifier is optimalmilestones, and every placeholder is per category: replace <category> with the category id (its file name without .yml, lower case).

Placeholder Value
%optimalmilestones_<category>_progress% Current progress, plain number (12345).
%optimalmilestones_<category>_progress_formatted% Current progress, comma-grouped (12,345).
%optimalmilestones_<category>_completed% Milestones claimed.
%optimalmilestones_<category>_total% Milestones in the category (enabled ones only).
%optimalmilestones_<category>_reached% Milestones whose threshold is met, claimed or not.
%optimalmilestones_<category>_percent% Claimed out of total as a whole-number percentage (42), no % sign.

For example %optimalmilestones_blocks_progress_formatted%. An unknown category returns an empty string.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Which ones are available depends on where you use them.

Milestone icons (Milestone-Icons in a category file):

Token Value
{category} The category’s Display-Name.
{milestone} The milestone number as a Roman numeral (XII). Numbers above 3999 stay arabic.
{number} The milestone number (12).
{progress} The player’s progress, comma-grouped.
{required} The milestone’s Required, comma-grouped.
{progress-bar} Progress towards this milestone as a bar.
{percent} Progress towards this milestone, two decimals (42.50), no % sign.
{primary}, {secondary} The state’s Primary and Secondary colors.
{reward-lore} A lore line holding this token expands into the milestone’s Lore.

Category selector icons, menu items and menu title:

Token Value
{category} The category’s Display-Name.
{complete} Milestones claimed.
{total} Milestones in the category.
{reached} Thresholds met, claimed or not.
{progress} The player’s progress, comma-grouped.
{progress-bar}, {percent} Claimed out of total, as a bar and a two-decimal number.
{page}, {pages} Current page and page count (menu items and title).
{max-page}, {results} Page count again, and the number of milestones (menu items only).

Messages: see tokens per message.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex and MiniMessage (<gradient:...>, <rainbow>, <bold>, <#RRGGBB>, …). With PlaceholderAPI installed, %...% placeholders from any expansion work in messages, item names and lore, and menu action arguments. In messages, a line containing [center] is centred in chat.

Reference

Section titled “Reference”