Creating Categories

Add your own index category - the category file, its entries, potion entries and the main menu button.

Categories are config, not commands. You add one by adding a file to categories/ and a button for it in the main menu. You need optimalindex.admin to reload.

1. Add a file to categories/

Create plugins/OptimalIndex/categories/ores.yml. The file name (without .yml) is the category id - here ores. Use lower case ids, because the PlaceholderAPI placeholders match them in lower case.

Display-Name: "&b&lOres Category"
Title: "Ores Category"

Entries:
  - COAL_ORE
  - DEEPSLATE_COAL_ORE
  - IRON_ORE
  - DEEPSLATE_IRON_ORE
  - COPPER_ORE
  - GOLD_ORE
  - REDSTONE_ORE
  - LAPIS_ORE
  - DIAMOND_ORE
  - EMERALD_ORE
  - NETHER_QUARTZ_ORE
  - ANCIENT_DEBRIS

Key	Used for
`Display-Name`	The category’s name in `{category}` (menus and the `DISCOVERED` / `CATEGORY-COMPLETED` messages).
`Title`	The title of this category’s menu.
`Entries`	The items in the category, in menu order.

Full field list: categories reference.

2. Add entries

Each line of Entries is one item. The order of the list is the order of the menu.

A plain material name is the usual form. Its display name is the client’s own translation of the item, so every player sees it in their own language:

Entries:
  - DIAMOND_ORE
  - ANCIENT_DEBRIS

A section sets your own name, and is the only way to add a potion type:

Entries:
  - {Material: POTION, Potion-Type: STRONG_HEALING, Name: "Potion of Healing II"}
  - {Material: TIPPED_ARROW, Potion-Type: POISON, Name: "Tipped Arrow Poison"}
  - {Material: DIAMOND, Name: "&bShiny Diamond"}

Name is required in a section. Potion-Type is optional and only allowed on items that can hold a potion (POTION, SPLASH_POTION, LINGERING_POTION, TIPPED_ARROW). Each potion type is its own entry, so a Potion of Swiftness, Swiftness II and Swiftness (Extended) are three entries.

A category is only reachable from /index once the main menu has a button for it. Open guis/main-menu.yml and add an item with Category: <id>:

Items:
  Ores-Category:
    Material: DIAMOND_ORE
    Slot: 25
    Name: "&b&lOres Category"
    Lore:
      - "&7Every ore found underground."
      - ""
      - "&bInformation:"
      - "&3 - &7Collected: &f{collected}&8/&f{category-total} &7items"
      - "&3 - &7Progress: &f{category-percentage}%"
      - ""
      - "&e➥ Click to view category!"
    Category: ores

Clicking the item opens the category; it needs no Actions. The slot must be inside the menu Size. On the shipped 36-slot menu, slot 25 is still free on the second row of buttons (it is covered by the glass background, which a button always wins over).

4. Reload

/indexadmin reload

The category appears in /index immediately. Online players are recounted against the new catalog right away, so items they already have in their data count at once. Test it with /indexadmin discover <you> diamond_ore and undo it with /indexadmin reset <you> diamond_ore.

The same item can sit in several categories. It is still one entry: discovering it fills every category that lists it, and it counts once towards {total}.

When you use the section form, give the item the same Name in every category. Two categories naming the same entry differently fail the load. Plain material entries are always named the same way, so they never clash.

Removing items and categories

Removing an entry (or a whole category file) drops it from every count after a reload. The discovery stays in the database, so adding the entry back later restores it for players who had it.
Online players are recounted on reload; offline players are recounted the next time they join, so the leaderboard catches up as they come back.
When you delete a category file, also delete its button from guis/main-menu.yml. A Category: pointing at a missing file fails the load.

Notes

The startup banner prints how many categories and unique items were loaded. Check it after bigger edits.
Loading fails loudly. A missing Display-Name, Title or Entries, an unknown material, an item that cannot be obtained (air, technical blocks), a Potion-Type on an item that cannot hold one, or the same entry listed twice in one category all stop the load with a console error naming the file.
A category without a button still counts towards the index total and the placeholders; players just cannot open it to see what they are missing. Give every category a button.
The menu layout (entry slots, buttons, entry lore) is shared by every category and lives in guis/category-menu.yml. Only the title comes from the category file.