Macros Reference¶

Macros are template variables written as {{macro_name}} that get replaced with dynamic content when your preset is assembled into a prompt. This is the complete reference of the built-in macros available in Lumiverse.

How to Use Macros¶

Place macros anywhere in preset blocks, chat-facing prompt fields, and other prompt content that goes through macro evaluation:

You are {{char}}, a character described as: {{description}}
You are speaking with {{user}}.
{{persona}}

During prompt assembly, each macro is replaced with its current value.

Arguments¶

Some macros accept arguments, separated by :: (double colon) or spaces:

{{random::1::100}}          — random number between 1 and 100
{{pick::cat::dog::bird}}    — randomly selects one item
{{roll::2d6}}               — rolls two six-sided dice

Space-delimited arguments are also supported — each word becomes a separate argument:

{{upper hello}}             — same as {{upper::hello}}
{{setvar key value}}        — same as {{setvar::key::value}}
{{abs -5}}                  — same as {{abs::-5}}

Variable Shorthand¶

Access variables directly with . (local), $ (global), or @ (chat-persisted) prefixes:

{{.myVar}}                  — same as {{getvar::myVar}}
{{$theme}}                  — same as {{getgvar::theme}}
{{@hp}}                     — same as {{getchatvar::hp}}
{{.score = 100}}            — same as {{setvar::score::100}}
{{@hp = 100}}               — same as {{setchatvar::hp::100}}
{{.hp -= 25}}               — subtract 25 from hp
{{.counter++}}              — increment by 1
{{@turn++}}                 — increment a persisted counter
{{.counter--}}              — decrement by 1

Variable shorthands work inside conditions too:

{{if .myVar}}has a value{{/if}}
{{if .score == 100}}perfect!{{/if}}
{{if !.gameOver}}still playing{{/if}}
{{if $theme == dark}}dark mode{{/if}}
{{if @hp > 0}}still alive{{/if}}

Scoped Macros¶

A few macros wrap content between opening and closing tags:

{{if::{{isGroupChat}}}}
This is a group conversation with {{group}}.
{{else}}
This is a private conversation.
{{/if}}

Prefixes & Scoped Tags¶

Lumiverse parses SillyTavern-style macro prefixes. The currently user-relevant ones are:

Closing scoped macros use /, like {{/if}}, {{/trim}}, or {{/numbered}}.

Core Macros¶

Utility macros for text manipulation and flow control.

Conditional Logic¶

{{if::condition}}
  Content when true
{{else}}
  Content when false
{{/if}}

The condition can be any value — it's truthy unless it's empty, "0", "false", "null", "undefined", "no", or "off" (case-insensitive for the named falsy values).

Only the selected branch is resolved. Side-effect macros in the unselected branch do not run.

Negation — prefix with ! to invert:

{{if::!0}}yes{{/if}}                — "yes" (0 is falsy, negated → truthy)
{{if::!{{hasvar::key}}}}missing{{/if}}

Comparisons — use ==, !=, >, <, >=, <= inside the condition:

{{if::{{messageCount}} > 10}}long chat{{/if}}
{{if::{{.score}} == 100}}perfect!{{/if}}

Else-if chains — use {{elseif}} or {{elif}} to avoid deeply nested if blocks:

{{if::{{groupCardMode}} == solo}}
Solo chat rules.
{{elseif::{{groupCardMode}} == swap}}
Focused group-member rules.
{{elseif::{{groupCardMode}} == merge_ignore_muted}}
Merged non-muted group rules.
{{else}}
Merged group rules.
{{/if}}

Unless — invert a condition at the block level:

{{unless::{{isGroupChat}}}}
Only include this in solo chats.
{{else}}
Only include this in group chats.
{{/unless}}

Variable shorthand — .var, $var, and @var resolve automatically in conditions:

{{if .myVar}}has a value{{/if}}
{{if .x > .y}}x is bigger{{/if}}
{{if !.gameOver}}still playing{{/if}}
{{if @hp > 0}}still alive{{/if}}

Iteration¶

{{foreach}}¶

Repeat a block of content once for each item in a list — the macro equivalent of a JavaScript forEach. The list is a single string that is split on a delimiter (, by default); each item is trimmed and blank items are dropped.

{{foreach::apple, banana, cherry}}
- {{.item}}
{{/foreach}}

produces:

- apple
- banana
- cherry

Custom loop variable — the second argument renames the loop variable (default item):

