# Menu File Structure

## 📂 Folder Layout

All menu files are stored uniformly in `plugins/KaMenu/menus/` directory, supporting subfolder structures of any depth:

```
plugins/KaMenu/menus/
├── main_menu.yml           # root directory menu
├── server_shop.yml         # root directory menu
├── example/                # example folder
│   └── actions_demo.yml    # demo menu
├── shop/                   # shop folder
│   ├── main.yml            # shop main menu
│   ├── weapons.yml         # weapon shop
│   └── armor.yml           # armor shop
└── admin/                  # admin tools folder
    └── tools.yml           # management tools
```

***

## 🎯 Menu ID Rules

The menu ID is determined by the file path:

* **Root directory menu**: directly use the file name (excluding `.yml`)

  ```
  /km open main_menu
  /km open server_shop
  ```
* **Subfolder menu**: use `/` the path relative to the separator

  ```
  /km open example/actions_demo
  /km open shop/weapons
  /km open admin/tools
  ```

***

## ✏️ Add Custom Menu

1. In `plugins/KaMenu/menus/` create `.yml` file (you can create subfolders as needed)
2. Write the content according to the menu configuration format (see later sections)
3. Run `/km reload` to reload

**File naming notes:**

* ✅ Chinese file and folder names are supported
* ⚠️ The file extension must be `.yml`(not `.yaml`)
* ⚠️ Use `/`as the path separator, not `\`

***

## 📝 Tab Completion

Enter `/km open` then press the Tab key, and all loaded menu IDs will be listed automatically, including subfolder paths:

```
demo
server_shop
example/actions_demo
shop/weapons
admin/tools
```

***

## 📄 Basic Menu File Structure

The basic structure of a complete menu YAML file is as follows:

```yaml
# Menu title (supports color codes and conditional logic)
Title: '&6Menu Title'

# Optional: global settings
Settings:
  can_escape: true      # whether ESC is allowed to close
  after_action: CLOSE   # behavior after a button action is executed
  
# Optional: predefined JavaScript functions 
JavaScript:
  test: |
    player.sendMessage("§aHello, " + name + "!");
    
# Optional: menu events
Events:
  Open:                # actions executed when the menu opens
    - 'tell: &aWelcome!'

# Optional: content display area (plain text, item display, etc.)
Body:
  ...

# Optional: input component area (text box, slider, dropdown, checkbox)
Inputs:
  ...

# Optional: bottom button area (confirm/cancel/multiple buttons, etc.)
Bottom:
  type: 'notice'       # notice | confirmation | multi
  ...
```

{% hint style="info" %}
Only `Title` node is required; all other nodes are optional. You can add the corresponding features as needed.
{% endhint %}

***

## 🎨 Menu File Node Descriptions

### Title - Menu Title

A required top-level node that defines the title displayed by the menu.

**Format:**

* Single-line text:`Title: '&6Menu Title'`
* Conditional logic: supports showing different titles based on different conditions

**Example:**

```yaml
Title: '&6Shop'

# Use conditional logic
Title:
  - condition: "%player_is_op% == true"
    allow: '&4Admin Shop'
    deny: '&6Regular Shop'
```

### Settings - Global Settings

Configure the menu's global behavior parameters.

**Settings:**

| Setting        | Type      | Default | Description                                                      |
| -------------- | --------- | ------- | ---------------------------------------------------------------- |
| `can_escape`   | `Boolean` | `true`  | Whether players are allowed to close the menu with the ESC key   |
| `after_action` | `String`  | `CLOSE` | Client behavior after clicking a button and executing its action |

**Detailed explanation and examples:** See [⚙️ Global Settings (Settings)](/plugins/kamenu-en/menu/setting.md)

### JavaScript - Predefined Functions

Predefined JavaScript code functions that can be called in actions.

**Example:**

```yaml
JavaScript:
  show_health: |
    var health = player.getHealth();
    var maxHealth = player.getMaxHealth();
    player.sendMessage("§eHealth: §f" + health + "/" + maxHealth);
```

**Call in action**

```yaml
actions:
  - 'js: [show_health]'
```

**Detailed explanation and examples:** See [🔧 Predefined JavaScript Functions (JavaScript)](/plugins/kamenu-en/menu/javascript.md)

### Events - Menu Events

Defines the actions executed by the menu at specific moments.

**Supported events:**

| Event Name | Trigger Timing                  |
| ---------- | ------------------------------- |
| `Open`     | When the player opens the menu  |
| `Close`    | When the player closes the menu |

**Example:**

```yaml
Events:
  Open:
    - 'tell: &aWelcome to the menu!'
    - 'sound: entity.experience_orb.pickup'
  Close:
    - 'tell: &7Goodbye!'
```

**Detailed explanation and examples:** See [🎯 Menu Events (Events)](/plugins/kamenu-en/menu/events.md)

### Body - Content Display Area

Display various content in the main menu area, such as plain text messages and item displays.

**Component types:**

* `message` - plain text message
* `item` - item display

**Detailed explanation and examples:** See [🧩 Content Components (Body)](/plugins/kamenu-en/menu/body.md)

### Inputs - Input Component Area

Provides user input components such as text boxes, sliders, dropdowns, etc.

**Component types:**

* `input` - text input box
* `slider` - slider
* `dropdown` - dropdown selection box
* `checkbox` - checkbox

**Detailed explanation and examples:** See [⌨️ Input Components (Inputs)](/plugins/kamenu-en/menu/inputs.md)

### Bottom - Bottom Button Area

Configure the buttons at the bottom of the menu, supporting multiple layout types.

**Layout types:**

* `notice` - notice type (single confirm button)
* `confirmation` - confirmation type (confirm and cancel buttons)
* `multi` - multi-button type (custom multiple buttons)

**Detailed explanation and examples:** See [📋 Bottom Buttons (Bottom)](/plugins/kamenu-en/menu/bottom.md)

***

## 🚀 Next Steps

After understanding the menu file structure, you can:

1. **Create your first menu**: view [📝 Menu Creation Tutorial](/plugins/kamenu-en/menu/creating_menu.md)
2. **Learn more about each component in depth**: read the corresponding detailed documentation
3. **Explore advanced features**: conditional logic, data storage, action system, etc.

{% hint style="success" %}
It is recommended to start with [📝 Menu Creation Tutorial](/plugins/kamenu-en/menu/creating_menu.md) and follow the tutorial step by step to create your first menu!
{% endhint %}


---

# 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/menu/structure.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.