> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/menu-configuration/menus/actions.md). # Actions and navigation Whenever a player clicks a button, moves their crosshair or cursor into or out of a region, or opens or closes a menu, the menu responds with actions. Everything from playing a click sound or sending a welcome message to running commands, switching pages, or starting animations is handled through actions. ## Basic syntax Actions that take arguments are written as `action: argument`, while actions without arguments are written by name alone (such as `close` or `back`). To run multiple steps on a single event, write them as a YAML list and the menu will execute them in order from top to bottom: ```yaml actions: right: - 'sound: UI_BUTTON_CLICK-1-1' - 'tell: &aWelcome, %player_name%!' - 'open: details' ``` In addition to `actions`, `deny`, `on-hover`, and `on-leave` inside interactive regions, actions can also be placed under top-level `events.open` and `events.close` in a menu. If you prefer combining a few short actions on a single line, join them with `_||_` or `&&&`, such as `'sound: UI_BUTTON_CLICK-1-1 &&& open: details'`. ## Messages and sounds Giving players immediate feedback is the most common use of actions. The actions below affect only the player who triggered the event (unless you attach a player target option): | Action | Example | Arguments and valid values | | ----------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tell` | `tell: &aWelcome!` | Sends plain text to chat. Supports `&` color codes, placeholders, and `\n` for multiple lines. (Aliases: `message`, `msg`, `talk`) | | `tellraw` | `tellraw: {"text":"Welcome!","color":"green"}` | Sends rich text to chat. Accepts standard Minecraft JSON text components or the `` shorthand syntax (supports `hover`, `suggest`, `command`/`execute`, and `url`/`open_url`). (Alias: `json`) | | `chat` | `chat: Hello everyone!` | Makes the current player send a chat message as themselves. (Aliases: `send`, `say`) | | `actionbar` | `actionbar: &aReady` | Displays a single line of text right above the hotbar. (Alias: `action`) | | `sound` | `sound: UI_BUTTON_CLICK-1-1` | Plays a sound in `sound-name` or `sound-name-volume-pitch` format. The sound can be a Bukkit enum name (`UI_BUTTON_CLICK`) or a vanilla namespaced key (`minecraft:ui.button.click`). Volume takes a non-negative decimal (default `1`), and pitch takes a decimal from `0` to `2` (default `1`). Separate multiple sounds with semicolons (`;`). | | `title` | See below | Displays a title and subtitle in the center of the screen. | | `bossbar` | See below | Displays a temporary BossBar banner at the top of the screen. | ### Titles and boss bars `title` and `bossbar` take space-separated arguments. When the title or boss bar text itself contains spaces, wrap that text in backticks (`` ` ``): ```yaml events: open: - 'title: `&aServer Menu` `&7Choose a feature` 10 40 10' - 'bossbar: `&aWelcome to the server` green solid 60' ``` * **`title` argument order**: `title subtitle [fade-in] [stay] [fade-out]`. The three timing values are optional integers in game ticks (at normal server speed, `20` ticks is roughly 1 second). When omitted, they default to `15`, `20`, and `15`. To show only a subtitle, pass an empty pair of backticks (\`\`) for the main title. * **`bossbar` argument order**: `text [color] [style] [duration]`. * **Color** (optional, defaults to `white`): `pink`, `blue`, `red`, `green`, `yellow`, `purple`, or `white`. * **Style** (optional, defaults to `solid`): `solid` for a single continuous bar, or segmented styles `segmented_6`, `segmented_10`, `segmented_12`, `segmented_20` (or shorthand `6`, `10`, `12`, `20`). * **Duration** (optional, defaults to `15`): A positive integer in game ticks before the bar hides automatically. ## Running commands Menus can run server commands as the player or through the console. A leading `/` is optional. To run multiple commands in sequence, either list them on separate lines or separate them with semicolons (`;`) on the same line. | Action | Sender | Example and description | | --------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `player` | Current player |

player: spawn
Runs the command using the player's own permissions. (Aliases: command, cmd, execute)

| | `console` | Server console |

console: minecraft:give %player\_name% minecraft:diamond 1
Executed by the server console regardless of the player's permissions. Use %player\_name% when the command needs the target player's name.

| | `op` | Temporary operator |

op: some-player-command
Temporarily grants the player OP status for the instant the command runs and restores their status immediately afterward. Useful for commands that must originate from a player without granting permanent permission.