{{foreach::Alice,Bob::name}}{{.name}} is here. {{/foreach}}

Custom delimiter — the third argument changes the split character. Pass an empty delimiter (::) to treat the whole string as a single item:

{{foreach::a|b|c::item::|}}{{.item}} {{/foreach}}    — splits on "|"

Inside the body, these loop variables are available (replace item with your variable name):

Numbered list:

{{foreach::Sword,Shield,Potion::loot}}{{.loot_number}}. {{.loot}}{{newline}}{{/foreach}}

Comma-joined list — use {{.x_last}} to skip the trailing separator:

{{foreach::a,b,c::x}}{{.x}}{{if::!{{.x_last}}}}, {{/if}}{{/foreach}}    — "a, b, c"

{{foreach}} pairs naturally with any macro that returns a delimited list, such as {{players}} or {{group}}:

{{foreach::{{players}}}}- {{.item}}{{newline}}{{/foreach}}

{{range}}¶

Generate a numeric sequence as a comma-separated list — ideal for counted loops.

{{range::5}}              — "1, 2, 3, 4, 5"   (1..n inclusive)
{{range::3::6}}           — "3, 4, 5, 6"      (start..end inclusive)
{{range::1::10::2}}       — "1, 3, 5, 7, 9"   (with a step)
{{range::5::1}}           — "5, 4, 3, 2, 1"   (counts down)

Feed it into {{foreach}} for indexed repetition:

{{foreach::{{range::1::{{playerCount}}}}::n}}Round {{.n}}…{{newline}}{{/foreach}}

{{filter}}¶

Keep only the list items whose body — an {{if}}-style condition — is truthy, returning a comma-separated list. The body sees the same loop variables as {{foreach}} ({{.item}}, {{.item_index}}, …).

{{filter::1,2,3,4::n}}{{gt::{{.n}}::2}}{{/filter}}                  — "3, 4"
{{filter::{{players}}::p}}{{ne::{{.p}}::{{hostName}}}}{{/filter}}    — everyone but the host

{{map}} / {{collect}}¶

Transform each item in a list and return the transformed values as a delimited list. It uses the same loop bindings and hygiene as {{foreach}}.

{{map::a,b,c::x}}{{upper::{{.x}}}}{{/map}}          — "A, B, C"

Arguments:

{{map::Alice|Bob|Cara::name::|:: / }}{{.name_number}}={{.name}}{{/map}}

produces:

1=Alice / 2=Bob / 3=Cara

{{some}} / {{every}}¶

Test whether any ({{some}}) or all ({{every}}) items satisfy a predicate. Both return "true" / "", are usable as conditions, and short-circuit. {{every}} is vacuously "true" for an empty list.

{{if::{{some::{{players}}::p}}{{eq::{{.p}}::Bob}}{{/some}}}}Bob is here.{{/if}}
{{if::{{every::{{range::1::5}}::n}}{{gt::{{.n}}::0}}{{/every}}}}all positive{{/if}}

{{foreachMessage}}¶

Loop over the chat history, resolving the body once per message — for custom transcripts, pulling out a speaker's lines, or scanning recent turns.

{{foreachMessage}}{{.msg_name}}: {{.msg}}{{newline}}{{/foreachMessage}}
{{foreachMessage::5}}…{{/foreachMessage}}            — only the last 5 messages
{{foreachMessage::5::m}}…{{.m}}…{{/foreachMessage}}  — last 5, body variable "m"

A numeric first argument iterates the last N messages (oldest-first); a non-numeric first argument is the loop variable name (default msg). Body bindings (replace msg):

{{foreachMessage::10::m}}{{if::{{.m_is_user}}}}> {{.m}}{{newline}}{{/if}}{{/foreachMessage}}    — the user's recent lines

{{foreachVar}} / {{foreachChatVar}} / {{foreachGlobalVar}}¶

Loop over the variables in a scope whose name starts with a prefix — the way to render a dynamic state table when you don't know the keys ahead of time. {{foreachVar}} reads local (.) variables, {{foreachChatVar}} reads chat-persisted (@) variables, and {{foreachGlobalVar}} reads global ($) variables. Items are visited in alphabetical key order.

{{@hp_Alice = 100}}{{@hp_Bob = 80}}
{{foreachChatVar::hp_::p}}{{.p}}: {{.p_value}} HP{{newline}}{{/foreachChatVar}}

produces:

Alice: 100 HP
Bob: 80 HP

Body bindings (replace item): {{.item}} is the name after the prefix, {{.item_key}} is the full variable name, {{.item_value}} is its value, plus the usual {{.item_index}} / {{.item_number}} / {{.item_count}} / {{.item_first}} / {{.item_last}}.

Lists¶

Query and transform comma-separated lists. These compose with the iteration macros and with anything that returns a list ({{players}}, {{group}}, {{range}}). Input is split on commas (items trimmed, blanks dropped); list-returning macros emit a clean ,-separated list, so the family round-trips.

Examples:

{{count::{{players}}}}                        — how many players
{{if::{{includes::{{group}}::Bob}}}}…{{/if}}   — gate on membership
{{first::{{sort::10,2,30}}}}                   — "2" (numeric sort → smallest)
{{slice::{{players}}::-2}}                      — the last two players
{{unique::{{sort::b,a,b,c}}}}                   — "a, b, c"

Numeric reductions¶

Reduce a list of numbers to a single value (non-numeric items are ignored).

{{sum::{{range::1::10}}}}                                            — "55"
{{avg::{{foreachChatVar::hp_::p}}{{.p_value}},{{/foreachChatVar}}}}   — average party HP

Identity & Names¶

Macros for character and user identity.

Multiplayer¶

State about the current multiplayer room. Outside a room every macro returns a safe "not multiplayer" value ({{isMultiplayer}} → "no", counts → 0, names → empty), so presets can reference them unconditionally. Names match what you see on messages: a player's persona name if they set one, otherwise their display name.

Gate room-only content so it costs nothing in solo chats:

{{if::{{isMultiplayer}}}}
This is a group session with {{playerCount}} players: {{players}}.
It is currently {{currentPlayer}}'s turn.
{{/if}}

Enumerate the roster with {{foreach}}:

{{if::{{isMultiplayer}}}}
Players in the room:
{{foreach::{{players}}::player}}{{.player_number}}. {{.player}}{{newline}}{{/foreach}}
{{/if}}

Character Data¶

Macros that pull from the character card fields. These respect alternate field selections.

Character Tags¶

Macros that read the current character card's tags — categorical labels such as Fantasy, Warrior, OC, or Female.

{{charTags}}                         — "Fantasy, Warrior, Male"
{{tagCount}}                         — "3"
{{tag::0}}                           — "Fantasy" (first tag)
{{tag::-1}}                          — "Male" (last tag)
{{hasTag::warrior}}                  — "true" (case-insensitive)
{{randomTag}}                        — one of the tags at random

{{if::{{hasTag::villain}}}}The character is a villain.{{/if}}
{{foreach::{{charTags}}::t}}- {{.t}}{{newline}}{{/foreach}}
{{count::{{charTags}}}}              — same as {{tagCount}}
{{includes::{{charTags}}::Warrior}}  — "true"

Chat & Conversation¶

Macros for the current chat state.

Time & Date¶

Macros for current time information.

Examples:

It is currently {{time}} on {{weekday}}, {{date}}.
The user has been idle for {{idleDuration}}.

Random & Entropy¶

Macros for randomness and dice rolling.

Examples:

{{char}} rolls a {{roll::1d20}} on their perception check.
The weather today is {{pick::sunny::cloudy::rainy::stormy}}.
A random number: {{random::1::100}}

String Manipulation¶

Transform, measure, and extract from text.

Examples:

{{upper::{{char}}}}                     — "BOB"
{{len::{{description}}}}                — "234" (character count)
{{replace::they::she::{{persona}}}}     — pronoun swap
{{split::{{charTags}}::,::0}}           — first tag
{{join::, ::{{char}}::{{user}}}}        — "Bob, Alice"
{{repeat::3}}---{{newline}}{{/repeat}}  — three separator lines
{{wrap::(**::**)::{{.note}}}}           — "(**important**)" or "" if empty
{{regex::\b(he|him)\b::she/her::{{description}}}}

Math¶

Arithmetic without intermediate variable gymnastics.

Examples:

{{calc::{{messageCount}} * 2 + 1}}      — arithmetic with macros
{{calc::({{.hp}} / {{.maxHp}}) * 100}}   — health percentage
{{clamp::{{.score}}::0::100}}            — keep score in bounds
{{max::{{.str}}::{{.dex}}}}              — highest stat
{{round::3.14159::2}}                    — "3.14"

