# API Interface

KaMenu provides a public API that allows other plugins to open KaMenu menus.

## API class

### `org.katacr.kamenu.api.KaMenuAPI`

#### Methods

**`openMenu(Player player, String menuId)`**

Opens the specified menu.

**Parameters:**

* `player` - Target player
* `menuId` - Menu ID (e.g. "main\_menu" or "shop/weapons")

**Return value:**

* `boolean` - Whether the menu was opened successfully

**Example:**

```kotlin
import org.katacr.kamenu.api.KaMenuAPI
import org.bukkit.entity.Player

// Open the main menu
val success = KaMenuAPI.openMenu(player, "main_menu")
if (!success) {
    player.sendMessage("§cFailed to open menu!")
}

// Open a submenu folder menu
KaMenuAPI.openMenu(player, "shop/weapons")
```

```java
import org.katacr.kamenu.api.KaMenuAPI;
import org.bukkit.entity.Player;

// Open the main menu
boolean success = KaMenuAPI.openMenu(player, "main_menu");
if (!success) {
    player.sendMessage("§cFailed to open menu!");
}

// Open a submenu folder menu
KaMenuAPI.openMenu(player, "shop/weapons");
```

**`isAvailable()`**

Checks whether KaMenu has been loaded.

**Return value:**

* `boolean` - Whether KaMenu is available

**Example:**

```kotlin
if (KaMenuAPI.isAvailable()) {
    KaMenuAPI.openMenu(player, "main_menu")
} else {
    player.sendMessage("§cKaMenu plugin is not installed or not enabled")
}
```

**`getPlugin()`**

Gets the KaMenu plugin instance.

**Return value:**

* `KaMenuPlugin` - KaMenu plugin instance; returns null if not loaded

## Using in other plugins

### Method 1: Use reflection directly (no dependency required)

If your plugin does not need to depend on KaMenu directly, you can call the API via reflection:

```kotlin
fun openKaMenu(player: Player, menuId: String): Boolean {
    try {
        val kaMenuPlugin = player.server.pluginManager.getPlugin("KaMenu")
        if (kaMenuPlugin == null) {
            player.sendMessage("§cKaMenu plugin is not installed or not enabled")
            return false
        }

        val apiClass = Class.forName("org.katacr.kamenu.api.KaMenuAPI")
        val openMenuMethod = apiClass.getMethod("openMenu", org.bukkit.entity.Player::class.java, String::class.java)
        val result = openMenuMethod.invoke(null, player, menuId)
        return result == true
    } catch (e: Exception) {
        e.printStackTrace()
        return false
    }
}
```

### Method 2: Add dependency (recommended)

If you want to use a type-safe API, you can add KaMenu as a dependency in `plugin.yml` :

```yaml
name: YourPlugin
version: 1.0.0
main: com.yourname.yourplugin.Main
api-version: "1.21"
depend:
  - KaMenu
```

Then use it directly:

```kotlin
import org.katacr.kamenu.api.KaMenuAPI

fun openShop(player: Player) {
    KaMenuAPI.openMenu(player, "shop/weapons")
}
```

## Use in actions

The KaGuilds plugin has already integrated the KaMenu API, so it can be used in menu configuration `kamenu:` Actions:

```yaml
# KaGuilds menu configuration example
guild_manage:
  type: NOTICE
  layout: ...
  buttons:
    kamenu_demo:
      icon: BOOK
      text: "&aOpen KaMenu demo menu"
      actions:
        right:
          - 'kamenu: condition_demo'
        left:
          - 'tell: &aOpening KaMenu menu...'
          - 'kamenu: example/actions_demo'
```

## Notes

1. **Plugin dependency**: Make sure KaMenu is installed and enabled
2. **Menu exists**: Make sure the menu ID you want to open exists
3. **Asynchronous call**: The API methods themselves are synchronous, but in some cases you may need to call them asynchronously
4. **Error handling**: It is recommended to add proper error handling so that feedback can be provided when an API call fails

## Full example

Here is a complete plugin example showing how to use the KaMenu API:

```kotlin
package com.example.plugin

import org.bukkit.plugin.java.JavaPlugin
import org.bukkit.command.Command
import org.bukkit.command.CommandSender
import org.bukkit.entity.Player
import org.katacr.kamenu.api.KaMenuAPI

class ExamplePlugin : JavaPlugin() {
    override fun onEnable() {
        logger.info("ExamplePlugin has been enabled")

        // Check whether KaMenu is available
        if (!KaMenuAPI.isAvailable()) {
            logger.warning("KaMenu plugin is not installed, some features will be unavailable")
        }
    }

    override fun onCommand(
        sender: CommandSender,
        command: Command,
        label: String,
        args: Array<out String>
    ): Boolean {
        if (command.name.equals("openmenu", ignoreCase = true)) {
            if (sender !is Player) {
                sender.sendMessage("§cThis command can only be executed by a player")
                return true
            }

            if (!KaMenuAPI.isAvailable()) {
                sender.sendMessage("§cKaMenu plugin is not installed or not enabled")
                return true
            }

            val menuId = if (args.isNotEmpty()) args[0] else "main_menu"
            val success = KaMenuAPI.openMenu(sender, menuId)

            if (success) {
                sender.sendMessage("§aSuccessfully opened menu: $menuId")
            } else {
                sender.sendMessage("§cFailed to open menu, please check whether the menu ID is correct")
            }
            return true
        }
        return false
    }
}
```

Corresponding `plugin.yml`:

```yaml
name: ExamplePlugin
version: 1.0.0
main: com.example.plugin.ExamplePlugin
api-version: "1.21"
depend:
  - KaMenu

commands:
  openmenu:
    description: Open KaMenu menu
    usage: /openmenu [menuID]
    permission: exampleplugin.openmenu
    permission-message: "§cYou do not have permission to execute this command"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://katacr.gitbook.io/plugins/kamenu-en/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.