| ## Menu navigation and flow control When your interface spans multiple pages (such as a main menu, shop category pages, and confirmation dialogs), each page is a separate menu file linked together with navigation actions. Switching pages within the same session keeps the screen anchor from when the menu was first opened, so the interface stays steady even if the player turns their head slightly. | Action | Example | Purpose and valid values | | ---------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open` | `open: welcome` | Opens the menu with the specified ID. Target IDs use lowercase letters, digits, underscores, or hyphens, and can be built dynamically with placeholders. (Aliases: `gui`, `menu`, `open-gui`) | | `open-app` | `open-app: myplugin:shop` | Opens an application view registered by a third-party plugin through the developer API. Application IDs always use `namespace:path` format. | | `back` | `back` | Takes no arguments. Returns to the previous page in the current session, or closes the menu if already on the first page. | | `close` | `close` | Takes no arguments. Closes the current menu and clears navigation history. (Aliases: `shut`, `force-close`, `silent-close`) | | `connect` | `connect: lobby` | Transfers the player to another backend server under your proxy (BungeeCord / Velocity). Pass the server name configured on the proxy. (Aliases: `bungee`, `server`) | | `return` | `return` | Takes no arguments. Stops the current action list immediately and skips any remaining actions below it. (Alias: `break`) | ### Passing page arguments Both `open` and `open-app` let you pass arguments after the target ID, separated by spaces. Wrap any argument that contains spaces in backticks (`` ` ``): ```yaml actions: right: 'open: world-detail survival `Survival World`' ``` Once `world-detail` opens, the target menu can read `survival` with `{0}` and `Survival World` with `{1}`. For more on page arguments, see [Placeholders and text formatting](/en/text-formatting/text-placeholders.md) and [Advanced actions](/en/menu-configuration/menus/advanced-actions.md). ## Dynamic refresh and animations If a click action updates a player's data or balance and you want text, images (including nodes set to `update: -1` without automatic polling), or tooltips on the current screen to update right away, use the `refresh` action (which shares the same underlying refresh pipeline as the developer API's `refresh`). You can also start and stop timeline animations on demand: * **`refresh`**: With no arguments (or `refresh: *`), refreshes all text nodes, image nodes (including image source and content), and any active hover tooltip in the current menu. * **`refresh: target-id`**: Refreshes one or more specific targets (separate multiple IDs with semicolons `;`). The target ID can be a frontend `text` or `image` node ID (immediately recalculating and redrawing it even if set to `update: -1`) or a backend region ID (immediately refreshing its tooltip if the player is currently pointing at that region). * **`animation: animation-id`**: Plays a timeline animation bound to the current menu (Aliases: `animate`, `play-animation`). * **`stop-animation: animation-id`**: Stops the specified animation and restores elements to their initial state (Alias: `cancel-animation`). Placing play and stop actions in a region's `on-hover` and `on-leave` gives you smooth hover animations. ## Delays, probability, inline conditions, and target players You can append curly-brace options `{...}` to the end of any single action string to control its timing, probability, condition, or target players: | Option | Example | Value and effect | | ---------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{delay=ticks}` | `tell: &aHello {delay=20}` | Delays this single action by the given number of game ticks, as a non-negative integer (Alias: `wait`). | | `{chance=probability}` | `give-money: 10 {chance=0.5}` | Runs this action with the given probability, as a decimal between `0` and `1` (`0.5` is a 50% chance; aliases: `rate`, `rand`, `random`). | | `{condition=expr}` | `tell: &aHello VIP {condition=perm my.vip}` | Runs this action only when the condition expression passes (Alias: `requirement`). See [Conditions](/en/menu-configuration/menus/conditions.md) for syntax. | | `{players}` | `tell: &eServer broadcast {players}` | Runs this action for all currently online players. | | `{players=expr}` | `tell: &eNotice {players=perm my.staff}` | Filters online players by the condition and runs this action for everyone who matches. | ### Standalone `delay` vs. inline `{delay=...}` In addition to attaching `{delay=20}` to the end of a single action, you can also put `delay: ticks` on its own line in an action list (placeholders are supported): ```yaml events: open: - 'tell: &aMenu opened.' - 'delay: 20' - 'tell: &7Message shown one second later.' - 'delay: 20' - 'tell: &7Message shown two seconds later.' ``` * **Standalone `delay: 20`**: Pushes back **all** actions listed after it by 20 ticks, and multiple standalone `delay` lines accumulate. * **Inline `{delay=20}`**: Delays only that specific line without affecting when the next line runs. When a player closes the menu or navigates to another menu page, any pending delayed actions from the previous page are canceled automatically so they do not fire after the player has left. ### Execution order after navigation actions In an action list, `open`, `back`, and `close` update the current session state, while any immediate actions listed right after them in the same list still finish running (for example, writing `close` followed by `tell: &7Goodbye` still sends the message). If you want to stop the action list completely at a specific branch, add a `return` line. Once you are comfortable with these core actions, continue to [Advanced actions](/en/menu-configuration/menus/advanced-actions.md) to work with custom variables, balances, inventory items, and chat input capture. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.myarc.icu/en/menu-configuration/menus/actions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.