Macros

Experimental Macro Engine

The Experimental Macro Engine supports nesting, stable substitution order, and other improvements. It is enabled by default for new installations. Existing installations can enable it in User Settings > Chat/Message Handling > Experimental Macro Engine.

Macros are dynamic placeholders that get replaced with actual values when text is processed. They are used throughout SillyTavern in prompts, character cards, lorebooks, Quick Replies, and more.

Finding Available Macros

SillyTavern provides built-in documentation for all available macros:

Slash command: Type /? macros in the chat input to display a list of all registered macros with their descriptions.
Autocomplete: See Macro Autocomplete below for details on getting suggestions while typing.

Macro Autocomplete

Macro autocomplete provides suggestions for available macros as you type. It works in all text fields that support macros throughout SillyTavern.

Type {{ to start autocomplete for macros, showing available macros and their arguments, potential Macro Flags, Variable Shorthands, and more.

Where autocomplete appears by default:

Chat user input box
Expanded editor (full-screen text editing, opened via the 'Expand' button next to text fields)
Prompt manager editor

Triggering autocomplete in other fields:

Press Ctrl+Space in any macro-supporting text field to open the autocomplete popup
Enable Settings → AutoComplete Settings → Show in all macro fields to have autocomplete appear automatically in all macro fields

Basic Syntax

Macros are enclosed in double curly braces:

{{macroName}}

Macro names are case-insensitive. {{User}}, {{USER}}, and {{user}} all resolve to the same macro.

Examples:

{{user}}        // Returns the current user/persona name
{{char}}        // Returns the current character name
{{time}}        // Returns the current time
{{date}}        // Returns the current date

Arguments

Many macros accept arguments to customize their behavior.

Space Separator

For macros with a single argument, a space can separate the macro name from its argument:

{{macroName argument}}

Examples:

{{getvar myVariable}}
{{roll 1d20}}
{{reverse Hello World}}

Double Colon Separator

Use :: to separate multiple arguments:

{{macroName::arg1::arg2::arg3}}

Examples:

{{setvar::myVariable::Hello World}}
{{random::red::green::blue}}
{{roll::2d6+3}}

Both space and :: are the recommended syntax for macro arguments.

Single Colon Separator (Legacy)

A single : can also introduce arguments, but this syntax is considered legacy and not recommended for new content:

{{macroName:argument}}

Examples:

{{roll:1d20}}

Whitespace in Macro Definitions

Whitespace between the macro name, separators, and arguments is ignored. This allows for more readable formatting:

{{ macroName :: arg1 :: arg2 }}
{{ setvar :: myVariable :: some value }}
{{ if :: condition }}

All of the above are equivalent to their compact forms without extra spaces.

Nested Macros

Macros can be nested inside other macros. Inner macros are resolved first:

{{getvar::{{char}}_mood}}

This first resolves {{char}} (e.g., to "Alice"), then resolves {{getvar::Alice_mood}}.

More examples:

{{setvar::greeting::Hello, {{user}}!}}

Sets a variable with content that includes the user's name.

{{if {{getvar::showDetails}}}}Details here{{/if}}

The condition itself is a macro that retrieves a variable value.

Scoped Macros

Any macro that accepts at least one argument supports scoped syntax. The content between opening and closing tags becomes the last argument of the macro.

Scoped Syntax

Instead of writing the last argument inline, it can be placed between opening and closing tags:

{{macroName argument}}
  scoped content here
{{/macroName}}

The closing tag uses the / flag before the macro name: {{/macroName}}.

This is equivalent to writing:

{{macroName::argument::scoped content here}}

Examples

Setting a variable with multiline content:

{{ setvar backstory }}
  This character was born in a small village
  and grew up to become a renowned scholar.
{{ /setvar }}

Using reverse with scoped content:

{{ reverse }}
  Hello World
{{ /reverse }}

This returns "dlroW olleH".

Content Trimming

By default, scoped content is automatically trimmed:

Leading and trailing whitespace is removed
Consistent indentation is de-dented (the indentation of the first non-empty line is removed from all lines)

This allows clean formatting:

{{ if condition }}
    # Heading
    Some content here
{{ /if }}

Produces # Heading\nSome content here (without the leading spaces).

To preserve all whitespace including leading/trailing newlines, use the # flag. See Macro Flags for details.

Conditional Macros

The {{if}} macro renders content conditionally based on whether a value is truthy or falsy.

Simple Condition

{{ if description }}
  # Character Description
  {{ description }}
{{ /if }}

This displays the heading and description only if description returns a non-empty value.

The condition can be:

A macro name (resolved automatically if no arguments are required)
Any value from a nested macro like {{getvar::flag}}
A variable shorthand like .myFlag or $globalFlag (see Variable Shorthands)
Any text you want (that will implicitly resolve to truthy or falsy based on its content)

Falsy values: empty string, false, 0, off, no.

Using Variable Shorthands in Conditions

Variable shorthands provide a concise way to check variable values in conditions:

{{ if .isEnabled }}
  Feature is enabled.
{{ /if }}

{{ if !$globalDisabled }}
  Not globally disabled.
{{ /if }}

See Variable Shorthands for more details on shorthand notation.

Inverted Condition

Prefix the condition with ! to invert it:

{{ if !personality }}
  No personality defined for this character.
{{ /if }}

If/Else Branches

Use {{else}} inside an {{if}} block to define an alternative branch:

{{ if personality }}
  {{ personality }}
{{ else }}
  No personality defined.
{{ /if }}

Another example:

{{ if {{getvar::details-block}} }}
  # Details Block
  {{ getvar::details-block }}
{{ else }}
  No details currently exist.
{{ /if }}

Macro Flags

Flags are special symbol characters placed between the opening braces and the macro name that modify macro behavior.

Syntax

{{!macroName}}
{{#macroName}}

Flags can be combined:

{{!?macroName}}

Whitespace is allowed between flags and the macro name:

{{ / macroName }}
{{ # macroName }}

Implemented Flags

Flag	Name	Description
`/`	Closing Block	Marks a closing tag for scoped macros. Example: `{{/if}}`
`#`	Preserve Whitespace	Prevents automatic trimming of scoped content.

Planned Flags (Not Yet Implemented)

Flag	Name	Description
`!`	Immediate	Resolve this macro before other macros in the same text.
`?`	Delayed	Resolve this macro after other macros in the same text.
`~`	Re-evaluate	Mark this macro for re-evaluation.
`>`	Filter	Enable pipe-based output filters for this macro.

Flags-like prefix operators

Variable shorthand syntax uses prefix operators (. and $) which behave similarly to flags but are not flags themselves.
See the Variable Shorthands section for details.

Preserve Whitespace Flag

Use the # flag when you need to preserve all whitespace in scoped content, including leading/trailing newlines and indentation:

{{ # setvar code }}
    function hello() {
        return "world";
    }
{{ /setvar }}

Without #, the content would be trimmed and dedented. With #, all whitespace is preserved exactly as written—including the newline after the opening tag and before the closing tag.

Comments

Use the comment macro to add notes that won't appear in the output:

{{// This is a comment and will be removed}}

For multi-line comments, use scoped syntax:

{{ // }}
  This entire block is a comment.
  It can span multiple lines.
{{ /// }}

Escaping Macros

To display literal curly braces without macro resolution, escape them with backslashes:

\{\{notAMacro\}\}

This outputs {{notAMacro}} as plain text.

Variable Shorthands

Variable shorthands provide a concise syntax for common variable operations. Use . for local variables and $ for global variables.

Variable Shorthands Prefixes

Prefix	Name	Description
`.`	Local Variable	Shorthand for local variable operations. Example: `{{.myvar}}`
`$`	Global Variable	Shorthand for global variable operations. Example: `{{$myvar}}`

These prefix operators have to be placed immediately before the variable name, after any optionally appearing Macro Flags. They aren't considered macro flags, but more indicators that a variable shorthand is being inserted, instead of a macro by name. The prefix operators are not part of the variable name itself, but rather modifiers that change how the variable is accessed.

Variable Names

Variable names follow the same rules as macro identifiers: start with a letter, followed by letters, digits, underscores, or hyphens. The last character is not allowed to be an underscore or hyphen.

{{.my-var}}       // Valid
{{.my_var}}       // Valid
{{.myVar123}}     // Valid

If your variable has an identifier that does not match the standard rules, you have to use the full variable macro syntax (e.g. {{getvar::my§var----}}), or rename/move your variable value.

Nested Macros in Values

Variable values can contain nested macros:

{{.greeting = Hello, {{user}}!}}

Resolves to a variable that saves Hello, User! inside. (If {{user}} is named "User")

Whitespace Handling

Whitespace around operators is allowed:

{{ .myvar = spaced value }}
{{ .counter ++ }}

Variable Shorthand Operators

The following operators can be used with variable shorthands. Each operator follows the pattern {{.varName operator value}} or {{$varName operator value}}.

Operator	Name	Example	Description
(none)	Get	`{{.myvar}}`	Returns the variable value
`=`	Set	`{{.myvar = value}}`	Sets the variable to a value, returns nothing
`++`	Increment	`{{.counter++}}`	Increments by 1, returns new value
`--`	Decrement	`{{.counter--}}`	Decrements by 1, returns new value
`+=`	Add	`{{.score += 10}}`	Adds to variable (numeric or string concatenation), returns nothing
`-=`	Subtract	`{{.health -= 5}}`	Subtracts from variable (numeric only), returns nothing
`\|\|`	Logical Or	`{{.name \|\| Guest}}`	Returns fallback if variable is falsy
`??`	Nullish Coalescing	`{{.name ?? Guest}}`	Returns fallback only if variable is undefined
`\|\|=`	Logical Or Assign	`{{.name \|\|= Guest}}`	Sets value if variable is falsy, returns the new value
`??=`	Nullish Coalescing Assign	`{{.name ??= Guest}}`	Sets value only if variable is undefined, returns the new value
`==`	Equals	`{{.status == active}}`	Compares values, returns `"true"` or `"false"`
`!=`	Not Equals	`{{.status != active}}`	Compares values, returns `"true"` if not equal
`>`	Greater Than	`{{.score > 50}}`	Returns `"true"` if variable is greater than value
`>=`	Greater Than or Equal	`{{.level >= 10}}`	Returns `"true"` if variable is greater than or equal to value
`<`	Less Than	`{{.health < 20}}`	Returns `"true"` if variable is less than value
`<=`	Less Than or Equal	`{{.health <= 0}}`	Returns `"true"` if variable is less than or equal to value

Get Variable

Retrieve variable values with a simple prefix:

{{.myvar}}       // Get local variable "myvar"
{{$myvar}}       // Get global variable "myvar"

Equivalent to {{getvar::myvar}} and {{getglobalvar::myvar}}.

Set Variable

Use the = operator to set a variable value:

{{ .myvar = Hello World }}     // Set local variable
{{ $myvar = Some value }}      // Set global variable

Equivalent to {{setvar::myvar::Hello World}} and {{setglobalvar::myvar::Hello World}}. Returns an empty string.

Increment

Use ++ to increment a numeric variable by 1:

{{.counter++}}    // Increment local variable, returns new value
{{$counter++}}    // Increment global variable, returns new value

Equivalent to {{incvar counter}} and {{incglobalvar counter}}. Returns the new value after incrementing.

Decrement

Use -- to decrement a numeric variable by 1:

{{.counter--}}    // Decrement local variable, returns new value
{{$counter--}}    // Decrement global variable, returns new value

Equivalent to {{decvar counter}} and {{decglobalvar counter}}. Returns the new value after decrementing.

Add

Use += to add a numeric value to a variable:

{{.score += 10}}     // Add 10 to local variable
{{$total += 5}}      // Add 5 to global variable

Equivalent to {{addvar::score::10}} and {{addglobalvar::total::5}}. Returns an empty string.

The add operator also supports appending strings to an existing string variable, if neither of them are numbers:

{{.myvar += {{noop}} | Second block}}   // Resolves to "Content | Second block" when the variable before was "Content".
                                        // Use `{{noop}}` to be able to add whitespaces, that otherwise would be trimmed automatically.

Subtract

Use -= to subtract a numeric value from a variable:

{{.health -= 10}}    // Subtract 10 from local variable
{{$points -= 5}}     // Subtract 5 from global variable

Equivalent to {{addvar::score::10}} and {{addglobalvar::total::5}}, but with a negative/inverted number. Returns an empty string. If the value is not a valid number, a warning is logged and the variable is unchanged.

Logical Or

Use || to provide a fallback value when the variable is falsy (empty string, 0, false):

{{.name || Anonymous}}     // Returns "Anonymous" if .name is empty or falsy
{{$setting || default}}    // Returns "default" if $setting is falsy

Returns the variable value if truthy, otherwise returns the fallback value. The fallback is only evaluated if needed (lazy evaluation).

Nullish Coalescing

Use ?? to provide a fallback value only when the variable does not exist:

{{.name ?? Guest}}         // Returns "Guest" only if .name is not defined
{{$config ?? default}}     // Returns "default" only if $config doesn't exist

Unlike ||, this returns the variable value even if it's falsy (empty string, 0, false) — as long as the variable exists. The fallback is only evaluated if needed (lazy evaluation).

Logical Or Assign

Use ||= to set a variable to a value only if it's currently falsy:

{{.name ||= Anonymous}}    // Sets and returns "Anonymous" if .name is falsy
{{$count ||= 0}}           // Sets and returns "0" if $count is falsy

If the variable is already truthy, returns the current value without modification. Returns the final value (either existing or newly set).

Nullish Coalescing Assign

Use ??= to set a variable to a value only if it doesn't exist:

{{.name ??= Guest}}        // Sets and returns "Guest" only if .name is undefined
{{$config ??= default}}    // Sets and returns "default" only if $config doesn't exist

Unlike ||=, this preserves falsy values (empty string, 0, false) if the variable already exists. Returns the final value (either existing or newly set).

Equals

Use == to compare a variable value to another value:

{{.status == active}}      // Returns "true" if .status equals "active", otherwise "false"
{{$mode == dark}}          // Returns "true" if $mode equals "dark", otherwise "false"

Performs a string comparison and returns the literal string "true" or "false".
Treats not existing variables, null variables and empty variables as the same.