Global Settings (Settings)

The Settings node configures the menu's global behaviour, including how it can be closed and what happens after a button action is executed.

---

Configuration Overview#

Option	Type	Default	Description
can_escape	Boolean	true	Whether players can close the menu using the ESC key
after_action	String	CLOSE	Client-side behaviour after a button action is executed
lifetime	Long	300	Maximum time the menu may remain open, in seconds
need_placeholder	List<String>	null	List of PlaceholderAPI expansions required by the menu
min_click_delay	Long	0	Container menus only; minimum interval between valid button clicks in the same session, in milliseconds
pass_arguments	Section	Disabled	Menu argument-passing settings supported by Dialog and Container menus

---

pass_arguments - Menu Arguments#

pass_arguments creates an isolated argument context for the target menu. Arguments are not written to meta, the database, or shared YAML, so asynchronous actions cannot overwrite temporary shared values or observe stale data.

KaMenu uses the existing plural configuration node Settings; the full path is Settings.pass_arguments.

Configuration Format#

Settings:
  pass_arguments:
    enable: true
    default:
      - 'Default value'
      - '%player_name%'
      - '{meta:test}'
      - '{js:[hello]}'
    must: 2

Resolution Rules#

• enable: false or an omitted section disables the target menu argument context
• default is an index-ordered list of fallback arguments
• Explicit arguments take priority
• When explicit arguments are fewer than the default list, missing indexes use the corresponding default values
• Defaults are resolved before the target menu opens and support PlaceholderAPI, KaMenu built-in variables, MetaData, and JavaScript
• must is the minimum number of arguments after defaults have been applied; opening is rejected when the count is lower
• An omitted or 0 must value imposes no minimum
• Extra explicit arguments are preserved

Passing Arguments from Actions#

open and force-open accept arguments after the menu ID. Arguments may be separated by whitespace or English commas. Wrap an argument containing spaces in single quotes, double quotes, or backticks:

Buttons:
  profile:
    display:
      material: PLAYER_HEAD
      name: '&aOpen profile'
    actions:
      left:
        - 'open: profile/detail {meta:target} vip'
  search:
    display:
      material: PAPER
      name: '&aOpen search'
    actions:
      left:
        - 'open: search/result,`Diamond Sword`'

Inside the target menu, use {arg:0}, {arg:1}, and so on. {args} returns all arguments joined by spaces, and {arg_count} returns the argument count. These values can be used in titles, Body, button items, conditions, Events, and actions:

Title: '&8Search: {arg:0}'

Body:
  info:
    type: 'message'
    text: 'Player: {arg:0}, mode: {arg:1}'

Events:
  Open:
    - 'tell: &7Opening the menu for {arg:0}'

Buttons:
  confirm:
    display:
      material: EMERALD
      name: '&aConfirm {arg:0}'
    actions:
      left:
        - 'tell: &aArgument count: {arg_count}'
        - 'close'

reset and Menu Switching#

reset preserves the already resolved arguments of the current menu and re-renders it. open and force-open switch to a new menu, which resolves arguments again using that menu's own default and must settings.

---

Settings for Container Menus#

Chest, hopper, dispenser, dropper, furnace, blast furnace, smoker, and anvil menus currently support these Settings entries:

Settings:
  need_placeholder:
    - 'player'
    - 'vault'
  min_click_delay: 200

need_placeholder#

need_placeholder is the PlaceholderAPI prerequisite check shared by Container and Dialog menus. Each entry is a PlaceholderAPI expansion identifier, for example:

• %player_name% uses the player expansion
• %vault_eco_balance% uses the vault expansion

When the menu opens, KaMenu checks that PlaceholderAPI is enabled and that each listed expansion is registered. A failed check prevents rendering, avoiding incomplete displays or incorrect action conditions. Administrators receive a clickable prompt for missing expansions; regular players receive a dependency-missing message.

This setting does not scan every %...% variable in the menu automatically. Add the relevant expansion identifiers when a menu uses PlaceholderAPI variables. Menus that do not use PAPI expansions do not need need_placeholder.

min_click_delay#

min_click_delay limits the frequency of valid button clicks by the same player during the current Container menu session. The unit is milliseconds, matching TrMenu's Options.Min-Click-Delay:

Settings:
  min_click_delay: 200

• 0 or omitted: no click limit; this is the default
• 200: at least 200 milliseconds must pass between valid button clicks
• It applies only after the button is visible and resolves to at least one action
• Empty slots, hidden buttons, and buttons without actions do not consume the cooldown
• The timestamp belongs to the current menu session and resets after reopening, reset, or switching menus
• A blocked click runs no button action and does not change items or refresh the menu

For shops, reward claims, economy deductions, and point deductions, 150 to 300 milliseconds is a practical starting range. Menus that require rapid repeated interaction can keep the default 0.

Container menus do not use the Dialog-only can_escape, after_action, or lifetime settings. Configure Container closing, action transitions, and lifecycle behaviour through button actions and Events.Open / Events.Close.

