Upgrading Guide

This guide describes how to upgrade to EasyMenu 7 and covers migration details from prior versions.

---

Migrating from EasyMenu 6 to EasyMenu 7

The Short Version

• Your existing YAML files (config.yml, main.yml, sub/*.yml, lang/*.yml) do not need to change.
• NegiLib 1.x is now required.

Upgrade Steps

1. Stop the server.
2. Put both NegiLib-1.1.1.jar and EasyMenu-7.0.2.jar into your plugins/ directory.
3. Remove the old EasyMenu-6.x.x.jar.
4. Start the server.
5. Verify that a log line like the following appears in your console (the wording before NegiLib depends on language):

[EasyMenu] EasyMenu has been enabled. NegiLib 1.1.1 (API 1.0), capabilities=N

The number after capabilities= varies by server environment.

Requirements That Changed

Item	EasyMenu 6	EasyMenu 7
Server	Spigot, Paper, Folia	Paper, Purpur, Folia
Java	17+	17+
Minecraft	1.20.1+	1.20.1+
Required Plugin	None	NegiLib 1.x
PlaceholderAPI	Optional	Optional

Spigot Support

Because NegiLib relies on the Folia scheduler API, Spigot is no longer supported. Please use Paper, Purpur, or Folia.

Existing Configuration Compatibility

All YAML features from EasyMenu 6 continue to work without modification:

menu-title: "&6&lEasyMenu"
menu-opensound: "ENTITY_EXPERIENCE_ORB_PICKUP"
menu-background-item: "GRAY_STAINED_GLASS_PANE"
menu-size: 54

menu-items:
  - location: "3,3"          # location and slot both supported
    material: "RED_BED"
    name: "&c&lHome"
    command: "/home"         # slash optional
    sound: "ENTITY_ENDERMAN_TELEPORT"
    close-menu: true
    lore:
      - "&7Teleport to your home"

  - slot: 22
    material: "EMERALD"
    command: "sub_shop"      # opens submenu "shop"

  - slot: 26
    material: "BARRIER"
    command: "main_mainopen" # opens main menu

Typed actions (actions:), click-policy, custom-model-data, and the input action remain fully supported.

Notable Behavior Improvements

Change	Rationale
command: "shop buy diamond" without a leading slash now runs as a player command (was rejected in 6)	Makes shorthand commands more intuitive
Declaring actions that produce 0 effective actions is now an error during reload	Prevents buttons from silently turning into dead decorative items
Target menu IDs in open-menu that do not exist are caught at reload time	Catches typos before players encounter runtime errors
open-menu waits until the target menu is fully rendered before continuing the action pipeline	Ensures subsequent messages describe the newly opened menu
Form input initial values are verified against the input contract	Prevents initial submissions from failing unexpectedly
Unknown sound names produce warnings and drop only the sound action	Non-critical sound errors do not prevent menus from opening

New config.yml Keys

Your existing config.yml keeps working. On first launch with v7, new configuration keys are populated with safe defaults:

runtime:
  default-presentation: inventory   # default display mode for menus

diagnostics:
  log-warnings-on-load: true

input:
  default-timeout-seconds: 60

cooldown:
  cleanup-interval-seconds: 60

Rolling Back

EasyMenu 7 never rewrites your menu files (main.yml, sub/*.yml) into a newer syntax.

config.yml, however, is saved with any missing new keys appended using their defaults at startup. EasyMenu 6 ignores unknown keys, so it still works, but if you want a perfectly restored state, back up config.yml before upgrading. To roll back, put EasyMenu-6.x.x.jar back and restore config.yml if needed.

Legacy Syntax vs. Recommended Syntax

Everything written for EasyMenu 6 still works. For new menus the right-hand column is recommended.

Legacy (still works)	Recommended	Difference
location: "5,2"	slot: 13	location is a 1-based "column,row"; slot is a 0-based index. slot wins when both are present.
command: "/spawn" / command: "spawn"	action: with type: player-command	The slash is optional. Both run with the player's permissions.
command: "sub_shop"	action: with type: open-menu, menu: shop	The shorthand is converted to open-menu internally. Use actions: to combine it with other steps.
command: "main_mainopen"	type: open-menu, menu: main	Same as above.
Running as console via command: (not possible)	type: console-command	command: always runs as the player. Use a typed action for console authority.
dialog: true	mode: native-preferred under presentation:	dialog is a shorthand. When both are written, presentation wins.
menu-size / menu-background-item	presentation.inventory.size / background	Both work. The former is used when presentation.inventory is omitted.

---

Migrating from EasyMenu 5.x to EasyMenu 6 (Archive)

For servers upgrading from legacy EasyMenu 5.x:

Automatic Folder Migration

The legacy folder is automatically migrated on startup:

plugins/EasyMenuPlugin/  →  plugins/EasyMenu/

If your old config.yml contained inline menu definitions, they are automatically separated into plugins/EasyMenu/main.yml.

Command Changes

The old /menureload command was removed in favor of:

/menu reload

Permission: easymenu.command.reload (or easymenu.admin).

Supported Legacy Syntax

• location: "5,3"
• command: "/spawn"
• command: "sub_shop"
• command: "main_mainopen"
• close-menu: true