# Variables & Syncing

PainterJS features a powerful global variable system (`VariableSet`) that allows you to define values on the server and use them in client-side math expressions.

## Why use Variables?
Instead of sending a new `Painter.paint()` packet every time a value changes (which is expensive), you can set a variable once and have the client update its UI every frame based on that variable.

## The `Painter.vars` API

### `Painter.vars.set(name, value)`
Sets a global variable.
*   **name**: String (e.g., `'mana'`).
*   **value**: Double.

### `Painter.sync(player)`
Syncs the current global variable state to a specific player.

### `Painter.syncAll()`
Syncs the current global variable state to **all** online players.

> **Note:** Variables are **not** automatically synced when you call `.set()`. You must call a sync method to push changes to the clients. This allows you to batch multiple variable updates into a single network packet.

---

## Using Variables in Objects
To use a variable in a paint object property, prefix its name with a `$` in the property string.

```javascript
// Server Script
Painter.vars.set('my_score', 1250);
Painter.syncAll();

Painter.paint(event.player, {
    score_text: {
        type: 'text',
        text: 'Score: $my_score', // Text replacement
        x: 10,
        y: '$my_score / 10',      // Math expression
        color: '#FFFFFF'
    }
});
```

## Handling Multiple Players (UUIDs)
Since `Painter.vars` is currently global, if you want to store per-player data (like individual mana bars), it is recommended to include the player's UUID in the variable name.

```javascript
// Setting per-player mana
Painter.vars.set('mana_' + player.uuid, 50);
Painter.sync(player);

// Referencing it in the paint object
mana_bar: {
    type: 'rectangle',
    w: '$mana_' + player.uuid,
    // ...
}
```
*Note: PainterJS supports dashes in variable names, so raw UUID strings are safe to use.*