# Global Settings (Setting)

`Settings` The node is used to configure the menu's global behavior parameters, including how it is closed and what happens after an action is executed.

***

## Overview of configuration items

| Configuration item | Type           | Default value | 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 to execute an action   |
| `need_placeholder` | `List<String>` | `null`        | List of PlaceholderAPI expansions required by the menu         |

***

## can\_escape parameter

### Function description

Controls how the menu is closed, determining whether players can close it with the ESC key.

### Optional values

| Value           | Description                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| `true`(default) | Players can close the menu with the ESC key; when closed, the corresponding button's action will be executed |
| `false`         | Players must click the specified button to close the menu; ESC exit is disabled                              |

### Example configuration

```yaml
Settings:
  can_escape: false  # Force players to click a button to close the menu
```

### Usage scenarios

**Recommended use `true`(default):**

* Normal menus, allowing players to exit at any time
* Scenarios that need flexible closing

**Recommended use `false`：**

* Important confirmation menus (such as confirm delete, confirm payment)
* Admin operation menus
* Scenarios where you need to ensure the user selects an option

### Default action for ESC close

When `can_escape: true` is set, pressing the ESC key will execute the corresponding button's action:

| Menu type      | Button executed              |
| -------------- | ---------------------------- |
| `notice`       | `confirm` / `button1` button |
| `confirmation` | `deny` button                |
| `multi`        | `exit` button                |

**Example configuration:**

```yaml
Settings:
  can_escape: true

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm ]'
    actions:
      - 'tell: &aYou chose confirm'
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'tell: &cYou chose cancel'  # This action is executed when the ESC key is pressed
```

***

## after\_action parameter

### Function description

Defines the client's behavior while waiting for the server response after a player clicks a button.

### Background: Why is this parameter needed?

There is a certain delay in network communication between the server and client:

* **Normal case**：Delay is only a few dozen milliseconds
* **Poor network / high server load**：Delay may reach 1 second or longer

During this period, if the player operates on the game world (such as moving items, dropping items, etc.), the subsequent menu logic may become inconsistent with the actual state, causing abnormal behavior.

`after_action` This parameter is used to declare a specified local client-side action, preventing players from performing illegal operations while waiting for the server response and ensuring the integrity of the menu logic.

### Optional values

| Value               | Client behavior                                     | Applicable scenarios                                                          |
| ------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| `CLOSE`(default)    | Close the menu interface directly                   | Scenarios without a submenu or without the need to handle subsequent behavior |
| `NONE`              | Do not perform any local behavior                   | Most scenarios, where the action after clicking is determined by the server   |
| `WAIT_FOR_RESPONSE` | Display an overlay and wait for the server response | Scenarios with submenus or involving important operations                     |

### Example configuration

```yaml
Settings:
  after_action: CLOSE  # Default value
  # after_action: NONE
  # after_action: WAIT_FOR_RESPONSE
```

### Detailed explanation

#### 1. CLOSE (default)

After clicking the button, the client immediately closes the menu interface.

**Advantages:**

* Simple and direct
* Smooth user experience

**Disadvantages:**

* Cannot prevent illegal operations during network latency

**Applicable scenarios:**

* Simple menus without submenus
* Scenarios that do not need subsequent behavior processing

**Example:**

```yaml
Settings:
  after_action: CLOSE

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ Close ]'
    actions:
      - 'close'
```

#### 2. NONE

After clicking the button, the client performs no local behavior; all logic is controlled by the server.

**Advantages:**

* Highest flexibility
* Server fully controls menu behavior
* **Recommended choice for most scenarios**

**Disadvantages:**

* Need to explicitly close the menu in the action list

**Applicable scenarios:**

* Most menus (recommended default)
* Scenarios where behavior must be fully controlled by the server
* Scenarios where whether to close depends on conditions

**Example:**

```yaml
Settings:
  after_action: NONE

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm Delete ]'
    actions:
      - condition: '%player_balance% >= 1000'
        allow:
          - 'console: eco take %player_name% 1000'
          - 'tell: &aDeduction successful!'
          - 'close'  # Manually close the menu
        deny:
          - 'tell: &cInsufficient balance!'
          # Do not close the menu, let the player choose again
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'close'
```

