# Setting up and using Variables

{% hint style="warning" %}
BattlePass 4.6.2 and AdvancedJobs 1.4.1 removed MaterialData from items in variables (`:0`, `:1` at the end of item's type).
{% endhint %}

The core of actions is the variable system. The basis of this system is that it is a filter. If the variable is set to `none`, there is no filter. If it is set, if whatever the variable is entered as when a user performs an action matches the variable, it will progress.

Recently, we've also added sub variables which can make this system a bit more confusing. Here are some examples for different action types with and without sub variables.

Every action has the global sub variables listed below:

```yml
variable:
  root: none
  holding:
    item: diamond_sword
    name: 'IDK some name'
    amount: 1
    model: 0 # Custom Model Data (for resource packs)
```

Every sub-variable is optional. If you don't specify it, it won't be filtered for. Therefore, you can just use `holding.item` if you wish, or just `holding.amount`.

## Basic Examples

**Without Sub-Variables:**

The following two actions function in the same manner, they're just two ways of formatting them.

`block-break`

```yml
variable:
  root: stone
```

`block-break`

```yml
variable: stone
```

Some more random examples: `throw-projectile`

```yml
variable: SNOWBALL
```

**With Sub-Variables:**

`block-break`

```yml
variable:
  root: diamond_block
  holding:
    item: golden_pickaxe
```

`enchant-all`

```yml
variable:
  root: SOUL_SPEED
  item: diamond_sword
  level: 3
```

This action is to enchant an item with soul speed 3 using an anvil.

**With Multiple Variables:**

`block-break`

```yml
variable: diamond_block OR gold_block OR iron_block
#This will progress the action if any of the blocks listed above is mined.
```

`block-place`

```yml
variable:
  - "stone"
  - "cobblestone"
  - "gravel"
# This will progress the quest if any of the blocks listed above is placed.
```

## Blacklists

To create blacklist in variable, use `!` in front of first element

**Examples without subroots:**

`block-break`

```yml
variable: "!stone OR dirt"
# This will progress the quest if player mined any block except stone and dirt
```

`block-place`

```yml
variable:
  - "!stone"
  - "dirt"
# This will progress the quest if player placed any block except stone and dirt
```

**Examples with subroots:**

```yml
variable:
  root: "none"
  holding:
    item: "!diamond_pickaxe"
# This will progress the quest if player doesn't hold diamond pickaxe
```

## Variable format

There are some formats which you can use in variables to achieve certain functionality

### "Contains" element

"CONTAINS" element check if action root/subroot contains specified text. TO create this, add `__` before element.

**Example:**

```yml
variable: __ORE
```

In this case, root will accept every item which contains ORE in name (it also applies for strings and entities)

### ItemsAdder (experimental)

Just add `itemsadder:` before element name to use itemsadder items, block or entities

**Example:**

```yml
variable: itemsadder:ITEM_NAME
```

### MMOItems (experimental)

Just add `mmoitems:` before element name to use items from this plugin

**Example:**

```yml
variable: mmoitems:ITEM_NAME
```

### Properties

You can add some properties in JSON format.

#### `nbt` property

Minecraft NBT String to modify required item. I.e. to create quest that progres only when we use unbreakable diamond pickaxe, we can use this property.

Note: Minecraft NBT String must contain item name. It also must be in correct format (1.20.5 changed format of NBT String i.e. in give command)

**Example:**

```yml
variable:
    root: none
    holding:
        item: "diamond_pickaxe{nbt: 'diamond_pickaxe[unbreakable={}]'}"
```

#### `faces` property

Support for block with multiple faces i.e. mushroom blocks.

**Example:**

```yml
variable: "brown_mushroom_block{faces: ['west', 'east']}"
```

#### `age` property

Age of Ageable material i.e. age of planted carrot

**Example:**

```yml
variable: "carrots{age: 3}"
```

#### `progress` property

Added progress property (similar to old `special-progress` section). It's multiplier of progress.

**Example:**

```yml
variable: "iron_ingot OR diamond{progress: 3}"
```

In this case, diamond gives 3 progress instead of 1.

{% hint style="info" %}
`special-progress` is still available for cases where we can't use progress property, i.e. in blacklists
{% endhint %}

## PAPI conditions

If you have PlaceholderAPI installed, you can use variables conditions to have more control over when player can progress quest.

There are 2 types of conditions:

* `or` (same as `||` in Java) - player must meet at least one condition to progress
* `and` (same as `&&` in Java) - player must meet all conditions to progress

**Example:**

```yml
variable:
    root: none
    conditions:
        or:
          - "%player_is_op% == yes"
          - "%player_level% > 10"
        and: []
```

In this case, action will progress only when the player is op OR has level greater than 10.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.advancedplugins.net/actions/setting-up-and-using-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.