main-menu.yml

guis/main-menu.yml is the menu /index opens. You can retheme it freely - change the title, size, background and buttons. After editing, run /indexadmin reload.

How the file works

The root holds Title, Size (a multiple of 9) and an Items section. Each entry in Items is an item placed with Slot: (one number) or Slots: (a list where each entry is a number or an a-b inclusive range). Every slot must be inside Size.

Title: "Item Index"
Size: 36

Items:
  Filler-Item:
    Material: BLACK_STAINED_GLASS_PANE
    Slots: [0-35]
    Name: "&r"

  Profile-Item:
    Material: PLAYER_HEAD
    Slot: 3
    Head-Owner: TARGET
    Name: "&d&lIndex Profile"
    Lore:
      - "&5 - &7Player: &f{target}"
      - "&5 - &7Collected: &f{discovered}&8/&f{total} &7items"
      - "&5 - &7Progress: &f{percentage}%"
      - "&5 - &7Rank: &f#{rank}"

  Building-Category:
    Material: BRICKS
    Slot: 11
    Name: "&6&lBuilding Category"
    Lore:
      - "&e - &7Collected: &f{collected}&8/&f{category-total} &7items"
      - "&e - &7Progress: &f{category-percentage}%"
    Category: building

  Close-Item:
    Material: BARRIER
    Slot: 31
    Name: "&c&lClose Menu"
    Actions:
      - "[close]"

When items overlap, the item with the fewest slots wins the slot. A full-size filler never covers a button, so you can fill the whole menu and place buttons on top.

Deleted keys stay deleted: the file is read without filling in defaults, so removing a lore line or an item really removes it. A missing Title or an invalid item fails the load.

Item fields

The standard item fields all work: Material, Amount, Name, Lore, Glow, Item-Flags, Base64 (head texture), Custom-Model-Data, Item-Model, Enchantments and Hide-Tooltip.

OptimalIndex adds two keys:

Key	Description
Category	A category id (file name in categories/). Clicking the item opens that category, and the item gets the category tokens. An id with no matching file fails the load.
Head-Owner	TARGET (the player whose index is shown) or VIEWER (the player looking). Sets the skull owner of a PLAYER_HEAD. Anything else fails the load.

The shipped Profile-Item uses Head-Owner: TARGET, so /index Notch shows Notch’s head rather than yours.

Shipped items

Key	Slot	Does
Filler-Item	0-35	Black glass background.
Barrier-Item	10-16, 19-25	Glass panes behind the category buttons.
Profile-Item	3	The target’s head with their totals and rank.
Leaderboard-Item	5	The {leaderboard} list, the viewer’s {self} line and the {completed} count.
Building-Category … Redstone-Category	11-15	Building, Colorful, Natural, Functional, Redstone.
Tools-Category … Potions-Category	20-24	Tools, Combat, Food, Ingredients, Potions.
Close-Item	31	[close].

Item keys are only names. Rename them freely; the Category: value is what links a button to a category.

Actions

An Actions list runs in order on click. A Category item needs no actions.

Action	Does
[close]	Close the menu.
[console] <cmd>	Run a command as console.
[player] <cmd> / [command] <cmd>	Run a command as the player.
[message] <text>	Send the player a chat message.
[broadcast] <text>	Send a message to everyone.
[actionbar] <text>	Show an action bar message.
[title] title;subtitle;in;stay;out	Show a title. Times are in ticks.
[sound] NAME;volume;pitch	Play a sound.

The argument is the text after ]. {player}, {uuid} and, with PlaceholderAPI installed, %...% are resolved in it.

The page and filter actions ([main], [previous], [next], [filter]) belong to the category menu only.

Tokens

The title gets {player}, {viewer} and {target}. Every item gets:

Token	Value
{player}, {viewer}	The player looking at the menu.
{target}	The player whose index is shown.
{discovered}	The target’s discovered entries.
{total}	Unique entries in the index.
{percentage}	The target’s completion, rounded down.
{rank}	The target’s leaderboard rank (Leaderboard.Unranked before the first refresh).
{completed}	Players who have completed the whole index.
{self}	The viewer’s own leaderboard line (Leaderboard.Self).
{leaderboard}	List token: one lore line per leaderboard position (Leaderboard.Positions). Put it alone on its line.

Items with Category: also get:

Token	Value
{category}	The category’s Display-Name.
{collected}	Entries of that category the target has discovered.
{category-total}	Entries in the category.
{category-percentage}	The target’s completion of the category, rounded down.

Numbers are printed with thousands separators. The leaderboard lines are formatted in config.yml.