# Custom Commands

KaMenu provides powerful custom command functionality, allowing you to create independent, concise open commands for each menu, greatly improving the player experience.

## Why use custom commands?

### ❌ Drawbacks of the traditional approach

When using `/kamenu open <menu name>` Opening menus has the following issues:

* **Long commands**: Players need to enter the full menu path, creating a heavy memory burden
* **Permission issues**: You must grant players `kamenu.admin` permissions; players can open all menus, which creates security risks
* **Complex management**: If you want to restrict specific players from accessing specific menus, you need to configure a complex permission system

### ✅ Advantages of custom commands

Use registered commands to open menus:

* **Simple and fast**: Each menu has an independent short command, such as `/main`,`/shop` etc., making them easy to remember
* **Flexible permissions**: No permission configuration is needed; all players can see the command
* **Conditional control**: In the menu's `Events.Open` event, check conditions to freely control who can open the menu

## Configure custom commands

In the `config.yml` Configure custom commands in:

```yaml
custom-commands:
  # Custom command name: menu ID
  main: example/main_menu
  shop: example/shop_menu
  vip: example/vip_menu
  admin: example/admin_menu
```

## Example: Restrict access for specific players

Suppose you only want VIP players to open the VIP menu; without configuring permissions, just add a conditional check in the menu's `Events.Open` event:

```yaml
Events:
  Open:
    - condition: "hasPerm.user.vip"
      actions:
        - 'tell: Welcome to the VIP menu!'
      deny:
        - 'tell: §cYou do not have the user.vip permission and cannot access this menu'
        - 'return'
```

After configuring this:

* ✅ All players can try to execute `/vip` command
* ✅ Only players with the `vip` permission can successfully open the menu
* ✅ Other players will receive a prompt message, and the menu will not open

## Usage scenarios

### Scenario 1: Quick access to commonly used menus

Create short commands for commonly used menus:

```yaml
custom-commands:
  menu: example/main_menu      # Main menu
  warp: example/warp_menu      # Teleport menu
  shop: example/shop_menu      # Shop menu
  bank: example/bank_menu      # Bank menu
```

Players only need to enter `/menu`,`/warp` and other simple commands to access quickly.

### Scenario 2: Conditional access to privileged menus

Create special menus for VIPs, administrators, etc.:

```yaml
custom-commands:
  vip: example/vip_menu
  admin: example/admin_menu
  owner: example/owner_menu
```

Then in each corresponding `Events.Open` check player permissions to achieve conditional access.

### Scenario 3: Independent entry points for feature menus

Create independent entry points for specific features:

```yaml
custom-commands:
  daily: example/daily_reward     # Daily check-in
  mail: example/mail_system        # Mail system
  quest: example/quest_system      # Quest system
```

## Best practices

### 1. Naming conventions

* Use short, easy-to-remember English names
* Avoid special symbols
* It is recommended to use lowercase letters for better compatibility

```yaml
# ✅ Recommended
custom-commands:
  menu: ...
  shop: ...
  vip: ...

# ❌ Not recommended
custom-commands:
  @shop: ...           # Special symbols may conflict
  VERYLONGNAME: ...    # Too long and inconvenient to type
  help: ...         # Try to avoid conflicts with other plugins
```

### 2. Conditional check recommendations

In the `Events.Open` When using conditional checks in , it is recommended to:

* Provide clear prompt messages
* When using `return` The action prevents players who do not meet the conditions from opening the menu
* Combine `data` or `meta` to achieve more flexible access control

```yaml
Events:
  Open:
    # Multi-condition combined check
    - condition: "hasPerm.user.vip && %player_level% >= 10"
      actions:
        - 'tell: Welcome to the VIP menu'
      deny:
        - 'tell: §cYou need the user.vip permission and level 10 or higher to access this menu'
        - 'return'
```

### 3. Reload command

After modifying `config.yml` , execute the following command to reload:

```
/kamenu reload
```

The system will automatically register all custom commands without needing to restart the server.

## Technical details

* Custom commands are automatically registered when the server starts
* Supports `/kamenu reload` hot reload, no server restart required
* Command names are case-insensitive (`/menu` and `/MENU` has the same effect)
* Custom commands are independent of the main command and do not affect each other.

## Summary

The custom command feature makes menu access simple, safe, and flexible. By using it properly, you can:

1. Simplify the player's operation flow
2. Avoid complex permission configuration
3. Achieve fine-grained access control through conditional checks
4. Improve the overall user experience

Start using custom commands and make your plugin more user-friendly and powerful!


---

# 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/config/customcommands.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.