Logic & Comparisons¶

Composable boolean logic and multi-branch conditionals.

Branching¶

{{switch}} also has a scoped block form for larger branches:

{{switch::{{groupCardMode}}}}
{{case::solo}}
Solo chat instructions.
{{/case}}
{{case::swap}}
Focused group-member instructions.
{{/case}}
{{case::merge::merge_ignore_muted}}
Merged group instructions.
{{/case}}
{{default}}
Fallback instructions.
{{/default}}
{{/switch}}

Only the matching {{case}} body, or the {{default}} body, is resolved.

Boolean Operators¶

Comparison Operators¶

Predicate Helpers¶

Examples:

{{switch::{{.mood}}::happy::😊::sad::😢::neutral}}

{{default::{{.title}}::Stranger}}

{{if::{{and::{{isGroupChat}}::{{lumiaCouncilModeActive}}}}}}
  Group council is active.
{{/if}}

{{if::{{gt::{{messageCount}}::50}}}}
  This is a long conversation.
{{/if}}

{{if::{{blank::{{.optional_note}}}}}}
  No note was provided.
{{/if}}

{{if::{{matches::{{lastUserMessage}}::\\bhelp\\b::i}}}}
  The user asked for help.
{{/if}}

Formatting¶

Quick list formatting.

Examples:

{{bullets::{{char}}::{{user}}::{{group}}}}
{{numbered}}
Establish the scene
Describe the character's action
Include internal thoughts
{{/numbered}}

Chat Utilities¶

Access individual messages, track state, and query chat metadata.

Examples:

{{messageAt::0}}                  — the first message (greeting)
{{messageAt::-1}}                 — the most recent message
{{messagesBy::{{char}}::3}}       — last 3 things the character said

{{counter::scene_count}}          — auto-incrementing scene counter
{{toggle::narrator_mode}}         — flip between narrator on/off

This chat started {{chatAge}} ago.

Regex Script References¶

Call installed regex scripts by their Script ID — a stable, user-defined identifier you set on any regex script.

Script IDs are auto-normalized: lowercase, spaces/hyphens become underscores, punctuation stripped. "My Cool-Script!" becomes my_cool_script.

Examples:

{{!-- Check if a script is installed --}}
{{if::{{regexInstalled::censor}}}}
  Content filtering is active.
{{/if}}

{{!-- Apply a regex script inline --}}
{{regexInstalled::fix_pronouns::{{description}}}}

{{!-- Scoped form --}}
{{regexInstalled::format_dialogue}}
  "Hello," she said. "How are you?"
{{/regexInstalled}}

Variables¶

Read and write values in three scopes — local (transient per-evaluation), chat (persisted per-chat), or global (cross-chat).

Local Variables (Transient)¶

Local variables live for the duration of a single evaluation pass. They are useful for intermediate calculations, loop counters, and temporary values within a preset block. They are not saved between generations.

Aliases: {{varexists}} for {{hasvar}}, {{flushvar}} for {{deletevar}}, {{withVar}} / {{scope}} for {{let}}

Shorthand: . prefix — {{.myVar}}, {{.score = 100}}, {{.counter++}}

Scoped temporary variables:

{{let::speaker::{{char}}::tone::quiet}}
Write {{.speaker}} with a {{.tone}} voice.
{{/let}}

{{let}} is hygienic: if a local variable already existed, its previous value is restored after the block; if it did not exist, it is removed after the block.

Chat-Persisted Variables¶

Chat-persisted variables are automatically saved to the chat after each generation. They survive across messages, regenerations, and page reloads — making them ideal for tracking story state like health, quest progress, relationship points, or turn counters.

Alias: {{flushchatvar}} for {{deletechatvar}}

Shorthand: @ prefix — {{@hp}}, {{@hp = 100}}, {{@turn++}}, {{@hp -= 25}}

Example — RPG state tracking:

{{@turn++}}
{{@hp -= {{roll::1d6}}}}

{{if::{{gt::{{@hp}}::0}}}}
Turn {{@turn}}: {{char}} takes damage. HP: {{@hp}}/{{@maxHp}}
{{else}}
Turn {{@turn}}: {{char}} has fallen!
{{/if}}

Example — Relationship tracker:

{{setchatvar::affection::50}}

{{if::{{gt::{{@affection}}::80}}}}
{{char}} looks at you warmly.
{{else}}
{{char}} gives you a polite nod.
{{/if}}

