> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/menu-configuration/menus/actions.md).

# Actions and navigation

Actions define what happens when a player clicks a button, opens a menu or closes it. This page covers action syntax, messages and commands, navigation, execution order and action options. See [Backend regions and click events](/arcmenu-wiki/menu-configuration/menus/backend.md) for region and click settings.

## Placement and syntax

Actions can be configured in these locations:

| Location                                         | When it runs                               |
| ------------------------------------------------ | ------------------------------------------ |
| `backend` → region name → `actions` → click type | When the specified region is clicked.      |
| `backend` → region name → `deny`                 | When a click fails the region's condition. |
| `events` → `open`                                | When the menu opens.                       |
| `events` → `close`                               | When the menu closes.                      |

An action with an argument uses `action-name: argument`; an action without arguments uses its name alone. Write one action directly or use a YAML list for several actions.

```yaml
backend:
  notice-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'sound: UI_BUTTON_CLICK-1-1'
        - 'tell: &aWelcome!'
      shift-right: close
```

This is a menu fragment. Add it to an existing menu alongside its visible content. Quote action strings, especially those containing colons, color codes or special characters.

Open and close events use the same syntax:

```yaml
events:
  open:
    - 'sound: UI_BUTTON_CLICK-1-1'
  close:
    - 'tell: &7Menu closed.'
```

## Messages and sounds

| Action      | Example                                        | Purpose                                            | Spigot       |
| ----------- | ---------------------------------------------- | -------------------------------------------------- | ------------ |
| `tell`      | `tell: &aWelcome!`                             | Sends a chat message to the player.                | Supported.   |
| `tellraw`   | `tellraw: {"text":"Welcome!","color":"green"}` | Sends formatted chat text, including JSON text.    | Unsupported. |
| `chat`      | `chat: Hello everyone!`                        | Sends a chat message as the player.                | Unsupported. |
| `actionbar` | `actionbar: &aReady`                           | Displays text above the hotbar.                    | Unsupported. |
| `title`     | See below.                                     | Displays a screen title and subtitle.              | Unsupported. |
| `bossbar`   | See below.                                     | Displays a temporary bar at the top of the screen. | Unsupported. |
| `sound`     | `sound: UI_BUTTON_CLICK-1-1`                   | Plays a sound for the player.                      | Supported.   |

`tell` sends a message to the current player; `chat` sends a message from that player to chat.

### Sound arguments

`sound` uses `sound-name-volume-pitch`. The example above uses `1` for both volume and pitch. When only a sound name is supplied, both default to `1`. The sound must exist in the server's Minecraft version.

### Title arguments

`title` takes the main title, subtitle, fade-in time, stay time and fade-out time, in that order. Enclose titles containing spaces in backticks:

```yaml
events:
  open:
    - 'title: `&aServer menu` `&7Choose an option` 10 40 10'
```

Times are in game ticks; at normal server speed, `20` ticks are approximately `1` second. Omitted times default to `15`, `20` and `15` ticks respectively.

### Boss bar arguments

`bossbar` takes text, color, style and display time:

```yaml
events:
  open:
    - 'bossbar: `&aWelcome to the server` green solid 60'
```

Colors are `pink`, `blue`, `red`, `green`, `yellow`, `purple` and `white`. Styles are `solid`, `segmented_6`, `segmented_10`, `segmented_12` and `segmented_20`. Defaults are `white`, `solid` and `15` ticks.

## Running commands

| Action    | Command sender                                              | Spigot       |
| --------- | ----------------------------------------------------------- | ------------ |
| `player`  | The player using the menu, with their existing permissions. | Supported.   |
| `console` | The server console.                                         | Supported.   |
| `op`      | The player, with administrator permissions for the command. | Unsupported. |

Write the command after the action name, usually without the leading `/`.

```yaml
backend:
  spawn-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'player: spawn'
```

This example requires the server to provide `/spawn` and the player to have permission to use it. ArcMenu does not create commands belonging to other plugins.

Use `console` and `op` for commands chosen by the menu author. Console commands do not automatically target the player who clicked. Supply a player argument when the command requires one, for example `console: minecraft:give %player_name% minecraft:diamond 1`.

## Menu navigation

| Action   | Syntax          | Purpose                                                                                                    |
| -------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
| `open`   | `open: welcome` | Opens the specified menu.                                                                                  |
| `back`   | `back`          | Returns to the previous menu in navigation history, or closes the current menu if no previous menu exists. |
| `close`  | `close`         | Closes the current menu.                                                                                   |
| `return` | `return`        | Ends the current action flow without closing the menu.                                                     |

All four actions support Spigot. `open` uses the target menu's top-level `id`, rather than its filename or a button name. The target must be loaded, and the player must meet its permission requirements.

