Menu API

Overview

The Menu API provides a clean interface for external plugins to interact with PhantomDungeons config-driven menu system. Open menus for players, pass variables between menus, and access menu contexts seamlessly.

All menus are defined in YAML files in the menus/ folder and loaded dynamically at runtime.

Getting Started

1

Get the API Instance

In your plugin's onEnable, grab the API instance.

Java

import me.fergs.phantomdungeons.modules.menu.api.MenuAPI;

// Get the singleton instance
MenuAPI menuAPI = MenuAPI.get();

Add depend: [PhantomDungeons] to your plugin.yml to ensure proper load order.

2

Cache for Performance

Store it in your main plugin class.

Java

public class MyPlugin extends JavaPlugin {
    private MenuAPI menuAPI;
    
    @Override
    public void onEnable() {
        try {
            this.menuAPI = MenuAPIProvider.get();
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
}

3

Safe Null Checks

Always check availability before using.

Java

if (menuAPI == null) {
    getLogger().warning("Menu API not available!");
    return;
}

Core Operations

Opening Menus

Open configured menus for players.

Java

// Open a menu by ID
boolean success = menuAPI.openMenu(player, "sword-upgrade-inventory");

if (success) {
    player.sendMessage("§aMenu opened!");
} else {
    player.sendMessage("§cMenu not found!");
}

Opening Menus with Variables

Pass custom variables to menus for dynamic content.

Java

// Create variables map
Map<String, String> variables = new HashMap<>();
variables.put("enchant", "speed");
variables.put("tier", "5");

// Open menu with variables
boolean success = menuAPI.openMenu(player, "upgrade-enchant-inventory", variables);

// Variables can be used in the menu YAML:
// - name: '&aUpgrading: &e{enchant}'
// - lore: '&7Tier: &f{tier}'

Variables use {variable_name} syntax and are replaced throughout the menu configuration including titles, lore, conditions, and actions.

Closing Menus

Close a player's open menu programmatically.

Java

// Close specific menu by ID
boolean closed = menuAPI.closeMenu(player, "sword-upgrade-inventory");

if (closed) {
    player.sendMessage("§aMenu closed!");
}

Menu Contexts

Getting Active Context

Retrieve the current menu context for a player.

Java

MenuVariableContext context = menuAPI.getActiveInventoryContext(player);

if (context != null) {
    // Get menu ID
    String menuId = context.getMenuId();
    
    // Get specific variable
    String enchant = context.getVariable("enchant");
    
    // Get all variables
    Map<String, String> allVars = context.getVariables();
    
    player.sendMessage("§7Current Menu: §a" + menuId);
}

Menu contexts persist throughout menu navigation and can be passed between parent and child menus.

Checking Menu Existence

Validate menu IDs before opening.

Java

// Check if menu exists
if (menuAPI.menuExists("custom-menu")) {
    menuAPI.openMenu(player, "custom-menu");
} else {
    player.sendMessage("§cMenu 'custom-menu' not found!");
}

Action Chaining

Multiple actions can be executed in sequence.

YAML

any-click-actions:
  - '[sound] ENTITY_PLAYER_LEVELUP'
  - '[upgrade-enchant] {enchant} 1'
  - '[message] &aSuccessfully upgraded {enchant}!'
  - '[menu] sword-enchant-inventory'

Variable System

Variables are powerful for creating dynamic menus.

Variable Sources

1

Passed Variables

Variables explicitly passed via API.

2

Parent Variables

Variables inherited from parent menu.

3

PlaceholderAPI

Any PAPI placeholder (e.g., %player_name%).

4

Menu Variables

Variables set within the menu itself.

Variable Syntax

YAML

inventory:
  title: '&8&lUpgrading: &e{enchant}'  # Custom variable
  slots: 27

items:
  'upgrade-button':
    name: '&a&lUpgrade {enchant}'
    lore:
      - '&7Current Level: &f%phantomdungeons_enchant_{enchant}_level%'
      - '&7Cost: &e{cost} Souls'
    slots: '13'

Frequently Asked Questions

How do I create a new menu?

Create a new YAML file in plugins/PhantomDungeons/menus/ with your menu configuration. The file name becomes the menu ID. Reload the plugin with /dungeons reload or restart the server.

Example file: menus/my-custom-menu.yml

Can variables persist across multiple menu navigations?

Yes. Variables are stored in the MenuVariableContext which persists as players navigate between menus. Child menus inherit variables from their parent context.

How do I debug menu issues?

Use the admin commands:

• /dungeons menu list - Show all loaded menus

• /dungeons menu reload [menu_id] - Reload specific menu or all menus

• Check the console for parsing errors during startup or reload

Can I use PlaceholderAPI placeholders in menus?

Yes. All PlaceholderAPI placeholders work in menu configurations including titles, item names, lore, and conditions. Variables and placeholders are processed together.

What happens if a player disconnects with a menu open?

Menu contexts are session-based and automatically cleaned up when a player disconnects. No data persists beyond the session.

---

Related APIs

Economy APIBoosters APIEnchants APILevelling APISword API