Skip to content
BattleStudio

Information

OptimalIndex features, how discovery works, commands, permissions, placeholders, tokens and formatting in one reference.

BattleStudio plugin

OptimalIndex

Players discover every item by picking it up, then track their progress per category, on a live leaderboard and in a paged, filterable menu.

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

OptimalIndex is an item discovery index. Every item listed in a category starts out undiscovered; the first time a player picks it up (or has it in their inventory when it is scanned) it is discovered for good. /index shows the player’s progress per category, a discovery leaderboard, and a paged, filterable view of every item in each category.

Categories are plain files in categories/, one file per category. Ten ship by default (building, colorful, natural, functional, redstone, tools, combat, food, ingredients and potions), holding around 1,500 unique items between them, so the index is complete on first start.

How discovery works

Section titled “How discovery works”
  • Picking up an item discovers it (Settings.Discovery.Pickup). Cancelled pickups do not count.
  • Inventory scans (Settings.Discovery.Inventory-Scan) check the player’s whole inventory every time they close an inventory window, and once right after their data loads on join. This is what catches items a player crafted, bought or got from a command without picking them up.
  • Ignored game modes and worlds. Players in Ignored-Game-Modes (creative and spectator by default) or in a Disabled-Worlds world discover nothing. Admin grants ignore both checks.
  • Discoveries are permanent and stamped with the time they happened. That timestamp shows in the category menu as a date and a “time ago” line.
  • One entry, one count. An item listed in several categories is a single entry: it counts once towards the index total and fills every category it belongs to.
  • Potions are separate entries. An entry is either a plain material (oak_log) or a material plus a potion type (splash_potion:long_swiftness, tipped_arrow:healing). A typed potion never matches a plain POTION entry and vice versa.

When a discovery lands, the player gets DISCOVERED (or DISCOVERED-MULTIPLE when one scan finds several items at once), then CATEGORY-COMPLETED for every category it finished and INDEX-COMPLETED (with a screen title) when the whole index is done. Completing the index can also be broadcast to the whole server.

Features

Section titled “Features”
  • Any number of categories, each one a file with its own name, menu title and ordered item list
  • Plain material entries are named with the client’s own translation, so they show in each player’s language
  • Potions, splash and lingering potions and tipped arrows tracked per potion type, rendered in their effect colour
  • Discovery by pickup and by inventory scan, with ignored game modes and disabled worlds
  • Main menu with a profile head, a live leaderboard and one button per category
  • Paged category menu with an All / Found / Not Found filter
  • Discovered entries show when they were found (date plus “time ago”) and how many players have found each one
  • Leaderboard with per-position formats, your own position line and player-head sprites
  • View any player’s index, online or offline, with /index <player>
  • Admin commands to grant or remove single items or everything
  • PlaceholderAPI expansion for totals, percentages, rank and per-category progress
  • SQLite or MySQL storage, all writes off the main thread
  • Folia-ready

Commands

Section titled “Commands”

Player - /index (aliases /optimalindex, /collection):

  • /index - open your own index · optimalindex.use
  • /index <player> - open another player’s index · optimalindex.use and optimalindex.others. Works on offline players: they are looked up by their last known name. A name that never joined gets UNKNOWN-PLAYER.

Admin - /indexadmin (alias /optimalindexadmin) · all optimalindex.admin:

  • /indexadmin discover <player> <item|all> - discover one entry, or every entry, for an online player. The player gets the normal discovery messages and sounds.
  • /indexadmin reset <player> [item|all] - remove one discovery, or all of them, from an online player. Leaving out the item resets everything.
  • /indexadmin reload - reload every config file, menu and category.

<item> is an entry key: the material name in lower case (oak_log, diamond_sword), or material:potion_type for potions (potion:strong_healing, tipped_arrow:poison). The minecraft: prefix is optional and case does not matter. Tab completion lists every key.

/indexadmin with no arguments, or with a wrong one, prints the help panel (INDEX-ADMIN-HELP). The command is hidden from players without optimalindex.admin, so it does not show up in their tab completion at all.

Permissions

Section titled “Permissions”
  • optimalindex.use - /index and the menus (default: everyone)
  • optimalindex.others - /index <player> (default: everyone)
  • optimalindex.admin - every /indexadmin command (default: op)

Categories have no permission nodes. Every player sees every category.

Placeholders

Section titled “Placeholders”

With PlaceholderAPI installed, OptimalIndex registers the optimalindex expansion:

Placeholder Value
%optimalindex_discovered% Entries the player has discovered.
%optimalindex_total% Unique entries in the whole index.
%optimalindex_percentage% Index completion, rounded down (0-100).
%optimalindex_rank% The player’s leaderboard rank. Leaderboard.Unranked before the first leaderboard refresh.
%optimalindex_completed% Players who have completed the whole index.
%optimalindex_category_<id>% Entries the player has discovered in that category.
%optimalindex_category_<id>_total% Entries in that category.

<id> is the category’s file name without .yml (building, potions). Keep category file names lower case, because the placeholder is matched in lower case.

Placeholder numbers are plain (1234); the menus print them with thousands separators (1,234).

PlaceholderAPI also resolves %...% placeholders from other plugins inside messages, menu items and menu action arguments.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Which ones a field gets depends on where it is:

Token Value Where
{player}, {viewer} The player looking at the menu. Menus
{target} The player whose index is shown (the viewer, or the player from /index <player>). Menus
{discovered}, {total}, {percentage} The target’s discovered count, the index total and the completion percentage. Main menu, discovery messages (no {percentage} there)
{rank} The target’s leaderboard rank. Main menu
{completed} Players who completed the whole index. Main menu
{leaderboard} One line per leaderboard position. A list token: put it on its own lore line. Main menu
{self} The viewer’s own leaderboard line. Main menu
{category}, {collected}, {category-total}, {category-percentage} The category’s display name, the target’s discovered count in it, its size and completion percentage. Category items, category menu
{filter}, {filters} The active filter name, and the list of every filter (a list token). Category menu
{page}, {pages}, {results} Current page, page count and the number of entries the filter shows. Category menu items
{item}, {found} The entry’s name and how many players have discovered it. Category entries
{date}, {time-ago} When the target discovered the entry. Discovered entries

Every token per file is listed on its config page: main menu, category menu and messages.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and, with PlaceholderAPI installed, %...% in messages, menu items and action arguments. <gradient> accepts comma-separated hex stops.

The MiniMessage <head:name> tag draws a small player-head sprite. The shipped leaderboard lines use <head:{name}> to show each player’s face next to their name, and <lang:...> is how plain entries get their translated item names.

Reference

Section titled “Reference”