**Author:** RajaAditya **Website:** [rajaaditya.my.id](https://rajaaditya.my.id) **Version:** 1.0.3 **API:** Paper 1.21.x **Based on:** [DeluxeMenus](https://github.com/HelpChat/DeluxeMenus) (fork, heavily modified) --- ## About This Fork RA-ExcellentMenus started as a **fork of DeluxeMenus** — the config format (`menu_title`, `open_command`, `click_requirement`, action prefixes like `[message]` / `[console]`, etc.) is intentionally kept close to it, so anyone who has built DeluxeMenus menus before can pick this up almost immediately. From there, the plugin was rewritten and re-scoped by the author around three goals DeluxeMenus doesn't cover out of the box: 1. **Native Bedrock support** — every menu can render as a Cumulus Form for Floodgate/Bedrock players from the exact same YAML, with an optional per-item `bedrock:` override block. DeluxeMenus is Java-only. 2. **A much smaller surface area** — only the requirement types, actions, and options actually needed for this use case were kept or reimplemented, instead of DeluxeMenus' full feature set (pagination, NBT items, third-party item-plugin materials, meta/exp requirements, etc.). 3. **A license-gated distribution model** — since this is a closed-source, commercially distributed plugin rather than a free open-source project, it includes its own license verification system, which DeluxeMenus (free and open source) has no equivalent for. Because of this, **RA-ExcellentMenus is not a drop-in replacement** for DeluxeMenus — menus are similar in spirit and syntax, but not 100% config-compatible. See the [comparison table](#comparison-with-deluxemenus) below for specifics. --- ## What's New in 1.0.3 - **Cooldown feedback is no longer hardcoded.** The old `cooldown_message` field has been removed. Cooldowns now use the same `deny_commands` action-list system as every other requirement block — put `[message]`, `[sound]`, `[console]`, or any other action there, and it runs whenever a player clicks an item that's still on cooldown. The `{cooldown}` placeholder (remaining seconds) is still available inside those commands. - **Custom head textures via `basehead-`.** Item `material:` now supports a DeluxeMenus-style custom skull texture syntax — set `material: basehead-` (the raw base64 `textures` property from a Mojang session server, same value tools like Minecraft-Heads or DeluxeMenus use) to display a fully custom head icon, instead of being limited to vanilla `Material` names. ## What's New in 1.0.2 - **Fully customizable plugin messages** via a new `messages.yml` — every message the plugin sends (errors, command feedback, etc.) can now be edited without recompiling. See [Messages](#messages-messagesyml) below. - **Three new actions**: `[takemoney]`, `[commandevent]`, `[broadcastsound]` — plus a `[openguimenu]` alias for DeluxeMenus config compatibility. See the [Actions](#actions) table. - **Enchantment support** on menu items via the `enchantments:` field. - **Drag protection** — dragging/splitting a stack into a menu slot is now cancelled, preventing item loss or duplication. - **Live cooldown/price info on Bedrock forms** — buttons now show remaining cooldown and balance status directly in the form text, not just via chat. --- ## Features ### Cross-Platform Menus - Define a menu once in YAML — it renders as a **chest GUI** for Java Edition players and as a **Cumulus Form** for Bedrock players (via Floodgate) - Bedrock detection is automatic (`FloodgateApi#isFloodgatePlayer`) - Per-item `bedrock:` override block lets you customize icon, display name, priority, and visibility specifically for Bedrock clients - Bedrock form buttons automatically append a live cooldown/balance line (`⏳ Cooldown: Ns` / `💰 Harga: X (✅ Cukup / ❌ Kurang)`) for items that have `cooldown` or `price` set ### DeluxeMenus-Style Configuration - One `.yml` file = one menu, placed inside the `menus/` folder — add or remove freely, no restart needed - `menu_title`, `size`, `inventory_type`, `open_command`, `permission`, `items` — familiar structure for anyone coming from DeluxeMenus - `open_command` entries are automatically captured as commands (chat-intercepted) — no need to register them one-by-one - Optional `register_command: true` registers the command **officially** into the server's command map (via reflection into Bukkit's internal `CommandMap`), so it shows up in tab-completion, `/help`, and other plugins' command lists ### Rich Requirement System - Per-item requirements for **opening a menu**, **viewing an item**, and **clicking an item** — with separate blocks for left click, right click, shift-click (both), and middle click - 12 requirement types out of the box: `javascript`, `has_permission`, `has_permissions` (multiple), `has_item`, `has_money`, comparison operators (`>`, `>=`, `<`, `<=`, `==`, `!=`), `string contains`, `string equals`, `string equals ignorecase`, `regex matches`, `is near`, `is object` - Each requirement block supports `deny_commands` (run on failure) and `success_commands` (run on success) - Architecture is designed to be extended — new requirement types only need a new class implementing `Requirement` ### Actions - Command-style action prefixes usable in `click_commands`, `deny_commands` (including an item's cooldown `deny_commands`), and `success_commands` - Supported prefixes: `[message]`, `[console]`, `[player]`, `[close]`, `[sound]`, `[open_menu]` / `[open]` / `[openguimenu]`, `[broadcast]`, `[connect]`, `[update]` / `[refresh]`, `[json]`, `[takemoney]`, `[commandevent]`, `[broadcastsound]` - A line with no recognized prefix is run as a console command by default ### Items - `material:` accepts any vanilla Bukkit `Material` name, **or** `basehead-` for a custom skull texture (see [Custom Head Textures](#custom-head-textures-basehead-) below) - `enchantments:` lets you add enchantments to an item, written as `"NAME;LEVEL"` (e.g. `"SHARPNESS;5"`); unknown enchantment names are skipped with a console warning instead of failing the whole menu - Clicking, dragging, or shift-clicking to move an item into a menu slot is blocked — menus can't be used to accidentally store or duplicate items #### Custom Head Textures (`basehead-`) Instead of picking from vanilla materials, an item can use a fully custom player-head texture — the same trick DeluxeMenus and head-database style plugins use: ```yaml items: spawn-hub: material: 'basehead-eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvODY4NDkzZDg4OTlmZGMxZDllOTFiMDkyZjAwNWJlNmFiZmIwYjhlMjA0ZTkzN2Q2NWM4MTUxY2ZlYjhiYTBlOCJ9fX0=' slot: 10 display_name: '&cSpawn' ``` - Everything after `basehead-` must be the raw base64 `textures` property value from a Mojang session server (the same format sites like Minecraft-Heads.com or DeluxeMenus head packs use) — paste it as-is, no need to decode it yourself. - If the value is missing or malformed, the plugin falls back to a plain `PLAYER_HEAD` and logs a warning instead of failing the whole menu. - Unrelated to Bedrock rendering — Bedrock Cumulus Forms use the `bedrock.icon` field instead (see the `bedrock:` override block). ### Economy & Cooldown - `price:` on an item charges the player via Vault economy before running its click commands (soft-depend — if Vault isn't installed, items are treated as free) - `cooldown:` (in seconds) blocks repeat clicks per player per item; when a player clicks while still on cooldown, the item's `deny_commands` runs instead of `click_commands` — put a `[message]` there with the `{cooldown}` placeholder (remaining seconds) if you want to tell the player about it, or use `[sound]`/`[console]`/anything else - Neither `price` nor `cooldown` can be bypassed, even by operators - `[takemoney]` action lets you additionally withdraw money as part of any command list (separate from the `price:` field, e.g. inside `deny_commands`/`success_commands`, or to charge a variable amount resolved from a placeholder) ### Placeholders - Integrates with **PlaceholderAPI** when present - Built-in fallback placeholders even without PlaceholderAPI: `%player_name%`, `%player_displayname%`, `%player_uuid%`, and basic Vault balance placeholders (`%vault_eco_balance_fixed%`, `%vault_eco_balance%`, `%vault_eco_balance_formatted%`, `%vault_eco_balance_commas%`) ### Messages (`messages.yml`) - Every player/console-facing message (errors, command feedback, "menu not found", etc.) is defined in `plugins/RA-ExcellentMenus/messages.yml` — no code changes or recompiling needed to reword anything - Supports `&` color codes and per-message placeholders (e.g. `{menu}`, `{player}`) - Reloads automatically with `/excellentmenus reload` - If a plugin update introduces new message keys that don't exist yet in your `messages.yml`, they're merged in automatically from the bundled defaults — existing customizations are preserved ### License-Gated Activation - Plugin verifies a license key against `plugins.rajaaditya.my.id` on startup and on a configurable heartbeat interval - Communication is **outbound-only** (plugin → web); the web service never connects back to your server - If the key is invalid or unconfigured, all menus are disabled until it's fixed — no "expired" state, just valid/invalid - Short network outages don't immediately disable menus: a grace period keeps the last known-valid state active ### Fully Configurable - All menus, items, requirements, and actions are configured through YAML — no code required - `/excellentmenus reload` (alias `/em reload`) reloads config, messages, and every menu without restarting the server --- ## Dependencies | Plugin | Required | Purpose | |--------|----------|---------| | [Floodgate](https://github.com/GeyserMC/Floodgate) | **Yes** (`depend`) | Sends Cumulus forms to Bedrock clients | | [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) | Optional (`softdepend`) | Placeholder resolution in requirements, actions, and item text | | [Vault](https://github.com/MilkBowl/VaultAPI) | Optional (`softdepend`) | Powers `price`, `has_money` requirement, `[takemoney]` action, and Vault balance placeholders | > Nashorn (standalone, version 15.4) is bundled directly into the plugin jar for evaluating `type: javascript` expressions — no separate install needed. --- ## Installation 1. Make sure **Floodgate** is installed and running (required) 2. Optionally install **PlaceholderAPI** and/or **Vault** for the extra features they unlock 3. Place `RA-ExcellentMenus-1.0.3.jar` into your `plugins/` folder 4. Start the server once to generate the default config, `messages.yml`, and example menus 5. Open `plugins/RA-ExcellentMenus/config.yml` and set a valid `license.key` (get one at [plugins.rajaaditya.my.id](https://plugins.rajaaditya.my.id)) — **menus stay disabled until this is done** 6. Restart the server (or wait for the next license heartbeat) to activate menus 7. Edit or add files inside `plugins/RA-ExcellentMenus/menus/` to build your own menus — subfolders of any depth are supported and auto-discovered 8. Use `/excellentmenus reload` to apply menu, config, and message changes without restarting --- ## File Structure ``` plugins/RA-ExcellentMenus/ ├── config.yml # License key + general settings ├── messages.yml # All plugin messages, fully editable ├── menus/ # One .yml file = one menu (subfolders supported) │ ├── example.yml # Minimal example menu │ ├── example-actions.yml │ ├── example-requirement.yml │ ├── example-requirement-types.yml │ ├── example-bedrock.yml │ ├── example-register-command.yml │ ├── example-view-requirement.yml │ ├── example-open-requirement.yml │ ├── example-item-flags.yml │ ├── example-inventory-type.yml │ ├── example-has-item.yml │ ├── example-cooldown.yml │ └── example-price.yml └── data/ # DO NOT edit manually ├── server-id.dat # Unique fingerprint used for license binding └── license-cache.json # Last known license verification result ``` --- ## Configuration ### config.yml ```yaml license: key: "XXXX-XXXX-XXXX-XXXX" # Friendly name for this server, shown in the "My Licenses" dashboard # at https://plugins.rajaaditya.my.id server-nickname: "My Server" # How often (in minutes) the plugin re-verifies the license check-interval-minutes: 360 settings: # Folder (relative to the plugin's data folder) where menu .yml files live menus-folder: "menus" # If true, menu parsing errors are logged in detail to console debug: false # DO NOT edit manually — managed automatically by the plugin internal: server-id: "" last-verified-valid: false last-verified-at: 0 ``` **Important:** if `license.key` is left as the placeholder `XXXX-XXXX-XXXX-XXXX` (or empty), the `menus/` folder is not loaded at all and every menu is disabled. ### messages.yml ```yaml general: no-permission: "&cKamu tidak memiliki izin!" menu-not-found: "&cMenu tidak ditemukan: {menu}" menu-unavailable-license: "&cMenu sedang tidak tersedia (license server bermasalah). Hubungi admin server." menu-no-permission: "&cKamu tidak memiliki izin untuk membuka menu ini." player-not-found: "&cPlayer tidak ditemukan: {player}" console-must-specify-player: "&cKamu harus specify player atau jalankan dari console!" in-game-only: "&cCommand ini cuma bisa dipakai in-game." command: header-version: "&e RA-ExcellentMenus &7v{version}" header-usage: "&7Gunakan /{label} reload | open | list | execute" reload-success: "&a[ExcellentMenus] Config & semua menu berhasil di-reload." open-usage: "&cUsage: /{label} open [player]" open-success: "&aMenu '{menu}' dibuka untuk {player}" list-empty: "&eTidak ada menu yang terdaftar." list-header: "&6=== Daftar Menu ({count}) ===" list-entry: "&e{index}. &f{menu}&7 -> /{commands}" execute-usage: "&cUsage: /{label} execute " execute-running: "&aMenjalankan action untuk {player}: {action}" unknown-subcommand: "&cSub-command tidak dikenal." unknown-subcommand-hint: "&7Gunakan: reload, open, list, execute" ``` Every message supports `&` color codes. Placeholders available per message are noted in the comments right above each line in the actual file, and unused ones can be removed freely. --- ## Menu File Structure Each file inside `menus/` defines exactly one menu. The **file name (without `.yml`)** becomes the menu's internal key, used by `/excellentmenus open ` and the `[open_menu]` action. If the file lives in a subfolder (e.g. `menus/shop/vip.yml`), the key includes the relative path (`shop/vip`). ```yaml menu_title: '&8My Menu' # Inventory title, supports & color codes and hex (&#RRGGBB) size: 27 # Chest inventory size (multiple of 9), ignored if inventory_type is set inventory_type: CHEST # Optional — any Bukkit InventoryType (e.g. CHEST, DROPPER, HOPPER) open_command: # One or more commands that open this menu - mymenu - mm register_command: false # true = register officially to the server's command map permission: "my.menu.use" # Optional — permission required to open this menu (not bypassable by OP) open_requirement: # Optional — checked BEFORE the menu opens requirements: money_check: type: javascript expression: '%vault_eco_balance_fixed% >= 500' deny_commands: - '[message] &cYou need at least 500 to open this!' success_commands: # Optional, runs when the requirement passes - '[sound] ENTITY_PLAYER_LEVELUP' items: my_item: # Item key (any unique string per menu) material: DIAMOND # Vanilla Material name, or basehead- for a custom head slot: 13 # Single slot... slots: [0, 1, 2] # ...or multiple slots (list or "start-end" range strings) amount: 1 display_name: '&b&lMy Item' lore: - '&7Line one' - '&7Player: %player_name%' item_flags: - HIDE_ENCHANTS enchantments: # "NAME;LEVEL" strings — unknown names are skipped with a warning - "SHARPNESS;5" - "UNBREAKING;3" cooldown: 5 # Seconds between clicks per player deny_commands: # Runs instead of click_commands while on cooldown - '[message] &cWait {cooldown} more seconds!' price: 100 # Vault cost charged before click_commands run click_requirement: { } # Generic requirement, used as fallback for any click type left_click_requirement: { } shift_left_click_requirement: { } right_click_requirement: { } shift_right_click_requirement: { } middle_click_requirement: { } view_requirement: { } # Item is hidden entirely if this fails (checked silently) click_commands: [] # Generic actions, used as fallback for any click type left_click_commands: [] shift_left_click_commands: [] right_click_commands: [] shift_right_click_commands: [] middle_click_commands: [] bedrock: # Optional — Bedrock-only appearance override enable: true priority: 1 icon: 'textures/items/diamond' # See "Finding Bedrock Icon Paths" below for how to get this value display_name: - '&bLine 1 (max 2 lines)' - '&eLine 2' ``` **Requirement vs. view vs. open, at a glance:** | Block | Checked when | Bypassable by OP | Has deny/success commands | |---|---|---|---| | `open_requirement` | Before the menu opens | No | Yes | | `view_requirement` | Silently, before an item is rendered | No | No (item is just hidden) | | `click_requirement` / `*_click_requirement` | When the matching click type happens | No | Yes | | `cooldown` (via item-level `deny_commands`) | When clicking an item still on cooldown | No | Yes (`deny_commands` only, no separate success list — a normal click just runs `click_commands`) | **Item safety:** regardless of what's configured, players can never drag, shift-click, or otherwise place an item *into* a menu slot — this is blocked automatically to prevent items from being lost or duplicated when the menu closes. --- ## Menu File Fields: DeluxeMenus vs RA-ExcellentMenus Both plugins use a very similar top-level shape (`menu_title`, `open_command`, `items`, per-item `material`/`slot`/`display_name`/`lore`), but several field names and behaviors diverge. If you're porting a menu from DeluxeMenus, check this table field by field: | Section | Field | DeluxeMenus | RA-ExcellentMenus | |---|---|---|---| | **Registration** | Where a menu is declared | `config.yml` → `gui_menus: : file: .yml` | Just drop the `.yml` file into `menus/` (subfolders supported) — auto-discovered, no `config.yml` entry needed | | **Registration** | Menu key | The name you give it under `gui_menus:` | The file's path relative to `menus/`, without `.yml` | | **Top-level** | `menu_title` | ✅ Same | ✅ Same | | **Top-level** | `size` | ✅ Same (defaults to 54) | ✅ Same (defaults to 27) | | **Top-level** | `open_command` | ✅ Same, plus supports `/cmd ` argument placeholders | ✅ Same, no argument placeholder support | | **Top-level** | `inventory_type` | Limited/indirect support | ✅ Direct `inventory_type:` field, any Bukkit `InventoryType` | | **Top-level** | `register_command` | Not applicable — DeluxeMenus registers its own commands internally | ✅ Explicit `register_command: true` registers into the server's real `CommandMap` | | **Top-level** | `permission` (whole-menu gate) | Done via `open_requirement` + `has permission` type | ✅ Dedicated `permission:` field, separate from `open_requirement` | | **Top-level** | `open_requirement` | ✅ Same concept, plus `minimum_requirements` / `stop_at_success` | ✅ Same concept, always requires **all** requirements to pass | | **Item** | `material` | Supports vanilla + custom-item-plugin syntax (`mmoitems-...`, `nexo-...`, etc.) | Vanilla Bukkit `Material`, **plus** `basehead-` for custom skull textures | | **Item** | `slot` / multiple slots | `slot:` (single) | `slot:` (single) **or** `slots:` (list / `"0-8"` range strings) | | **Item** | `enchantments` | ✅ Supported | ✅ Supported (`"NAME;LEVEL"` string format) | | **Item** | `data`, `model_data`, NBT | ✅ Supported | ❌ Not supported | | **Item** | `price` | Not built-in (use `[takemoney]` action) | ✅ Built-in `price:` field | | **Item** | `cooldown` | Not built-in | ✅ Built-in `cooldown:` field; feedback handled via the item's `deny_commands` (any action, `{cooldown}` placeholder available) | | **Item** | `click_requirement` / `left_`/`right_`/`shift_left_`/`shift_right_`/`middle_click_requirement` | ✅ Same names | ✅ Same names | | **Item** | `view_requirement` | ✅ Same | ✅ Same | | **Item** | Requirement `minimum_requirements` / `stop_at_success` | ✅ Supported per block | ❌ Not supported — every requirement in the block must pass | | **Item** | Requirement inversion (`!type`) | ✅ e.g. `type: "!has permission"` | ❌ Not supported | | **Item** | `bedrock:` override block | Not applicable — no Bedrock renderer | ✅ RA-ExcellentMenus-only: `enable`, `priority`, `icon`, `display_name` | | **Item** | `next_page` / `previous_page` items | ✅ Supported | ❌ Not supported | | **Item** | `update_interval` (live-refreshing lore) | ✅ Supported | ❌ Not supported (use `[update]`/`[refresh]` action manually) | | **Item** | Drag/shift-click into menu slot | Depends on config | ✅ Always blocked automatically | --- ## Requirement Types | `type` | Fields Used | Description | |--------|-------------|-------------| | `javascript` | `expression` | Evaluates a JS expression (Nashorn) after resolving placeholders. Truthy result = pass. | | `has_permission` | `permission` | Single permission node check via Bukkit's permission API. | | `has permissions` | `permission` (comma-separated) | Checks multiple permissions at once; prefix a permission with `-` to require the player **not** have it. | | `has_item` | `material`, `amount`, `name`, `lore` | Checks inventory for a material (optionally matching display name/lore) and quantity. | | `has_money` | `amount` | Checks Vault balance ≥ amount. Requires Vault. | | `>`, `>=`, `<`, `<=`, `==`, `!=` | `expression`, or `input` + `output` | Numeric comparison after placeholder resolution. | | `string contains` | `input`, `value` | Substring check. | | `string equals` | `input`, `value` | Exact string match. | | `string equals ignorecase` | `input`, `value` | Case-insensitive string match. | | `regex matches` | `input`, `regex` | Full-match regex check. | | `is near` | `x`, `y`, `z`, `distance` | Checks if the player is within `distance` blocks of a coordinate (same world). | | `is object` | `input`, `object` | Validates that input resolves to a `player`, `uuid`, `int`, or `double`. | > Unknown or unregistered requirement `type` values log a warning and are skipped. --- ## Requirement System — Full Example This is a single menu file that combines all three requirement scopes (`open_requirement`, `view_requirement`, `click_requirement`) and several requirement types together, so you can see how they interact in practice. ```yaml menu_title: '&8VIP Shop' size: 27 open_command: - vipshop register_command: false # ── 1) OPEN REQUIREMENT ────────────────────────────────────────────── # Checked once, before the menu is even allowed to open. # If it fails, the player never sees the inventory at all. open_requirement: requirements: must_be_online_long_enough: type: javascript expression: '%statistic_time_played% >= 100' deny_commands: - '[sound] BLOCK_ANVIL_PLACE' - '[message] &cYou need more playtime before opening the VIP Shop.' success_commands: - '[sound] BLOCK_CHEST_OPEN' items: # ── 2) VIEW REQUIREMENT ──────────────────────────────────────────── # Checked silently while the menu is being built. If it fails, the # item is simply left out of the inventory — no deny message, since # the player never even knows the slot exists. vip_only_item: material: NETHER_STAR slot: 4 display_name: '&d&lVIP Exclusive Kit' lore: - '&7Only visible to VIP members.' view_requirement: requirements: vip_check: type: has_permission permission: 'vip.rank' click_commands: - '[message] &dEnjoy your VIP kit!' - '[close]' # ── 3) CLICK REQUIREMENT (combined: money + item) ────────────────── # Both requirements must pass for click_commands to run. # If either fails, deny_commands runs instead and click_commands # is skipped entirely. buy_rank_upgrade: material: DIAMOND_BLOCK slot: 11 display_name: '&b&lUpgrade Rank &7[500 coins + 1 Nether Star]' lore: - '&7Requires:' - '&7- &f500 coins' - '&7- &f1 Nether Star' click_requirement: requirements: enough_money: type: has_money amount: 500 has_nether_star: type: has_item material: NETHER_STAR amount: 1 deny_commands: - '[sound] BLOCK_ANVIL_PLACE' - '[message] &cYou need 500 coins and a Nether Star for this upgrade.' success_commands: - '[sound] ENTITY_PLAYER_LEVELUP' click_commands: - '[takemoney] 500' - '[console] clear %player_name% nether_star 1' - '[console] lp user %player_name% parent add vip-plus' - '[message] &aRank upgraded to VIP+!' - '[close]' # ── 4) DIFFERENT REQUIREMENTS PER CLICK TYPE ─────────────────────── # Left click sells 1, right click sells a full stack — each with its # own requirement, so the check matches the amount actually needed. sell_wheat: material: WHEAT slot: 15 display_name: '&e&lSell Wheat' lore: - '&7Left-click: sell 1' - '&7Right-click: sell a full stack (64)' left_click_requirement: requirements: has_one: type: has_item material: WHEAT amount: 1 deny_commands: - '[message] &cYou have no wheat to sell.' left_click_commands: - '[console] clear %player_name% wheat 1' - '[console] eco give %player_name% 2' - '[message] &aSold 1 wheat for 2 coins.' right_click_requirement: requirements: has_stack: type: has_item material: WHEAT amount: 64 deny_commands: - '[message] &cYou need a full stack (64) of wheat to use this.' right_click_commands: - '[console] clear %player_name% wheat 64' - '[console] eco give %player_name% 128' - '[message] &aSold 64 wheat for 128 coins.' # ── 5) NAME/LOCATION-BASED REQUIREMENT ───────────────────────────── spawn_only_deal: material: EMERALD slot: 20 display_name: '&a&lSpawn-Only Deal' lore: - '&7Only works while standing near spawn.' click_requirement: requirements: near_spawn: type: 'is near' x: 0 y: 64 z: 0 distance: 15 deny_commands: - '[message] &cYou must be near spawn to use this deal.' click_commands: - '[message] &aDeal claimed!' - '[close]' ``` **What this example shows:** - `open_requirement` gates the *whole menu* — fails loudly with a deny message. - `view_requirement` gates *visibility* — fails silently, the item just isn't there. - `click_requirement` with **multiple entries** (`enough_money` + `has_nether_star`) requires **all** of them to pass (no `minimum_requirements` option in this plugin — see the [comparison table](#menu-file-fields-deluxemenus-vs-ra-excellentmenus) above). - `left_click_requirement` / `right_click_requirement` let the **same item** enforce different rules per click type, each with its own `click_commands` counterpart. - Requirement types can be freely mixed within one block (`has_money` + `has_item` above). - `buy_rank_upgrade` uses `[takemoney]` to actually withdraw the coins as part of the action list (the `has_money` requirement only checked the balance beforehand). --- ## Actions Used in `click_commands` (and variants), `deny_commands` (including an item's cooldown `deny_commands`), and `success_commands`. | Prefix | Example | Behavior | |--------|---------|----------| | `[message]` | `[message] &aHello %player_name%!` | Sends a chat message to the player. | | `[console]` | `[console] give %player_name% diamond 1` | Runs the command as console. **Default** if no prefix is present. | | `[player]` | `[player] spawn` | Runs the command as the player. | | `[commandevent]` | `[commandevent] spawn` | Runs the command as the player, but via a real `PlayerCommandPreprocessEvent` first — other plugins listening for player commands (anti-cheat, loggers, command blockers) get a chance to see or cancel it, unlike `[player]`. | | `[close]` | `[close]` | Closes the player's currently open inventory. | | `[sound]` | `[sound] ENTITY_PLAYER_LEVELUP 1 1` | Plays a sound to the player only (`SOUND_NAME [volume] [pitch]`). | | `[broadcastsound]` | `[broadcastsound] ENTITY_PLAYER_LEVELUP 1 1` | Plays the same sound to **every online player**, not just the one who clicked. | | `[open_menu]` / `[open]` / `[openguimenu]` | `[open_menu] shop` | Opens another menu by its file key. All three prefixes are equivalent; `[openguimenu]` exists for DeluxeMenus config compatibility. | | `[broadcast]` | `[broadcast] &6%player_name% did something!` | Sends a message to every online player. | | `[connect]` | `[connect] lobby` | Sends the player to another server via BungeeCord/Velocity plugin messaging. | | `[update]` / `[refresh]` | `[update]` | Re-opens (refreshes) the menu currently open for the player. | | `[json]` | `[json] &aClick info` | Sends a chat component message (currently renders as plain colored text). | | `[takemoney]` | `[takemoney] 100` | Withdraws the given amount from the player's Vault balance. Unlike the `has_money` requirement (which only checks the balance), this actually deducts it — no-ops with a warning if Vault isn't installed. | --- ## Commands | Command | Description | Usage | |---------|-------------|-------| | `/excellentmenus` (`/em`) | Shows plugin version and usage help | Player / Console | | `/excellentmenus reload` | Reloads `config.yml`, `messages.yml`, and every menu file | Player / Console | | `/excellentmenus open [player]` | Opens a menu for yourself or a target player | Player / Console | | `/excellentmenus list` | Lists all currently loaded menus and their open commands | Player / Console | | `/excellentmenus execute ` | Manually runs an action string against a target player | Player / Console | > Any `open_command` defined in a menu file also opens that menu directly, e.g. `/mymenu`. --- ## Permissions | Permission | Default | Description | |------------|---------|-------------| | `excellentmenus.admin` | `op` | Use `/excellentmenus reload`, `open`, `list`, and `execute` | Individual menus can additionally require their own permission via the `permission:` key in the menu file — this is checked when the menu is opened and is **not bypassable by operators**. --- ## Data Files Data is stored under `plugins/RA-ExcellentMenus/data/`. **Do not edit these files manually.** ### server-id.dat A randomly generated UUID created once on first run, used to bind your license to this specific server installation (used for `max_activations` / "My Licenses" on the dashboard). ### license-cache.json ```json {"valid": true, "checked_at": 1735689600000} ``` Cached result of the last successful license check, used as a fallback during short network outages (grace period) so menus don't drop offline for a temporary connectivity blip. --- ## License Verification Flow 1. On `onEnable` (and every `check-interval-minutes`), the plugin sends `{key, server_id, server_nickname}` to `plugins.rajaaditya.my.id/api/license/verify`. 2. If the response says `valid: true`, menus load normally. 3. If `valid: false`, every menu is cleared and all dynamically registered commands are unregistered until the license is fixed. 4. If the request fails outright (network issue) but the plugin previously verified successfully, it keeps menus active using the cached result (grace period) rather than shutting them down immediately. 5. If the key was never configured (still the placeholder or blank), the plugin never calls the API — menus stay disabled until a real key is entered. --- ## Comparison with DeluxeMenus | Aspect | DeluxeMenus | RA-ExcellentMenus | |---|---|---| | **License model** | Free & open source (GitHub) | Closed source, license-key gated | | **Bedrock support** | ❌ Java Edition only | ✅ Native, via Floodgate + Cumulus Forms from the same config, including live cooldown/balance info on buttons | | **Menu registration** | Menus listed explicitly in `config.yml` under `gui_menus:` (`name: file: xxx.yml`) | Menus are auto-discovered — every `.yml` file dropped into `menus/` (including subfolders) is loaded automatically | | **Open command args** | Supports `/menu ` argument parsing in open commands | Not implemented | | **register_command equivalent** | Commands are always registered via `open_command` (own command system) | Explicit opt-in via `register_command: true`, using reflection to register into Bukkit's real `CommandMap` (so it shows up in `/help`, tab-complete of other plugins, etc.) | | **Requirement types** | ~16+ types: `has permission`, `has permissions`, `has money`, `has item`, `has meta`, `has exp`, `is near`, `javascript`, `string equals`, `string equals ignorecase`, `string contains`, `string length`, `is object`, comparators (`>`, `>=`, `<`, `<=`, `==`, `!=`), plus inversion via `!type` prefix | 12 types: `javascript`, `has_permission`, `has permissions`, `has_item`, `has_money`, comparators, `string contains/equals/equals ignorecase`, `regex matches`, `is near`, `is object`. No requirement inversion (`!type`) support | | **Requirement inversion (`!type`)** | ✅ Supported on every requirement type | ❌ Not supported | | **`minimum_requirements` / `stop_at_success`** | ✅ Supported — pass if only N of several requirements are met | ❌ Not implemented — all requirements in a block must pass | | **Regex requirement** | Not a dedicated type (achievable via other means) | ✅ Dedicated `regex matches` type | | **Actions** | `[player]`, `[console]`, `[commandevent]`, `[message]`, `[openguimenu]`, `[connect]`, `[json]`, `[refresh]`, `[broadcastsound]`, `[sound]`, `[takemoney]`, `[close]`, and more | `[message]`, `[console]`, `[player]`, `[commandevent]`, `[close]`, `[sound]`, `[broadcastsound]`, `[open_menu]`/`[open]`/`[openguimenu]`, `[broadcast]`, `[connect]`, `[update]`/`[refresh]`, `[json]`, `[takemoney]` — full parity on this list as of v1.0.2 | | **Pricing an item** | No built-in `price:` field — done via `[takemoney]` action + `has money` requirement | ✅ Built-in `price:` field on an item (auto-checks balance and withdraws before running click commands), **plus** the same `[takemoney]` action for manual/variable charges | | **Cooldowns** | Not a built-in per-item option (needs external plugin/placeholder tricks) | ✅ Built-in `cooldown:` per item, with feedback via `deny_commands` (any action, `{cooldown}` placeholder available) instead of a fixed message | | **Custom head textures** | Only via third-party item plugins (`mmoitems-...`, `nexo-...`, etc.) | ✅ Built-in `basehead-` material syntax — no extra plugin required | | **Pagination (next/previous page)** | ✅ Supported | ❌ Not implemented | | **Custom item plugin materials** (MMOItems, Nexo, ExecutableItems, etc.) | ✅ Supported | ❌ Only vanilla Bukkit `Material` (plus built-in `basehead-` custom skulls) | | **Enchantments** | ✅ Supported | ✅ Supported (`"NAME;LEVEL"` string format) | | **NBT / CustomModelData on items** | ✅ Supported | ❌ Not implemented | | **Live placeholder refresh (`update_interval`)** | ✅ Supported — lore/name can refresh while the menu stays open | ❌ Placeholders resolve once, when the menu opens (manual `[update]`/`[refresh]` action needed to re-render) | | **Inventory types other than chest** | Chest-focused, limited alternates | ✅ Any Bukkit `InventoryType` via `inventory_type:` (e.g. `DROPPER`, `HOPPER`) | | **Drag/shift-click protection** | Depends on config | ✅ Always blocked automatically — no way to drag/duplicate items into a menu slot | | **Vault dependency** | Required for money-related features | Optional (soft-depend) — `price`/`has_money`/`[takemoney]` silently no-op as "free"/pass if Vault is absent | | **PlaceholderAPI dependency** | Required for placeholders | Optional (soft-depend) — falls back to built-in `%player_name%`/`%player_uuid%`/basic Vault placeholders if absent | | **JS expression engine** | Built-in expression evaluator | Standalone Nashorn (shaded into the jar), same expression style | | **Message customization** | Editable via its own messages config | ✅ Editable via `messages.yml`, auto-merges new keys on update | | **Admin commands** | `/dm reload`, `/dm open`, `/dm list` (paginated), `/dm dump ` | `/excellentmenus reload`, `open`, `list`, `execute` (no `dump`) | **Summary:** if you need DeluxeMenus' full breadth — pagination, custom-item-plugin support, NBT, live-refreshing placeholders, requirement inversion — stick with DeluxeMenus. RA-ExcellentMenus trades that breadth for **out-of-the-box Bedrock parity**, **built-in pricing/cooldowns**, custom head textures without extra plugins, a fully customizable message system, and a smaller, easier-to-audit config surface, at the cost of being closed-source and license-gated. --- ## License Developed by **RajaAditya** — [rajaaditya.my.id](https://rajaaditya.my.id) This plugin is **closed source**. Redistribution without permission is prohibited.