---

can_escape#

Description#

Controls how the menu can be closed, determining whether players can press ESC to close it.

Values#

Value	Description
true (default)	Players can close the menu with ESC, triggering the corresponding bottom button actions
false	Players must click a specific button to close the menu; ESC is disabled

Configuration Example#

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

Use Cases#

Recommended: true (default)

• Regular menus where players should be able to exit freely
• Scenarios requiring flexible closing behaviour

Recommended: false

• Important confirmation menus (e.g., confirm deletion, confirm payment)
• Admin operation menus
• Scenarios where a player must choose an option
• Menus using Events.Tasks where close actions and task cancellation timing must be controlled explicitly

Button Actions Triggered by ESC#

When can_escape: true, pressing ESC triggers bottom button actions according to the button layout:

Menu Type	Action triggered by ESC
notice	The only button's actions
confirmation	The deny (cancel) button's actions
multi	The exit button's actions, when an exit button is configured

If a menu depends on close events or periodic task lifecycle, the button triggered by ESC is already the close path, so you usually do not need to add close there. Use close or force-close only when you want to close the menu manually from other branches.

Example configuration:

Settings:
  can_escape: true

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm ]'
    actions:
      - 'tell: &aYou chose to confirm'
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'tell: &cYou chose to cancel'
      - 'close'

---

lifetime#

lifetime - Menu lifetime limit#

lifetime is measured in seconds and defaults to 300 (5 minutes). It controls both the Paper callback lifetime and KaMenu's server-side menu timeout.

Spigot v1.7.0 also supports active close through lifetime, including Tasks, pagination, and Events.Close cleanup. An earlier close caused by client-only url: or copy: actions cannot notify the server immediately, but lifetime still provides fallback cleanup.

When the limit is reached, KaMenu:

1. Verifies that the player is still in the original menu session, so an old timeout cannot close a newer menu;
2. Actively closes the Dialog;
3. Stops the menu's Events.Tasks;
4. Clears repeat pagination state;
5. Runs Events.Close for timeout cleanup.

The timeout is a hard limit, so return inside Events.Close cannot prevent the Dialog from closing. Values less than or equal to 0 are invalid and fall back to 300 seconds.

Settings:
  lifetime: 300

All server callbacks remain single-use. Resetting or opening another menu creates new callbacks and restarts lifetime. The lifetime limit can close menus or waiting overlays that remain open for too long, but it does not replace proper close or refresh actions.

---

after_action#

Description#

Defines the client-side behaviour while waiting for the server to respond after a player clicks a button.

Background: Why Is This Parameter Needed?#

There is some latency in the network communication between the server and client:

• Normal conditions: Latency is only a few dozen milliseconds
• Poor network / high server load: Latency can reach 1 second or more

During this period, if the player performs operations in the game world (such as moving items or dropping items), it may cause the subsequent menu logic to become inconsistent with the actual state, leading to unexpected behaviour.

The after_action parameter declares a specific operation to be performed locally on the client, preventing the player from making invalid operations during the server response period and ensuring the integrity of the menu logic.

Values#

Value	Client Behaviour	Use Case
CLOSE (default)	Immediately closes the menu	Menus with no sub-menus or no follow-up behaviour to handle
NONE	No local action taken	Menus where the server explicitly closes, refreshes, or opens another menu
WAIT_FOR_RESPONSE	Displays an overlay screen while waiting for the server	Menus where the server explicitly closes, refreshes, or opens another menu after processing

Configuration Example#

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

Detailed Description#

1. CLOSE (Default)#

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

Advantages:

• Simple and straightforward
• Smooth user experience

Disadvantages:

• Cannot prevent invalid operations during network latency

Use Cases:

• Simple menus without sub-menus
• Scenarios with no follow-up behaviour to handle

Example:

Settings:
  after_action: CLOSE

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

2. NONE#

After clicking a button, the client takes no local action; all logic is controlled by the server.

Advantages:

• Maximum flexibility
• Server has complete control over menu behaviour
• Useful when closure, refresh, or navigation depends on server-side conditions

Disadvantages:

• Requires every button action path to explicitly close, refresh, or open a menu

Use Cases:

• Scenarios requiring complete server control over behaviour
• Scenarios where menu closure depends on conditions
• Scenarios where a click refreshes the current menu or opens another menu

Example:

Settings:
  after_action: NONE

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm ]'
    actions:
      - condition: '%player_balance% >= 1000'
        allow:
          - 'console: eco take %player_name% 1000'
          - 'tell: &aPayment successful!'
          - 'close'  # Manually close the menu
        deny:
          - 'tell: &cInsufficient balance!'
          - 'reset'  # Re-render the menu to avoid leaving an old dialog with no callback
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'close'

3. WAIT_FOR_RESPONSE#

After clicking a button, the client displays an overlay screen and waits for the server to respond before continuing.

Advantages:

• Completely prevents invalid operations during network latency
• Suitable for critical operations
• Stable user experience

Disadvantages:

