> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erlc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Variables in erlc.dev Studio Automations Guide

> Store and reuse values in your automations using local variables, persistent data variables, and list variables in erlc.dev Studio.

Variables let you store values — player names, counts, flags, IDs — and refer to them later in the same automation or even across multiple runs. erlc.dev Studio provides three kinds of variables: **local variables** that live only for the duration of a single run, **persistent data variables** that are stored server-side and survive across runs, and **list variables** for working with ordered collections of values. Choosing the right kind for each situation keeps your automations fast, readable, and correct.

***

## Local Variables

Local variables are created and read within a single automation run. Every time the automation fires, all local variables start fresh — they are not shared between runs or between different automations running at the same time.

<CardGroup cols={3}>
  <Card title="erlc_set_variable" icon="pen">
    Creates or overwrites a named variable. Provide the variable **name** in the NAME field and connect a value block to the VALUE input socket.
  </Card>

  <Card title="erlc_variable_value" icon="eye">
    Reads the current value of a named local variable. Plug this value block into any input socket that needs the stored value.
  </Card>

  <Card title="erlc_change_variable" icon="plus-minus">
    Adds a numeric amount to an existing local variable. Useful for counters — for example, incrementing a `kill_count` variable each time a loop body executes.
  </Card>
</CardGroup>

<Note>
  If you try to read a local variable with `erlc_variable_value` before it has been set with `erlc_set_variable`, it returns an empty value. Always set a variable before you read it.
</Note>

### Example: storing and reading a local variable

The following JSON represents two connected blocks: an `erlc_set_variable` block that stores the text `"Liberty County"` under the name `server_name`, and an `erlc_log` block that reads it back using `erlc_variable_value`.

```json theme={null}
[
  {
    "type": "erlc_set_variable",
    "fields": {
      "NAME": "server_name"
    },
    "inputs": {
      "VALUE": {
        "block": {
          "type": "text",
          "fields": {
            "TEXT": "Liberty County"
          }
        }
      }
    },
    "next": {
      "block": {
        "type": "erlc_log",
        "inputs": {
          "VALUE": {
            "block": {
              "type": "erlc_variable_value",
              "fields": {
                "NAME": "server_name"
              }
            }
          }
        }
      }
    }
  }
]
```

When this runs, the log panel outputs `Liberty County`.

<Tip>
  Use descriptive variable names like `target_player_id` instead of `x` or `temp`. You'll thank yourself when you come back to a complex automation later.
</Tip>

***

## Persistent Data Variables

Persistent data variables are stored server-side and survive across automation runs, bot restarts, and server resets. Use them when you need to remember state between events — for example, tracking a cumulative warning count for a player or storing a configurable threshold you update occasionally.

<CardGroup cols={3}>
  <Card title="erlc_data_variable_set" icon="floppy-disk">
    Writes a value to persistent storage under the given name. If a variable with that name already exists, it is overwritten.
  </Card>

  <Card title="erlc_data_variable_get" icon="database">
    Reads the stored value of a persistent variable by name. Returns the value as it was last written by `erlc_data_variable_set`.
  </Card>

  <Card title="erlc_data_variable_delete" icon="trash">
    Permanently removes a persistent variable from storage. The next `erlc_data_variable_get` for that name will return empty.
  </Card>
</CardGroup>

<Warning>
  Persistent variables are shared across all runs of all automations in your project. If two automations write to the same persistent variable name at the same time, one write may overwrite the other. Use unique, descriptive names to avoid collisions.
</Warning>

### Typical use cases

<AccordionGroup>
  <Accordion title="Player warning counters">
    Store a running count of warnings issued to a player using their user ID as part of the variable name (e.g. `warnings_76561198012345678`). Each moderation automation increments the counter with `erlc_data_variable_set` and reads it back with `erlc_data_variable_get` to decide whether to escalate.
  </Accordion>

  <Accordion title="Configurable thresholds">
    Store values like `max_warnings` or `afk_timeout_minutes` as persistent variables. Update them once from a slash command automation instead of editing block fields manually every time a policy changes.
  </Accordion>

  <Accordion title="Feature flags">
    Write a persistent variable named `patrol_mode_enabled` with a value of `true` or `false`. Any automation can read this flag to decide whether to proceed or skip its logic.
  </Accordion>
</AccordionGroup>

***

## List Variables

List variables are local (they reset each run) and hold an ordered collection of values. Use them when you need to track multiple items within a single run — for example, collecting the names of all players who triggered an event before sending a single summary message.

<CardGroup cols={2}>
  <Card title="erlc_list_add" icon="circle-plus">
    Appends an item to the end of a named list variable. If the list doesn't exist yet, it is created automatically.
  </Card>

  <Card title="erlc_list_remove" icon="circle-minus">
    Removes an item from the list by value or by index position.
  </Card>

  <Card title="erlc_list_contains" icon="circle-check">
    Returns `true` if the list contains the specified item, `false` otherwise. Use this inside an `erlc_if_then` block to avoid duplicates.
  </Card>

  <Card title="erlc_list_length" icon="hashtag">
    Returns the number of items currently in the list. Useful as a loop counter or to display a count in a message.
  </Card>
</CardGroup>

<Note>
  To iterate over every item in a list, use the `erlc_for_each` flow control block. Connect your list variable to its input, and the block exposes each item in turn as a local variable for the inner stack to use.
</Note>

### Example: checking a list before adding

```json theme={null}
[
  {
    "type": "erlc_if_then",
    "inputs": {
      "CONDITION": {
        "block": {
          "type": "erlc_list_contains",
          "fields": {
            "LIST_NAME": "warned_players"
          },
          "inputs": {
            "ITEM": {
              "block": {
                "type": "erlc_event_value",
                "fields": {
                  "KEY": "player_id"
                }
              }
            }
          }
        }
      },
      "DO": {
        "block": {
          "type": "erlc_log",
          "inputs": {
            "VALUE": {
              "block": {
                "type": "text",
                "fields": {
                  "TEXT": "Player already in warned list — skipping."
                }
              }
            }
          }
        }
      }
    }
  }
]
```

This checks whether the current event's `player_id` is already in the `warned_players` list. If it is, it logs a message and does not add the player again.

***

## Choosing the right variable type

| Need | Use |
| - | - |
| Temporary scratch value during a single run | Local variable (`erlc_set_variable`) |
| Running counter within a run | Local variable + `erlc_change_variable` |
| State that must survive a bot restart | Persistent variable (`erlc_data_variable_set/get`) |
| Collect multiple values in one run | List variable (`erlc_list_add`) |
| Permanent removal of stored state | Persistent variable (`erlc_data_variable_delete`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.