#### 3. WAIT\_FOR\_RESPONSE

After clicking the button, the client displays an overlay and continues after the server responds.

**Advantages:**

* Completely prevents illegal operations during network latency
* Suitable for important operations
* Stable user experience

**Disadvantages:**

* You need to make sure the menu is closed (otherwise it will get stuck on the overlay)
* Adds one extra waiting step

**Applicable scenarios:**

* Has a submenu (will automatically open a new menu)
* Involves important operations (transactions, permission changes)
* Servers with unstable networks or low TPS

{% hint style="warning" %}
**Important note:**

When using `WAIT_FOR_RESPONSE` if the button**does not have submenu functionality**you must add the `close` action to the action list. Otherwise, the client will keep showing the overlay and the player will be unable to operate.
{% endhint %}

**Example (with submenu):**

```yaml
Settings:
  after_action: WAIT_FOR_RESPONSE

Bottom:
  type: 'multi'
  buttons:
    open_sub_menu:
      text: '&a[ Open Submenu ]'
      actions:
        - 'open: shop/weapons'  # Opens a submenu, automatically closes the overlay
    exit:
      text: '&c[ Exit ]'
      actions:
        - 'close'
```

**Example (no submenu, must close manually):**

```yaml
Settings:
  after_action: WAIT_FOR_RESPONSE

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm Payment ]'
    actions:
      - 'console: eco take %player_name% 1000'
      - 'tell: &aPayment successful!'
      - 'close'  # Required: close the menu, remove the overlay
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'close'  # Required: close the menu, remove the overlay
```

## need\_placeholder parameter

### Function description

Configures the list of PlaceholderAPI expansions required by the menu. Before opening the menu, the plugin checks whether the required expansions are loaded. If an expansion is not loaded:

* **Admin players (with kamenu.admin permission)**: A detailed prompt will be shown, including the list of missing expansions and a clickable download button
* **Regular players**: A simplified prompt message will be shown

This feature ensures that placeholder variables in the menu work properly and avoids display errors caused by missing expansions.

### Configuration format

```yaml
Settings:
  need_placeholder:
    - 'player'     # Player expansion
    - 'server'     # Server expansion
    - 'vault'      # Vault expansion
```

### Optional values

`need_placeholder` It is a list of strings, where each element represents the identifier of a PlaceholderAPI expansion.

### Example configuration

**Basic example:**

```yaml
Title: '&8» &6&lPlayer Info &8«'

Settings:
  need_placeholder:
    - 'player'
    - 'vault'

Body:
  message:
    type: 'message'
    text: |
      &aPlayer name: %player_name%
      &aPlayer balance: %vault_eco_balance%
      &aTime online: %player_time_played%

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ OK ]'
    actions:
      - 'close'
```

### Admin prompt

When an admin (with kamenu.admin permission) tries to open a menu that is missing dependencies, the following kind of message will be shown:

```
§cThis menu requires the following PlaceholderAPI expansions: §e[player], §e[server]
```

Each expansion name (such as `[player]`) is clickable:

* **Click expansion**: Automatically execute `/papi ecloud download <expansion name>` command
* **Hover to display**: Shows the specific download command that will be executed

### Regular player prompt

Regular players will see a simplified prompt:

```
§cThis menu is missing required dependency files, please contact an administrator.
```

(Can be customized in the language file)

{% hint style="info" %}
**How to get the expansion identifier:**

