# Permission List

KaMenu adopts an ultra-minimal permission design philosophy, retaining only the core management permission and leaving all access control to the configuration system for flexible implementation.

***

## 💡 Design Philosophy

### Why is there only one permission?

KaMenu believes in**Configuration over permissions**as the design philosophy. Rather than using cumbersome permission nodes to control menu access, it is better to implement finer and more intuitive access control through a flexible configuration system.

**Core principles:**

* **Permission system**: only used for plugin management operations (such as reloading configuration)
* **Configuration system**: used for all menu access control (commands, items, condition checks)

### Why design it this way?

#### Problems with traditional permission systems

```yaml
# Traditional plugins usually require a large number of permission nodes
menu.main.open
menu.shop.open
menu.teleport.open
menu.admin.open
# ... may require dozens of permission nodes
```

**Problem:**

* A large number of permission nodes makes management difficult
* Permissions and menu files are separated, making the configuration scattered
* You need to remember many permission node names
* Unable to implement complex conditional access control

#### KaMenu's configuration-driven design

We can add opening actions inside the menu to determine whether the player meets the conditions.

```yaml
# Implement access control through condition checks
Events:
  open:
    actions:
      - condition: 'hasPerm.user.vip'
        allow:
          - 'tell: You have the user.vip permission, allowing you to open this menu.'  # Allow opening the menu
        deny:
          - 'tell: &cYou do not have the user.vip permission and cannot open this menu'
          - 'cancel'    # Prevent opening the menu
```

**Advantages:**

* All access control logic is centralized in the menu file
* Supports complex multi-condition checks
* No need to configure permission nodes, simplifying management
* More intuitive and more flexible

***

## 📋 Permission Overview

| Permission node | Description                                                    | Default owner |
| --------------- | -------------------------------------------------------------- | ------------- |
| `kamenu.admin`  | Allows management operations (such as reloading configuration) | OP only       |

***

## 🔧 kamenu.admin permission

### Function description

Allows server administrators to perform plugin management operations:

* Allows execution of `/kamenu` all commands

**Default status:** Only OP has this permission

***

## 🎯 Flexible implementation of access control

KaMenu implements menu access control through multiple configuration methods without relying on a permission system.

### 1. Custom commands - Who can use commands to open the menu?

Through `config.yml` in `custom-commands` to register custom commands, by default all players can use them.

```yaml
custom-commands:
  menu: 'main_menu'       # /menu -> can be executed by all players
  shop: 'server_shop'     # /shop -> can be executed by all players
```

### 2. Listener - Who can open the menu through items/keys?

Through `config.yml` Listener configuration in , automatically triggers menu opening.

```yaml
listeners:
  # Off-hand key trigger
  swap-hand:
    enabled: true
    menu: 'main_menu'
    require-sneaking: true  # Requires Shift + F

  # Right-click item trigger
  item-lore:
    main-menu:
      enabled: true
      material: 'CLOCK'
      target-lore: 'Menu'
      menu: 'main_menu'
      require-sneaking: false
```

**Default behavior:**

* All players holding the corresponding item or pressing the corresponding key will trigger it

### 3. Events.open conditions - Who can open the menu?

Through `Events.open` configuration in the menu file, fine-grained access control can be implemented.

#### Basic example: permission check

```yaml
Events:
  open:
    actions:
      - condition: 'hasPerm.kamenu.vip'
        allow:
          - 'tell: &aYou have the kamenu.vip permission, allowing the menu to open.'  # Continue opening the menu
        deny:
          - 'tell: &cYou need the kamenu.vip permission to access this menu'
          - 'return'    # Prevent opening the menu
```

#### Advanced example: multi-condition check

```yaml
Events:
  open:
    actions:
      # Check multiple conditions
      - condition: 'hasPerm.kamenu.vip && %vault_eco_balance% >= 100'
        allow:
          - 'tell: &aYou have the kamenu.vip permission and 100 coins, allowing the menu to open.'
        deny:
          - 'tell: &cYou need the kamenu.vip permission and 100 coins to access this menu'
          - 'return'
```

***

## 📝 Comparison Summary

### Traditional permission system vs KaMenu configuration-driven

| Feature                    | Traditional permission system                                | KaMenu configuration-driven                       |
| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------- |
| Number of permission nodes | Many (dozens)                                                | Very few (only 1)                                 |
| Configuration location     | Scattered (permission plugin + plugin configuration)         | Centralized (menu file)                           |
| Condition checks           | Does not support complex conditions                          | Supports arbitrarily complex conditions           |
| Flexibility                | Low                                                          | High                                              |
| Learning curve             | Need to remember many permission nodes                       | Configuration is intuitive and easy to understand |
| Maintenance cost           | High (changing permissions requires multiple configurations) | Low (centralized configuration)                   |

***

## 📚 Related documentation

* [⌨️ Custom Commands](/plugins/kamenu-en/config/customcommands.md) - Learn how to register custom commands
* [⚙️ Event system](/plugins/kamenu-en/menu/events.md) - Learn the detailed usage of Events.open
* [🔧 Condition checks](/plugins/kamenu-en/menu/conditions.md) - Learn various condition-checking methods
* [📋 Configuration file](/plugins/kamenu-en/config/config.md) - Learn the complete config.yml configuration


---

# 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/perm/permissions.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.