Variables

A variable is a value you name once and use anywhere a field takes tokens. Instead of typing D:/Assets/Textures into ten export nodes, define TEXTURES once and write {TEXTURES} in each. Change it in one place and every path follows.

Export Image 1

Output Path

{TEXTURES}/{CLIENT}/{name}.png </>

Writes

D:/Assets/Textures/Acme/hero.png

Here TEXTURES is D:/Assets/Textures and CLIENT is Acme; {name} is a built-in token, the image’s name (see Naming with Tokens).

The quick answer

• Open Window > Variables. Add a variable in Global if you reuse it across projects, or Project if it belongs to this document.
• Type {yourname} into any import path, export path, Text field, or Export Data column. Typing { lists your variables beside the built-in tokens.
• Sharing a project? Send the .arcb. If it relies on a Global or External variable the other machine lacks, ArcBrush offers to fill it in on open, with your last value pre-filled.
• For a path that is portable by construction, build it on the built-in {project_dir}.
• To name files after the image, the node, or a batch frame, use the built-in tokens: see Naming with Tokens. To read another node’s label, use a node reference such as {Levels2.label}, not a variable: see Name the file after any node.

Where variables work

Every field that takes tokens reads your variables, and a variable name is written like any token, {NAME}:

• Export paths: {TEXTURES}/{CLIENT}/{name} on Export Image, Export Batch, and Export Texture.
• Import paths: {TEXTURES}/wood/base.png on Image In, SVG Import, Image Folder, and Texture Folder, so source files can live behind the same variables as your outputs.
• Text: a caption reading {CLIENT} concept art fills itself in.
• Export Data columns, and Tag rules (Project variables only).

A name that matches nothing is written exactly as typed, so {not a variable} as literal text needs no escaping. ArcBrush’s own token names are reserved: you cannot define a variable called name or date, and the panel tells you if you try. The Token Reference lists them.

The three kinds of variable

Click to zoom

Scope	Where it lives	Reach	Use it for
Global	Your app settings	Every project on this machine	Paths and values you reuse constantly (TEXTURES, your initials, a studio name)
Project	The .arcb file	Only this document, but travels with it	Values specific to one job (CLIENT, VERSION, a shot code)
External	external-variables.json in your app data folder	Every project on this machine, read-only	Values a render farm, asset manager, or build script maintains for you (see External variables)

When more than one scope defines the same name, Project wins over External, and External wins over Global: a project can always pin its own value, and a pipeline’s value overrides your machine-wide default. Colliding rows in the panel carry a label saying which one is in effect.

Promote or demote a variable

To move a variable between Global and Project without retyping it, use the panel’s Copy to Global, Move to Global, Embed in Project, and Move to Project actions.

Portability: sharing a project without breaking paths

If TEXTURES is a Global variable on your machine and you send the project to a teammate, their machine has no TEXTURES, so every {TEXTURES} path would break.

When you save, the project records the current value of every Global and External variable it uses. When your teammate opens the file and one of those names is defined nowhere on their machine, a single Reconcile Variables dialog lists what is needed with your last value pre-filled. For each one they choose:

• Define globally: add it to their own Global scope.
• Define in this project: add it to this document only.
• Ignore this session: leave it undefined for now.

A project that only uses Project variables never shows the dialog, and the dialog never writes External variables.

Tip

For assets you ship next to the project, the built-in {project_dir} token (the folder the .arcb lives in) is the most portable anchor: {project_dir}/textures/wood.png works on any machine, with no variable to reconcile.

External variables

External variables let a script or another application, such as a render farm or asset manager, feed values into ArcBrush without ArcBrush ever editing their file. They appear in their own read-only External section of the Variables panel, between Global and Project, and work everywhere your own variables do.

The file is external-variables.json in your per-user app data folder:

• Windows: %APPDATA%\ArcBrush\external-variables.json
• macOS: ~/Library/Application Support/ArcBrush/external-variables.json
• Linux: $XDG_CONFIG_HOME/arcbrush/external-variables.json, or ~/.config/arcbrush/external-variables.json if that variable is not set

ArcBrush writes that file only once: if it is missing at startup, it creates an empty one for your tool to fill in. After that it only reads it: at startup, whenever a document is opened or created, and when you press Reload in the panel.

A read is all-or-nothing: a valid file replaces the whole scope, and a missing, unreadable, or malformed file keeps the values you already had, with the panel saying which happened. To clear the scope, write a valid file with an empty variables array.

The panel shows the resolved path for your machine, with Copy, Open Folder, and Copy example JSON (a worked example to paste over the empty file).

{
  "version": 1,
  "variables": [
    { "name": "TEXTURES", "type": "string", "value": "D:/Assets/Textures", "description": "Shared texture library" }
  ]
}

version must be 1. Each entry needs a name (letters, digits, and underscores, starting with a letter or underscore) and a string value; type and description are optional. A duplicate name, a name that collides with a built-in token, or a value over 64 KiB rejects the whole file.

Tool authors

Write a temporary file in the same folder and atomically replace the target, rather than editing it in place while ArcBrush is running.

The file is plain, unencrypted configuration, and a project that uses an External value records it for reconciliation like a Global one, so never put passwords or keys in it.

Nested variables

A variable’s value can contain tokens, to build a family of related values on a shared base:

DRIVE     = D:\Projects
CLIENT    = {DRIVE}\Acme
TEXTURES  = {CLIENT}\textures

Change DRIVE and everything built on it moves too. Nesting works across all three scopes, and a variable that references itself, directly or through a chain, is rejected rather than expanded into partial text.

Renaming a Project variable in the panel rewrites every field that uses it (export paths, Text, import paths, Export Data columns, and Tag rules), keeping any transform after the name, in one undo step.

Transforms in a variable’s value

A variable’s value can use the same transforms and fallbacks as any field, as in STUDIO = {CLIENT|upper}. Two limits:

• A node token such as {this.label}, or a reference to another node such as {Levels2.label}, inside a variable’s value is written as typed, with a note, so a variable never hides which node it reads. Put node tokens in the field itself; to read one particular node from many fields, see Name the file after any node.
• Transforms need ArcBrush 1.7.0 or later. Global variables live in your app settings, which every installed version shares, so a transform in a Global variable’s value writes literal text in an older build too. If you keep an older build installed, put transforms in the templates instead.

Related

• Naming with Tokens: the built-in tokens, step by step, with recipes.
• Token Reference: every token and where it works.
• File Management: how paths resolve and travel with a project.