setchatvar also supports scoped syntax — the enclosed content becomes the value:

{{setchatvar::last_scene}}The group arrived at the ancient temple...{{/setchatvar}}

Global Variables (Cross-Chat)¶

Global variables persist across all chats for the current user. Useful for preferences, themes, or cross-character state.

Aliases: {{getglobalvar}}, {{setglobalvar}}, {{addglobalvar}}, {{incglobalvar}}, {{decglobalvar}}, {{hasglobalvar}}, {{gvarexists}}, {{flushgvar}}, {{flushglobalvar}}, {{deleteglobalvar}}

Shorthand: $ prefix — {{$theme}}, {{$theme = dark}}

Variable Scope Summary¶

Example — Combined usage:

{{.roll = {{roll::1d20}}}}
{{@hp -= {{.roll}}}}
Rolled {{.roll}} damage. {{char}}'s HP: {{@hp}}/{{@maxHp}}

Here .roll is a temporary local variable (used for the current evaluation only), while @hp and @maxHp are chat-persisted and carry over to the next generation.

Prompt Variables (Preset Inputs)¶

Prompt variables are preset-defined inputs that are seeded into local scope before block evaluation. That means {{var::tone}}, {{getvar::tone}}, and {{.tone}} can all resolve to the same runtime value.

Variables come in seven types — Text, Text Area, Number, Slider, Dropdown, On/Off, and Multi-select — and each resolves to its rendered value when read:

• Dropdown → the selected option's value string (the long, expanded text the creator wrote).
• On/Off → 1 when on, 0 when off. Use directly in {{if::...}} gates.
• Multi-select → the selected options' values, joined by the variable's separator (default \n\n).

Examples:

Tone: {{default::{{var::tone}}::neutral}}

{{if::{{hasPromptVar::violence}}}}
Violence level: {{var::violence}}
{{/if}}

// On/Off switches resolve to 1 or 0 — drop them straight into {{if::...}}.
{{if::{{var::strict_canon}}}}
Strictly adhere to established canon.
{{/if}}

// Multi-select: the rendered value is the joined block of selected option values.
Style guidelines:
{{var::style_guides}}

// Multi-select: branch on WHICH options are selected with the ison sub-syntax.
{{if::{{var::style_guides::ison::concise,polite}}}}
Stay tight and respectful — no throat-clearing.
{{/if}}

Runtime & State¶

Information about the current system state.

Prompt Block Placement¶

These read-only macros report the effective placement of the preset block currently being rendered. If that block uses a Placement Selector, they reflect the user's saved Dropdown choice; otherwise they reflect the block's ordinary configuration.

They resolve to an empty string outside preset-block rendering, such as in a free-form macro preview. They only report placement; they cannot move or modify a block.

Example — adapt wording to placement:

{{if::{{promptBlockPosition}} == in_history}}
This is an in-history reminder. Treat it as context attached near the conversation.
{{else}}
This is a top-level instruction block.
{{/if}}

{{if::{{promptBlockRole}} == system}}
Follow these instructions at the system level.
{{/if}}

Reasoning / Chain-of-Thought¶

For models that support extended thinking (DeepSeek, Claude, o1).

Example:

{{reasoningPrefix}}
Think step by step about what {{char}} would do next.
{{reasoningSuffix}}

Memory¶

Long-term memory and retrieval macros from Lumiverse's memory systems.

Long-Term Memory¶

Databank Retrieval¶

Memory Cortex¶

Lumia & Council¶

Macros for the council deliberation system and Lumia personas. These resolve to content only when the relevant systems are enabled.

Lumia Identity¶

Alias: {{lumiaCouncilQuirks}} for {{lumiaQuirks}}

Council Status (Condition-Compatible)¶

Council Content¶

OOC (Out-of-Character)¶

Loom¶

Macros for the Loom narrative system.

Loom Content¶

Loom Conversation Aliases¶

Sovereign Hand¶

Condition-Compatible Macros¶

These macros return condition-friendly truthy/falsy values (such as "yes" / "no" or "true" / empty) and are designed for use with {{if}}:

Usage:

{{if::{{lumiaCouncilModeActive}}}}
Council deliberation results:
{{lumiaCouncilDeliberation}}
{{/if}}

{{if::{{and::{{hasTag::fantasy}}::{{gt::{{messageCount}}::5}}}}}}
The adventure is well underway.
{{/if}}

Tips for Preset Creators¶