> For the complete documentation index, see [llms.txt](https://hythium-studios.gitbook.io/wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hythium-studios.gitbook.io/wiki/plugins/hythiummenus.md).

# HythiumMenus

**HythiumMenus** is a high-performance interface management suite built exclusively for modern Minecraft servers (**Paper 1.21.4+**). It seamlessly bridges two essential UI paradigms: classic **virtual chest inventory menus (GUI)** spanning 1 to 6 rows and modern **client-side native modal dialogues**, without requiring heavy custom client mods or complex external dependencies.

***

## Core Features

* **Dual Interface Paradigms:** Manage traditional virtual chest containers and modern full-screen modal dialogue forms (interactive text fields, numerical sliders, dropdown selectors, and checkboxes).
* **The 5 Real Animations:** Modular, per-property animation runners (`material.animate`, `name.animate`, `lore.animate`, `custom-model-data.animate`, `item-model.animate`) operating on tick intervals without full inventory redraws or item flickering.
* **Canonical Action Engine:** Fast execution of server console and player commands, sound playback, private and broadcast messaging, native web links (`[url]`), clipboard copying (`[copy]`), interaction throttling (`[cooldown]`), and conditional requirement branching (`require:`). **All action tags are strictly lowercase.**
* **Next-Gen ItemBuilder:** Native support for Armor Trims, HEX leather armor dyes, strictly evaluated potion durations via `TimeParser` (or `-1` for infinite duration), player heads (`SELF`, usernames, PAPI placeholders, direct texture URLs, Base64), and modern stack sizing from 1 to 99 items.
* **In-Game Generator & Static Validator:** Design layouts in-game with `/menus generate <1-6>` and automatically validate the integrity of all configuration YAML files during startup or hot-reload to catch syntax errors before players encounter them.

***

## Command & Permission Reference

### Main Administrative Command: `/hythiummenus`

Aliases: `/hm`, `/hmenus`

Base permission: `hythiummenus.commands.main`

| Command / Subcommand         | Required Permission                  | Description                                                                                                                                                               |
| ---------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/hythiummenus help`         | `hythiummenus.commands.main`         | Displays the interactive administrative help menu with all available subcommands.                                                                                         |
| `/hythiummenus info`         | `hythiummenus.commands.main`         | Displays technical server metrics (version, platform, authors, update status, and loaded menu/dialogue counts).                                                           |
| `/hythiummenus reload`       | `hythiummenus.commands.reload`       | Hot-reloads all configuration files (`config.yml`, `messages.yml`), runs the static validator, and synchronizes dynamic commands in Bukkit without restarting the server. |
| `/hythiummenus checkupdates` | `hythiummenus.commands.checkupdates` | Asynchronously checks Modrinth for newer plugin releases.                                                                                                                 |

### Menu Manager: `/menus`

No aliases.

Base permission: `hythiummenus.commands.menu`

| Command / Subcommand          | Required Permission                   | Description                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/menus help`                 | `hythiummenus.commands.menu`          | Displays the help guide for inventory GUI menus.                                                                                                                                                                  |
| `/menus open <menu> [player]` | `hythiummenus.commands.menu.open`     | Opens a menu from `menus/*.yml` for yourself or for the specified player at the end. Works in-game and from the server console (target player is mandatory from console). Supports subfolders and tab-completion. |
| `/menus generate <rows>`      | `hythiummenus.commands.menu.generate` | Opens a temporary virtual container (1 to 6 rows) to visually arrange items and automatically export a clean YAML configuration using `default_empty_slots`.                                                      |

### Dialogue Manager: `/dialogue`

Alias: `/dialog`

Base permission: `hythiummenus.commands.dialogue`

| Command / Subcommand                 | Required Permission                   | Description                                                                                                                                                       |
| ------------------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/dialogue help`                     | `hythiummenus.commands.dialogue`      | Displays the help guide for native modal dialogues.                                                                                                               |
| `/dialogue open <file.yml> [player]` | `hythiummenus.commands.dialogue.open` | Opens a native Paper modal dialogue from `dialogues/*.yml` for yourself or for the specified player at the end (mandatory from console). Supports tab-completion. |

## Administrative Permissions & Dynamic Commands

* **Global Admin Permission:** `hythiummenus.admin` grants unrestricted access to all plugin commands and bypasses permission checks (assigned to server operators by default).
* **Dynamic Commands:** Configured per menu or dialogue via `settings.command: "shop"` or an alias list `settings.commands: ["menu", "main"]`. Injected directly into Bukkit's `CommandMap` at runtime. Dynamic commands inherit the optional `settings.permission` node and custom denial notice `settings.permission-message`, and update on `/hm reload` without server reboots.