```yaml
backend:
  welcome-area:
    x: 0
    y: 20
    width: 80
    height: 18
    actions:
      right:
        - 'sound: UI_BUTTON_CLICK-1-1'
        - 'open: welcome'
  back-area:
    x: 0
    y: -20
    width: 80
    height: 18
    actions:
      right: back
```

This example requires the `welcome` menu from [Your first menu](/arcmenu-wiki/getting-started/first-menu.md) to be created and loaded. Configure the navigation buttons' visible content in `frontend` as well.

Use a separate menu for each page and navigate with `open`. Do not use `open: welcome:2` to represent a second page.

### Navigation arguments and extension applications

Paper, Folia, Leaf and similar servers allow arguments after the menu ID, such as `open: welcome survival`. Enclose a single argument containing spaces in backticks, as in `` open: welcome `Survival World` `` . Arguments are available to the destination menu's placeholders; they do not create text or buttons automatically.

These servers also support `open-app: namespace:application-id` for ArcMenu applications supplied by other plugins. The providing plugin must be installed and offer the application. Use its documentation for the application ID and arguments.

On Spigot, `open` accepts only a fixed menu ID. Arguments, placeholder-based targets and extension applications are unsupported.

### Connecting to another server

`connect: lobby` requests a connection to the server named `lobby` in the proxy configuration. It requires a proxy connection that supports BungeeCord connection messages, and the destination name must match the proxy configuration. This action is available only on Paper-family servers and does not configure the proxy for you.

## Execution order and refreshing

Action lists are normally processed in their written order. Place messages, sounds and commands first, followed by `open`, `back` or `close` at the end of the list.

* On Spigot, successfully opening a menu, or running `back`, `close` or `return`, stops subsequent actions.
* On Paper-family servers, immediate actions remaining in the same list may still run after navigation or closing, but subsequent matching click groups or conditional branches stop processing.
* Use `return` to explicitly end the current action flow. It differs from `back`, which returns to a previous menu.

Avoid opening a menu from its own open event or closing it again from its close event, as this can repeatedly trigger events.

On Paper-family servers, `refresh` updates the current menu's dynamic content without reopening it. `refresh: title` can update a text element named `title`; a currently pointed region's name can refresh its tooltip text. This action does not read changed configuration from disk. Use `/arcmenu reload` after editing menu files.

`animation: animation-id` plays a track bound to the current menu, and `stop-animation: animation-id` stops it. See [Animation timelines and tracks](/arcmenu-wiki/feature-configuration/animations.md) for configuration. Spigot does not support refresh or animation actions.

## Action options

Options are written inside an individual action string. They are separate from region properties.

| Option                               | Purpose                                                                    | Spigot       |
| ------------------------------------ | -------------------------------------------------------------------------- | ------------ |
| `{chance=0.5}`                       | Runs this action with a `50%` probability; accepts values from `0` to `1`. | Supported.   |
| `{condition=perm myserver.menu.vip}` | Runs this action only when its condition passes.                           | Supported.   |
| `{delay=20}`                         | Runs this action after `20` game ticks.                                    | Unsupported. |
| `{players}`                          | Runs this action for every online player.                                  | Unsupported. |
| `{players=perm myserver.notice}`     | Runs this action for online players who meet the condition.                | Unsupported. |

A failed chance or condition skips only that action. It does not automatically run the region's `deny` actions. See [Conditions](/arcmenu-wiki/menu-configuration/menus/conditions.md) for more detailed settings.

### Delaying one action or the rest of a list

`{delay=20}` delays only the action containing it. The next action does not wait. To delay all subsequent actions in the list, use a separate `delay` action:

```yaml
events:
  open:
    - 'tell: &aMenu opened.'
    - 'delay: 20'
    - 'tell: &7One second later.'
    - 'delay: 20'
    - 'tell: &7Two seconds later.'
```

Separate `delay` actions accumulate. Closing or switching the menu while waiting prevents the old menu's pending delayed actions from running. Do not put required operations in delayed actions after closing the menu.

### Action recipients

By default, an action targets the player who triggered the menu interaction. `{players}` and `{players=...}` change the recipients. Player placeholders in the action text still refer to the player who originally triggered it.

For example, `tell: &aA player opened the menu. {players}` sends a message to every online player. Using `{players=perm myserver.notice}` sends it only to players with that permission.

## Checking and further configuration

Run `/arcmenu validate` and `/arcmenu reload` after editing, then open the menu normally to check command permissions, destinations, return paths and delayed actions. Preview mode does not execute interactive actions.

See [Advanced actions](/arcmenu-wiki/menu-configuration/menus/advanced-actions.md) for data, argument changes, balances, items and chat input. See [Platform and plugin compatibility](/arcmenu-wiki/configuration-and-administration/compatibility.md) for integration requirements.