• Must ensure every button action path eventually closes, refreshes, or opens a menu; otherwise the overlay can remain
• Adds one extra waiting step

Use Cases:

• Menus with sub-menus (a new menu will open automatically)
• Critical operations (trades, permission changes)
• Servers with unstable networks or low TPS
• Actions that must wait for server-side validation, refresh, or navigation

Example (with sub-menu):

Settings:
  after_action: WAIT_FOR_RESPONSE

Bottom:
  type: 'multi'
  buttons:
    open_sub_menu:
      text: '&a[ Open Sub-Menu ]'
      actions:
        - 'open: shop/weapons'  # Opens a sub-menu, which automatically removes the overlay
    exit:
      text: '&c[ Exit ]'
      actions:
        - 'close'

Example (no sub-menu — must explicitly finish):

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 and remove the overlay
  deny:
    text: '&c[ Cancel ]'
    actions:
      - 'close'  # Required: close the menu and remove the overlay

Example (validation fails but the menu should stay interactive):

Settings:
  after_action: WAIT_FOR_RESPONSE

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm ]'
    actions:
      - condition: 'isPosInt.$(amount)'
        allow:
          - 'tell: &aInput accepted'
          - 'close'
        deny:
          - 'toast: type=task;msg=Invalid;icon=barrier'
          - 'reset'  # Required: re-render the menu, clear the wait state, and rebuild callbacks

need_placeholder#

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 is shown, including the list of missing expansions and a clickable download button
• Regular players: A simplified prompt is shown

This feature ensures that placeholder variables in the menu work correctly, preventing display errors caused by missing expansions.

Configuration Format#

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

Values#

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

Configuration Examples#

Basic example:

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%
      &aOnline time: %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 with missing dependencies, they will see a message similar to:

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

Each expansion name (e.g., [player]) is clickable:

• Click expansion: Automatically runs /papi ecloud download <expansion-name>
• Hover: Shows the exact download command that will be executed

Regular Player Prompt#

Regular players see a simplified message:

§cThis menu is missing required dependencies. Please contact an administrator.

(Can be customised in the language file)

---

Complete Examples#

Example 1: Regular Shop Menu (Recommended Configuration)#

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

Settings:
  can_escape: true        # Allow ESC to exit
  after_action: NONE      # Controlled by 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#

Title: '&8» &c&lConfirm Deletion &8«'

Settings:
  can_escape: false                # Disable ESC
  after_action: WAIT_FOR_RESPONSE  # Prevent latency issues
  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: &aDeletion cancelled'
      - 'close'  # Required: close the menu

Example 3: Admin Operation Menu#

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

Settings:
  can_escape: false                # Disable ESC
  after_action: NONE               # Controlled by 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 Notice Menu#

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

Settings:
  can_escape: true        # Allow ESC
  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 great gaming environment.

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

---

Best Practices#

1. Recommended Default Configuration#

For most menus, the following configuration is recommended:

Settings:
  can_escape: true
  after_action: NONE

When using this configuration, every button action path must explicitly close, reset, or open another menu.

2. Critical Operations Configuration#

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

Settings:
  can_escape: false
  after_action: WAIT_FOR_RESPONSE

Important: When using WAIT_FOR_RESPONSE, ensure that every button action path eventually closes, resets, or opens another menu.

3. Conditional Close Configuration#

When the decision to close the menu depends on a condition:

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'
          - 'reset'  # Re-render when keeping the menu interactive

4. Network Considerations#

Servers with good network conditions:

• Use after_action: NONE for most scenarios
• Simple menus can use after_action: CLOSE
• With after_action: NONE, every button path must eventually close, reset, or open another menu to avoid leaving a cached dialog with no callback

Servers with unstable networks or low TPS:

• Use after_action: WAIT_FOR_RESPONSE for critical operations
• Ensure every button path eventually closes, resets, or opens another menu

---

Notes#

1. Choosing after_action

   • Use NONE by default for maximum flexibility
   • Use WAIT_FOR_RESPONSE for critical operations to ensure data consistency
   • NONE does not close automatically, and button callbacks are one-shot; every branch must explicitly close, reset, or open
   • WAIT_FOR_RESPONSE must also explicitly finish or rebuild interaction; every branch must close, reset, or open

2. Using can_escape

   • Keep true for regular menus to provide a better user experience
   • Set to false for important confirmation menus to force a choice
   • When using Events.Tasks or relying on Events.Close, let the ESC-mapped button own the close path; use close / force-close only for manual closure in other branches

3. pause parameter

   • Only effective in single-player mode; can be ignored for multiplayer servers
   • Defaults to false

4. Backward compatibility

   • Old configuration files without a Settings node use default values
   • It is recommended that all new configuration files include a Settings node

---

Related Documentation#

• Bottom Buttons (Bottom) — Learn about button action configuration
• Actions (Actions) — Learn about all available action types
• Events (Events) — Learn about the events system
• PlaceholderAPI — Learn about PlaceholderAPI integration