> For the complete documentation index, see [llms.txt](https://vulkan-technologies.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vulkan-technologies.gitbook.io/documentation/vulkan-menu/configuration/variables.md).

# Variables

Variables allow you to store and manipulate dynamic values within menus. They support mathematical operations and can be used to create interactive experiences like counters, calculators, or conditional displays.

## Defining Variables

Variables are defined in the menu configuration file under the `variables` section:

```yaml
variables:
  counter: 0
  price: 100.5
  player_level: 1
```

## Using Variables in Menu Items

Variables can be displayed in item names, lore, and other text fields using the `<variable-{name}>` syntax:

```yaml
items:
  display:
    slot: 4
    material: "paper"
    name: "<green>Counter: <variable-counter>"
    lore:
      - "<gray>Current value: <variable-counter>"
      - "<gray>Price: $<variable-price>"
```

## Mathematical Operations

Variables support mathematical expressions using the following syntax in actions:

```yaml
actions:
  - "[set-variable] counter (counter+1)"     # Increment by 1
  - "[set-variable] counter (counter-5)"     # Decrement by 5
  - "[set-variable] price (price*2)"         # Multiply by 2
  - "[set-variable] price (price/2)"         # Divide by 2
  - "[set-variable] total (price*counter)"   # Multiply variables
```

### Supported Operations

* Addition: `+`
* Subtraction: `-`
* Multiplication: `*`
* Division: `/`
* Parentheses for grouping: `()`

## Variable Actions

### Set Variable

Sets or updates a variable value:

```yaml
[set-variable] <variable-name> <value>
```

Examples:

```yaml
# Set to a static value
[set-variable] counter 10

# Set using mathematical expression
[set-variable] counter (counter+1)

# Set using another variable
[set-variable] backup_counter (counter)
```

### Remove Variable

Removes a variable from the menu:

```yaml
[remove-variable] <variable-name>
```

Example:

```yaml
[remove-variable] temporary_value
```

## Complete Example

Here's a complete example of a menu using variables to create a simple counter:

```yaml
title: <gradient:#521C0D:#FF9B45>Counter Menu
size: 9

variables:
  amount: 0

items:
  decrease_10:
    slot: 0
    material: "red_wool"
    name: "<red>-10"
    lore:
      - "<gray>Click to decrease by 10"
    actions:
      - "[set-variable] amount (amount-10)"
      - "[refresh]"
      
  decrease_1:
    slot: 1
    material: "orange_wool"
    name: "<gold>-1"
    lore:
      - "<gray>Click to decrease by 1"
    actions:
      - "[set-variable] amount (amount-1)"
      - "[refresh]"
      
  display:
    slot: 4
    material: "anvil"
    name: "<blue>Amount: <green><variable-amount>"
    lore:
      - "<gray>Current value: <variable-amount>"
      - ""
      - "<yellow>Click to show in chat"
    actions:
      - "[message] <gray>The amount is <green><variable-amount>"
      
  increase_1:
    slot: 7
    material: "lime_wool"
    name: "<green>+1"
    lore:
      - "<gray>Click to increase by 1"
    actions:
      - "[set-variable] amount (amount+1)"
      - "[refresh]"
      
  increase_10:
    slot: 8
    material: "green_wool"
    name: "<dark_green>+10"
    lore:
      - "<gray>Click to increase by 10"
    actions:
      - "[set-variable] amount (amount+10)"
      - "[refresh]"
      
  reset:
    slot: 5
    material: "barrier"
    name: "<red>Reset"
    lore:
      - "<gray>Click to reset counter"
    actions:
      - "[set-variable] amount 0"
      - "[refresh]"
```

## Variable Scope

Variables are scoped to the individual menu instance for each player. This means:

* Each player has their own set of variable values
* Variables persist while the menu is open
* Variables reset to their default values when the menu is reopened

## Tips and Best Practices

1. **Initialize variables**: Always define initial values in the `variables` section
2. **Use refresh**: After modifying variables, use `[refresh]` or `[refresh-slot]` to update the display
3. **Combine with requirements**: Use variables with compare requirements for conditional displays
4. **Mathematical expressions**: Complex calculations can be performed using parentheses for proper order of operations

## Integration with PlaceholderAPI

Variables can be combined with PlaceholderAPI placeholders:

```yaml
variables:
  player_level: 1

items:
  level_display:
    name: "<green>%player_name%'s Level: <variable-player_level>"
    actions:
      - "[set-variable] player_level (%player_level%)"
      - "[refresh]"
```

## Advanced Usage

### Conditional Actions Based on Variables

Combine variables with requirements for conditional logic:

```yaml
items:
  purchase:
    slot: 4
    material: "emerald"
    name: "<green>Purchase Item"
    actions:
      - "[message] <green>Purchase successful!"
    click-requirements:
      has_enough:
        requirement: "[compare] <variable-coins> >= 100"
        deny-actions:
          - "[message] <red>You need at least 100 coins!"
```

### Variable Persistence

While variables reset when a menu is closed, you can use the metadata system to persist values:

```yaml
# Save variable to metadata
actions:
  - "[set-meta] saved_counter <variable-counter>"

# Load from metadata on open
open-actions:
  - "[set-variable] counter %meta_saved_counter%"
```