1. When using `/papi list` Use the command to view installed expansions
2. Visit [PlaceholderAPI Expansion](https://wiki.placeholderapi.com/users/placeholder-list/minecraft/) Search for expansions
3. View the expansion's official documentation or source code
   {% endhint %}

***

## Complete example

### Example 1: Normal shop menu (recommended configuration)

```yaml
Title: '&8» &6&lServer Shop &8«'

Settings:
  can_escape: true        # Allow ESC to exit
  after_action: NONE      # Controlled by the server
  pause: false

Bottom:
  type: 'multi'
  buttons:
    buy:
      text: '&a[ Buy ]'
      actions:
        - 'console: give %player_name% diamond 1'
        - 'console: eco take %player_name% 100'
        - 'tell: &aPurchase successful!'
        - 'close'
    exit:
      text: '&c[ Exit ]'
      actions:
        - 'tell: &cGoodbye!'
        - 'close'
```

### Example 2: Important confirmation menu

```yaml
Title: '&8» &c&lConfirm Delete &8«'

Settings:
  can_escape: false                # Disable ESC exit
  after_action: WAIT_FOR_RESPONSE  # Prevent actions during network latency
  pause: false

Bottom:
  type: 'confirmation'
  confirm:
    text: '&c[ Confirm Delete ]'
    actions:
      - condition: '%player_name% == target_player'
        allow:
          - 'tell: &aTarget item deleted'
          - 'close'  # Required: close the menu
        deny:
          - 'tell: &cYou are not the item owner!'
          - 'close'
  deny:
    text: '&a[ Cancel ]'
    actions:
      - 'tell: &aDelete canceled'
      - 'close'  # Required: close the menu
```

### Example 3: Admin operation menu

```yaml
Title: '&8» &4&lAdmin Tools &8«'

Settings:
  can_escape: false                # Disable ESC exit
  after_action: NONE               # Controlled by the server
  pause: false

Bottom:
  type: 'multi'
  buttons:
    ban:
      text: '&c[ Ban Player ]'
      actions:
        - 'open: admin/ban_player'
    kick:
      text: '&e[ Kick Player ]'
      actions:
        - 'open: admin/kick_player'
    exit:
      text: '&7[ Back ]'
      actions:
        - 'open: main_menu'
```

### Example 4: Simple notification menu

```yaml
Title: '&8» &a&lNotice &8«'

Settings:
  can_escape: true        # Allow ESC to exit
  after_action: CLOSE      # Close directly
  pause: false

Body:
  message:
    type: 'message'
    text: |
      &aWelcome to our server!
      &7Please follow the server rules and help maintain a good gaming environment together.

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ OK ]'
    actions:
      - 'tell: &aNotice read'
```

***

## Best practices

### 1. Recommended default configuration

For most menus, the following default configuration is recommended:

```yaml
Settings:
  can_escape: true
  after_action: NONE
```

### 2. Important operation configuration

For menus involving important operations (deletion, payment, permission changes, etc.):

```yaml
Settings:
  can_escape: false
  after_action: WAIT_FOR_RESPONSE
```

**Important note:** When using `WAIT_FOR_RESPONSE` when set, make sure the action list of all buttons includes `close` the action (unless there is a submenu).

### 3. Conditional close configuration

When you need to decide whether to close the menu based on conditions:

```yaml
Settings:
  can_escape: true
  after_action: NONE

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm ]'
    actions:
      - condition: 'checkCondition'
        allow:
          - 'tell: &aOperation successful'
          - 'close'
        deny:
          - 'tell: &cOperation failed, please try again'
          # Do not close the menu
```

### 4. Network environment considerations

**Servers with good network:**

* Use in most scenarios `after_action: NONE`
* Simple menus can use `after_action: CLOSE`

**Servers with unstable networks or low TPS:**

* Use for important operations `after_action: WAIT_FOR_RESPONSE`
* Ensure the menu close is handled correctly

***

## Notes

1. **after\_action selection**
   * Use by default `NONE`Highest flexibility
   * Use for important operations `WAIT_FOR_RESPONSE`Ensure data consistency
   * `WAIT_FOR_RESPONSE` Must be used together with `close` action (unless there is a submenu)
2. **can\_escape usage**
   * Keep normal menus `true`to provide a better user experience
   * Set important confirmation menus to `false`to force users to make a choice
3. **pause parameter**
   * Only effective in single-player; no need to worry on multiplayer servers
   * Usually keep the default value `false`
4. **Backward compatibility**
   * Older versions of configuration files do not include `Settings` node; use the default value
   * It is recommended that all new configuration files include the `Settings` node

***

## Related documentation

* [🔘 Bottom Button (Bottom)](/plugins/kamenu-en/menu/bottom.md) - Learn about button action configuration
* [🤖 Actions](/plugins/kamenu-en/menu/actions.md) - Learn about all available action types
* [⚙️ Events](/plugins/kamenu-en/menu/events.md) - Learn about the event system
* [📊 PlaceholderAPI](/plugins/kamenu-en/placeholderapi.md) - Learn about PlaceholderAPI integration


---

# 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/setting.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.