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

# Advanced actions

This page covers stored values, menu arguments, balances, items and chat input. See [Actions and navigation](/arcmenu-wiki/menu-configuration/menus/actions.md) for placement and basic syntax.

These actions are available on Paper, Folia, Leaf and similar servers. Spigot does not support them. Balance and points actions require their respective plugins; the other examples need no additional plugins.

## Stored values

Each value has a key and content. For example, `selected-world` is the key and `survival` is its content. Write values with `action-name: key value`. Writing the same key again replaces its content.

| Scope                   | Write action      | Remove action        | Read with          | Retention                                                         |
| ----------------------- | ----------------- | -------------------- | ------------------ | ----------------------------------------------------------------- |
| Temporary player values | `set-meta`        | `remove-meta`        | `{meta:key}`       | Separate for each player; not retained after the plugin restarts. |
| Saved player values     | `set-data`        | `remove-data`        | `{data:key}`       | Saved per player and retained across normal restarts.             |
| Shared server values    | `set-global-data` | `remove-global-data` | `{globaldata:key}` | Shared by all players and retained across normal restarts.        |

Closing a menu alone does not clear temporary values. Use them for temporary selections passed between menus. Use `set-data` for player preferences that should be saved.

```yaml
backend:
  preference-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'set-meta: selected-world survival'
        - 'set-data: preferred-world survival'
        - 'tell: &aSaved world: {data:preferred-world}'
      shift-right:
        - 'remove-data: preferred-world'
        - 'tell: &7Preference removed.'
```

This fragment saves a world preference. It does not teleport the player or create a world. To display the updated value in frontend text, use `refresh` after writing it or configure periodic updates for the text element.

### Content and reading

Everything after the key is the value and may contain spaces, as in `set-data: display-name Survival World`. These actions store text. `set-data: visits 1` does not mean “increment visits by one.”

Semicolons separate multiple key-value entries in one write action. A semicolon inside a value is also treated as a separator, so avoid it in plain text values.

Reading an unset value produces `null`. ArcMenu provides these placeholders without PlaceholderAPI. See [Placeholders and text formatting](/arcmenu-wiki/text-formatting/text-placeholders.md) for the full reference.

### Removal patterns

Removal actions match keys using regular expressions. For example:

| Syntax                             | Removes                                                                |
| ---------------------------------- | ---------------------------------------------------------------------- |
| `remove-meta: selected-world`      | The current player's temporary `selected-world` value.                 |
| `remove-data: preference-.*`       | The current player's saved values whose keys begin with `preference-`. |
| `remove-global-data: event-status` | The shared `event-status` value.                                       |

Patterns match the entire key. Use letters, digits, underscores and hyphens for ordinary keys to avoid accidentally treating regular expression characters as part of an exact key. Removing a shared value affects what all players read.

## Menu arguments

Arguments passed after `open` are available to the destination menu. `set-args` replaces the current player's complete argument list; `clear-args` clears it. Neither action switches menus.

```yaml
backend:
  argument-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'set-args: survival `Survival World`'
        - 'tell: &aWorld ID: {0}'
        - 'tell: &7Display name: {1}'
      shift-right: clear-args
```

Arguments are numbered from `0`: `{0}` is `survival` and `{1}` is `Survival World` in this example. Backticks group content containing spaces into a single argument. `set-args` replaces existing arguments rather than appending to them.

Arguments belong to the current navigation flow and are unsuitable for lasting preferences. Use saved player values for content that must survive a restart.

## Balances and points

| Operation     | Money action     | Points action     |
| ------------- | ---------------- | ----------------- |
| Add           | `give-money: 10` | `give-points: 10` |
| Deduct        | `take-money: 10` | `take-points: 10` |
| Set the total | `set-money: 100` | `set-points: 100` |

Money actions require Vault and a compatible economy plugin. Points actions require PlayerPoints. See [Platform and plugin compatibility](/arcmenu-wiki/configuration-and-administration/compatibility.md) for prerequisites.

Amounts must be greater than `0`. Money may use decimals; use whole numbers for points. `set-money` and `set-points` set the total rather than adding to it. These actions cannot set a total to `0`.

```yaml
backend:
  reward-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'give-money: 10'
```

This fragment attempts to add `10` to the player's balance on every right-click. It has no claim limit. A one-time reward needs separately configured records and conditions.

A failed deduction does not automatically prevent later item rewards or commands. Check the balance and purchase eligibility first and configure a denial message. When payment and delivery must succeed together as one transaction, use a command from a plugin that provides transaction handling.

## Item operations

### Giving and taking items

`give-item` gives items; `take-item` removes matching items from the player's inventory storage slots. Both use `property:value`, with commas separating properties:

```yaml
backend:
  item-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'give-item: material:DIAMOND,amount:1,name:&bMenu Reward'
      shift-right:
        - 'take-item: material:DIAMOND,amount:1,name:&bMenu Reward'
```

