> 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/advanced-actions.md).

# Advanced actions

Beyond sending messages, running commands, and switching pages, menus often need to remember which option a player selected, charge currency and deliver items, or ask a player to type something in chat. This page covers the actions for storing data, handling balances and points, manipulating inventory items, and capturing chat input. You place them inside button click lists or menu events using the same basic syntax described in [Actions and navigation](/en/menu-configuration/menus/actions.md).

## Saving and removing data

ArcMenu provides three built-in data scopes so you can store and read state in menus without installing a separate variable plugin:

| Data type               | Write action      | Remove action        | Read placeholder    | Scope and lifetime                                                                                                                     |
| ----------------------- | ----------------- | -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Temporary player data   | `set-meta`        | `remove-meta`        | `{meta:name}`       | Kept in memory. Ideal for temporary state such as current purchase quantity or selected category tab (aliases: `set-temp`, `set-var`). |
| Persistent player data  | `set-data`        | `remove-data`        | `{data:name}`       | Bound to the player and saved persistently across normal server restarts. Ideal for personal preferences or reward claim records.      |
| Server-wide shared data | `set-global-data` | `remove-global-data` | `{globaldata:name}` | Shared across all players and saved persistently. Ideal for server event toggles or public counters (alias: `set-g-data`).             |

### Writing data

Write actions use the format `action: key value`, with a space separating the key and value. Values are stored as text and can contain spaces. To write multiple key-value pairs in a single action, separate them with semicolons (`;`). Writing to an existing key overwrites the previous value, and reading a key that has never been set returns `null`.

```yaml
actions:
  right:
    - 'set-data: preferred-world survival'
    - 'tell: &aSaved your preferred world: {data:preferred-world}'
    - refresh
  shift-right:
    - 'remove-data: preferred-world'
```

To save the result of a calculation into a variable, wrap the formula in `{math: ...}`:

```yaml
- 'set-meta: total {math: {meta:input-x} * 24}'
```

Writing `set-meta: total 3 * 24` directly stores the literal string `3 * 24` instead of calculating `72`.

### Removing data

Remove actions accept a **full-match regular expression**. Passing a fixed name such as `remove-data: preferred-world` deletes that specific entry, while passing a regex pattern such as `remove-data: preference-.*` clears all saved data for the current player whose keys start with `preference-`. You can also separate multiple patterns with semicolons (`;`).

## Modifying current menu arguments

In addition to passing arguments when opening a menu with `open: menu-id arg1 arg2`, you can replace or clear the argument list directly within the current page:

```yaml
actions:
  right:
    - 'set-args: survival `Survival World`'
    - 'tell: &aWorld ID: {0}, Name: {1}'
  shift-right: clear-args
```

* **`set-args: argument-list`** (aliases: `set-arg`, `set-arguments`): Replaces the current page's arguments with a new list. Separate multiple arguments with spaces, and wrap any single argument that contains spaces in backticks (`` ` ``). Once set, read them with numbered placeholders such as `{0}` and `{1}`.
* **`clear-args`** (aliases: `clear-arg`, `del-args`): Takes no parameters and clears all menu arguments on the current page.

## Balances and points

When Vault (with any economy plugin) or PlayerPoints is installed on the server, you can add, deduct, or set a player's currency balance or points directly with built-in actions:

| Operation    | Vault balance action                                     | PlayerPoints action                                         | Parameter requirements                                                                                          |
| ------------ | -------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Add          | `give-money` (aliases: `add-money`, `deposit-money`)     | `give-points` (aliases: `add-points`, `deposit-points`)     | Number or formula greater than `0`. Balances support decimals; points require integers.                         |
| Deduct       | `take-money` (aliases: `remove-money`, `withdraw-money`) | `take-points` (aliases: `remove-points`, `withdraw-points`) | Number or formula greater than `0`. Fails and halts subsequent actions if the player's balance is insufficient. |
| Set to value | `set-money` (alias: `modify-money`)                      | `set-points` (alias: `modify-points`)                       | Number or formula greater than `0`.                                                                             |

All six actions accept [math expressions](/en/menu-configuration/menus/math-expressions.md) directly in their parameter without wrapping them in `{math: ...}`:

```yaml
actions:
  right:
    - 'take-money: round({meta:input-x} * 24 * 0.95, 2)'
    - 'give-item: material:DIAMOND,amount:{meta:input-x}'
```

Points require an integer result. If your formula includes decimal discounts, wrap it in `floor(...)`, `ceil(...)`, or `round(...)` to specify how it should be rounded.

If a player does not have enough funds, the economy plugin is unavailable, or the math expression is invalid, the action fails and automatically stops the current action list (acting like `return`). Any `give-item` delivery action placed after the deduction will not run. Actions that already ran **before** the deduction are not rolled back, so place `take-money` or `take-points` before delivery actions in shop purchase flows, or check the player's balance beforehand with [Conditions](/en/menu-configuration/menus/conditions.md).

## Inventory item operations

### Giving and taking items

`give-item` (alias: `add-item`) and `take-item` (alias: `remove-item`) add or remove vanilla and custom-model items from a player's inventory:

```yaml
actions:
  right:
    - 'give-item: material:DIAMOND,amount:1,name:&bMenu Reward'
  shift-right:
    - 'take-item: material:DIAMOND,amount:1,name:&bMenu Reward'
```

Separate properties for a single item with commas (`,`), and join each property name and value with a colon (`:`) or equals sign (`=`). Underscores (`_`) and hyphens (`-`) in property names are interchangeable. To operate on multiple items in one action, separate each item specification with a semicolon (`;`). In `take-item`, you can prefix any property name except `amount` with an exclamation mark (`!`) to invert the match (for example, `!material:DIRT` matches items whose material is not dirt). Available properties are:

| Property key and aliases                                            | Required / Optional | Values and matching behavior                                                                                                                                                                                                    |
| ------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `material` (aliases: `materials`, `mat`, `mats`)                    | Optional            | Vanilla item material name (such as `DIAMOND` or `PLAYER_HEAD`). Defaults to `BEDROCK` in `give-item` if omitted; in `take-item`, omitting it leaves the material unrestricted and matches by the other properties you specify. |
| `amount` (aliases: `amounts`, `amt`, `amts`)                        | Optional            | Quantity as an integer from `1` to `99`. Defaults to `1` if omitted.                                                                                                                                                            |
| `name` (alias: `names`)                                             | Optional            | Item display name, supporting `&` color codes. Sets the item name when giving; when taking, matches any inventory item whose name **contains** this text (case-insensitive after translating `&` color codes).                  |
| `lore` (alias: `lores`)                                             | Optional            | Item lore text. Use `\n` to split into multiple lines when giving; when taking, matches if **any line** of the item's lore contains the specified substring (case-insensitive after translating `&` color codes).               |
| `model-data` (aliases: `model-datas`, `modeldata`, `modeldatas`)    | Optional            | CustomModelData integer value. When taking, requires the item to have CustomModelData with the exact same value.                                                                                                                |
| `data` (alias: `datas`)                                             | Optional            | Integer item damage (durability consumed). Values below `0` are treated as `0` when giving; when taking, requires the item's damage value to match.                                                                             |
| `head` (aliases: `heads`, `skull`, `skulls`, `texture`, `textures`) | Optional            | For player heads (`PLAYER_HEAD`), sets the skull owner when giving or matches the skull owner's player name (case-insensitive) when taking.                                                                                     |

When giving items, any items that do not fit in a full inventory drop at the player's feet. When taking items, ArcMenu scans the player's storage slots in order (excluding armor slots and the offhand) and deducts from matching stacks. If the total number of matching items in the inventory is less than the requested amount, items already deducted are not rolled back; the player receives an insufficient-items message and the remaining actions in the list continue to run. If subsequent delivery steps should only run when the player has enough items, check their inventory first using [Conditions](/en/menu-configuration/menus/conditions.md).

### Repairing, enchanting, and refreshing the inventory

* **`repair-item: slot`** (alias: `repair-items`): Fully restores the durability of damageable items in the specified slot. Separate multiple target slots with semicolons (`;`), such as `repair-item: hand;armor`.
* **`enchant-item: slot enchantment-id level`** (alias: `enchant-items`): Adds an enchantment to the item in the specified slot. The slot, enchantment ID, and level are **all required** and can be separated by spaces or commas (`,`). Separate multiple enchantment operations in one action with semicolons (`;`). Enchantment IDs accept vanilla names (such as `minecraft:unbreaking` or `unbreaking`). The level must be a positive integer greater than or equal to `1`, or a positive integer range such as `1-3` to pick a random level.
* **`reload-inventory`** (alias: `reload-inv`): Takes no parameters and actively synchronizes the player's inventory display to the client.

The **slot** parameter for `repair-item` and `enchant-item` accepts:

* Hands and armor: `hand` / `mainhand` (main hand), `offhand` (offhand), `helmet` (helmet), `chestplate` (chestplate), `leggings` (leggings), `boots` (boots), and `armor` (all four armor pieces).
* Bulk scopes: `all` / `inv` (all non-empty items in the player's inventory).
* Specific slot index: A numeric slot index (for example, `0` for the first hotbar slot).

## Chat input capture (`catcher`)

Alongside the in-menu [Arcitx text input component](/en/feature-configuration/arcitx.md), you can use the structured `catcher` action to temporarily hide the menu and guide the player through entering one or more lines of text in chat (such as a custom nickname, title, or transfer note).

Write `catcher` as a YAML map containing one or more input stages, which run in the order they are written:

```yaml
actions:
  right:
    - catcher:
        nickname:
          type: CHAT
          start:
            - 'tell: &eEnter your new nickname in chat, or type cancel to stop.'
          cancel:
            - 'tell: &7Nickname change cancelled.'
          end:
            - 'set-data: nickname {meta:input-nickname}'
            - 'tell: &aNickname saved as: {data:nickname}'
```

Each stage (`nickname` is the custom stage name in the example above) supports these fields:

* **`type`**: Set to `CHAT` (also defaults to `CHAT` if omitted).
* **`start`** (or `before`): Action list executed when entering this input stage, typically used to prompt the player.
* **`cancel`**: Action list executed if the player cancels input. Players can type `cancel`, `quit`, `end`, or `q` (case-insensitive) in chat to cancel.
* **`end`** (or `after`): Action list executed after the player sends normal chat text (supports conditional action branches).

### Reading captured input and asking to re-enter

Chat messages sent while `catcher` is active are intercepted by the menu and are not broadcast to public chat. Captured text is automatically stored in the player's temporary data (`meta`):

* **`{meta:input}`**: Reads the text entered in the stage that just finished.
* **`{meta:input-stage-name}`**: Reads the text entered in a specific stage (for example, `{meta:input-nickname}`). When you define multiple sequential stages under `catcher` (such as entering a recipient first and an amount second), you can read the values from all earlier stages together inside the final stage's `end` list.
* **`retype`** (aliases: `repeat`, `re-enter`): Used inside the `end` action list. If a condition in `end` finds that the player's input is invalid, running `retype` keeps the player in the current stage to try again and re-runs the `start` prompt.


---

# 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/advanced-actions.md?ask=<question>&goal=<user_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.