A normal right-click gives one named diamond. Shift+right-click removes one diamond matching the name condition. This example has no purchase checks, cooldown or claim limit.

| Property     | Purpose                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `material`   | Item material, such as `DIAMOND` or `PLAYER_HEAD`.                                                      |
| `amount`     | A whole number from `1` to `99`; defaults to `1`.                                                       |
| `name`       | Sets the display name when giving; matches names containing the text when taking. Supports color codes. |
| `lore`       | Sets description lines when giving, separated by `\n`; matches a line containing the text when taking.  |
| `model-data` | An integer custom model data value.                                                                     |
| `data`       | Damage on a damageable item; `0` means undamaged.                                                       |
| `head`       | The player name associated with a player head. Use with `material:PLAYER_HEAD` when giving.             |

Specify `material` when giving items. When taking items, all properties other than `amount` determine which items match. The required quantity may be removed from several matching stacks.

Separate several item specifications with semicolons, for example `give-item: material:DIAMOND,amount:1;material:EMERALD,amount:2`. Commas and semicolons inside property values are also treated as separators, so avoid them in names and lore.

Items that do not fit in the inventory are dropped at the player's location. Taking items checks only storage slots, excluding worn armor and the offhand.

{% hint style="warning" %}
If `take-item` finds too few items, any items already removed are not restored, and later actions do not automatically stop. Do not use it alone to check eligibility for an exchange. Check quantities and conditions first, or use a plugin that handles the complete transaction.
{% endhint %}

### Repairing and enchanting

`repair-item: hand` repairs the main-hand item. `enchant-item: hand minecraft:unbreaking 3` adds Unbreaking III to it.

Both actions accept these item targets:

| Target                                      | Selection                                            |
| ------------------------------------------- | ---------------------------------------------------- |
| `hand`, `mainhand`                          | Main-hand item.                                      |
| `offhand`                                   | Offhand item.                                        |
| `armor`                                     | Worn armor.                                          |
| `helmet`, `chestplate`, `leggings`, `boots` | The corresponding equipment slot.                    |
| `all`, `inv`                                | Inventory contents, including armor and the offhand. |

Enchanting takes a target, enchantment name and level, in that order. Use a positive whole number for the level or a range such as `enchant-item: hand minecraft:unbreaking 1-3`, which randomly chooses a level from one to three. This action allows levels and item combinations beyond normal enchanting restrictions; the menu author should choose the permitted settings.

`reload-inventory` refreshes the player's inventory display. It does not reload menu files, replenish items or restore removed items.

## Chat input

`catcher` receives a player's next chat input. It requires nested configuration and cannot be written as a plain `catcher: text` action. Only `type: CHAT` is supported; sign, anvil and book input screens are unavailable.

The hierarchy is **click type → action list → `catcher` → stage name → stage properties**.

```yaml
backend:
  input-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - catcher:
            nickname:
              type: CHAT
              start:
                - 'tell: &eEnter a nickname in chat, or type cancel.'
              cancel:
                - 'tell: &7Input cancelled.'
              end:
                - 'set-data: nickname {meta:input-nickname}'
                - 'tell: &aNickname saved: {data:nickname}'
```

### Stage properties

| Property | Purpose                                              |
| -------- | ---------------------------------------------------- |
| `type`   | Input method: `CHAT`, also the default when omitted. |
| `start`  | Actions run when the stage starts waiting for input. |
| `cancel` | Actions run when the player cancels input.           |
| `end`    | Actions run after normal input is received.          |

`nickname` names the stage in this example. Define several stages under `catcher` to receive inputs in their written order. Each stage has its own prompts and processing actions.

### Input content and cancellation

Read the latest input with `{meta:input}`. Read a particular stage's input with `{meta:input-stage-name}`, such as `{meta:input-nickname}` here. The message is used as menu input and is not broadcast as normal chat.

Entering `cancel`, `quit`, `end` or `q` cancels the flow and runs the current stage's `cancel` actions. These words are case-insensitive. Closing or switching the menu ends the wait without treating it as submission of a cancellation word.

Starting a new `catcher` clears previous temporary `input` and `input-...` values. Copy any input you need to keep to your own key in `end`, as the example does with `nickname`.

### Requesting input again

Running `retype` in `end` restarts the current stage and runs `start` again. Combine it with conditions to explain an invalid response and request another entry.

`retype` does not immediately stop subsequent actions. Put saving valid results and requesting another entry in separate conditional branches. `return` ends input processing; do not place it immediately after `retype` as part of a retry sequence.

Treat chat input as data. Before using it as an argument to a `console` or `op` command, restrict it to explicitly allowed content.

## Checking and loading

Run `/arcmenu validate` and `/arcmenu reload` after editing, then open the menu normally to check stored values, item quantities and chat input. Verify actual balance and points changes on a server where the corresponding plugins work.

Configuration validation checks action structure. It does not replace transaction conditions or verify every item, enchantment and third-party argument. See [Conditions](/arcmenu-wiki/menu-configuration/menus/conditions.md) for condition configuration.