Macros

Macros are dynamic placeholders that get replaced with real values when your prompt is sent to the AI. They let you inject character names, dates, random values, variables, and more into your prompts, character cards, lorebooks, and author notes.

Macros use double curly braces: {{macro_name}}. Many macros accept parameters separated by ::, like {{random::1::100}}.

---

What macros are there that you can use?

Identity

Basic information about the current chat participants.

Macro	Aliases	Description
{{char}}	{{character}}, {{bot}}	Character's name
{{user}}	{{player}}	Your display name
{{persona}}	{{userpersona}}	Your persona description
{{model}}	{{aimodel}}, {{llm}}	Current AI model name
{{group}}	{{groupname}}	Group chat name (empty if not in group)

---

Character Card

Access fields from the current character card.

Macro	Aliases	Description
{{description}}	{{chardesc}}, {{chardescription}}	Character description
{{personality}}	{{charpersonality}}	Character personality field
{{scenario}}		Current scenario
{{mesExamples}}	{{examples}}, {{exampledialogue}}	Example dialogues (formatted)
{{mesExamplesRaw}}	{{examplesraw}}	Example dialogues (raw, unformatted)
{{charVersion}}	{{cardversion}}	Character card version
{{firstMessage}}	{{greeting}}	Character's greeting / first message
{{charTags}}	{{tags}}	Tags as comma-separated list
{{charCreator}}	{{cardcreator}}	Creator username
{{charCreatorNotes}}	{{creatornotes}}, {{cardnotes}}	Creator's notes
{{charPrompt}}	{{characterprompt}}	Character's main prompt override
{{charInstruction}}	{{charjailbreak}}, {{characterinstruction}}	Character's post-history instructions
{{charDepthPrompt}}	{{depthnote}}, {{characterdepthnote}}	Character's @ Depth Note

---

Pronouns

Automatically resolve pronouns based on character or user gender settings.

Character Pronouns

Macro	Example (he/she/they)
{{they}}	he / she / they
{{them}}	him / her / them
{{their}}	his / her / their
{{theirs}}	his / hers / theirs
{{themself}}	himself / herself / themself

Capitalized versions are available for start-of-sentence use: {{They}}, {{Them}}, {{Their}}.

User Pronouns

Prefixed with u: {{uthey}}, {{uthem}}, {{utheir}}, {{utheirs}}, {{uthemself}}.

---

Time & Date

Current real-world time and date information.

Macro	Parameters	Description
{{time}}	[format]	Current time (12h default, use {{time::24}} for 24h)
{{date}}	[format]	Current date (short / medium / long / full)
{{weekday}}		Day of the week
{{month}}		Current month name
{{day}}		Day of month (number)
{{year}}		Current year
{{isodate}}		ISO date (YYYY-MM-DD)
{{isotime}}		ISO datetime
{{datetimeformat::FMT}}	format string	Custom format using tokens: YYYY, MM, DD, HH, mm, ss, MMM, ddd
{{idle_duration}}		Time since last message (e.g. "5 minutes", "2 hours")
{{season}}	[hemisphere]	Current season (use {{season::south}} for southern hemisphere)
{{moonPhase}}		Current moon phase
{{zodiac}}		Current zodiac sign
{{timeDiff::date1::date2}}	two dates	Human-readable duration between two dates

---

Random & Dice

Generate random values for unpredictable outcomes.

Macro	Description	Example
{{random}}	Random number 0-100, re-rolls every turn	73
{{random::1::10}}	Random in range, re-rolls every turn	7
{{random::apple::banana::cherry}}	Pick random option (3+ args), re-rolls every turn	banana
{{pick::a::b::c}}	Pick from list, sticky within one turn	c
{{roll::2d6}}	Roll dice (standard notation)	8
{{roll::1d20+5}}	Roll with modifier	17
{{coinflip}}	Heads or Tails	Heads
{{coinflip::win::lose}}	Custom coin sides	win
{{percent}}	Random 0-100	42
{{range::0::100::5}}	Random from stepped range	35
{{shuffle::a::b::c}}	Shuffle all items	c, a, b
{{weighted::dragon::10::goblin::90}}	Weighted random pick	goblin (90% chance)

pick vs random

{{random}} re-rolls every time it's evaluated, including when old messages are re-processed for context. {{pick}} is sticky within one prompt assembly -- the same option set always returns the same result within a single turn. Two {{pick::a::b::c}} macros in different places will return the same value.

To make a random selection permanent across turns, combine {{pick}} with {{setvar}}:

{{setvar::species::{{pick::HUMAN::ELF::DWARF::ORC}}}}

This sets species once. On subsequent turns, the {{setvar}} in your old message will not re-fire (historical messages use read-only macro processing), so the variable keeps its original value. Use {{getvar::species}} anywhere to retrieve it.

Historical message safety

Write macros ({{setvar}}, {{setglobalvar}}, {{addvar}}, {{incvar}}, {{decvar}}, etc.) in old chat messages do not re-execute on subsequent turns. Only the current user message and preset prompts can write variables. This prevents old {{setvar}} calls from overwriting values every turn.

Read macros ({{getvar}}, {{getglobalvar}}, {{hasvar}}, etc.) still work normally in historical messages.

---

Text Processing

Transform and manipulate text.

Macro	Description	Example
{{upper::hello}}	Uppercase	HELLO
{{lower::HELLO}}	Lowercase	hello
{{title::hello world}}	Title Case	Hello World
{{trim:: hello }}	Remove whitespace	hello
{{reverse::hello}}	Reverse text	olleh
{{length::hello}}	Character count	5
{{wordcount::hello world}}	Word count	2
{{truncate::long text::4}}	Truncate with "..."	long...
{{replace::hello::l::r}}	Find and replace	herro
{{regex::hello::[aeiou]::*}}	Regex replace	h*ll*
{{split::a,b,c::,::1}}	Split and get index	b
{{join:: and ::a::b::c}}	Join with delimiter	a and b and c
{{repeat::ha::3}}	Repeat N times	hahaha
{{pad::42::5::0::left}}	Pad to length	00042
{{newline}}	Insert newline
{{space}}	Insert space
{{space::4}}	Insert multiple spaces
{{noop}}	Returns empty string
{{// comment}}	Invisible comment (removed from output)

---

Chat Context

Access information about the current chat session.

Macro	Description
{{lastMessage}}	Most recent message (any role)
{{lastUserMessage}}	Most recent user message
{{lastCharMessage}}	Most recent character message
{{firstMessage}}	First message in chat
{{message::N}}	Message at index N (0-based; negative counts from end)
{{recentMessages::5}}	Last N messages, formatted
{{message history}}	Full message history (token-aware, default 2000 tokens)
{{memories}}	Chat memory summaries (token-aware)
{{messageCount}}	Total message count
{{userMessageCount}}	User messages only
{{charMessageCount}}	Character messages only
{{chatId}}	Current session ID
{{chatStart}}	When the chat started (ISO format)
{{summary}}	Latest auto-generated chat summary
{{lastMessageId}}	Index of last message
{{lastSwipeId}}	Total swipe count
{{currentSwipeId}}	Current swipe index

---

Variables

Store and retrieve dynamic values that persist during a chat session. Variables are the backbone of stateful prompts -- use them to track mood, health, inventory, relationships, and more.

Local Variables (per-chat)

Macro	Description
{{getvar::name}}	Get a variable's value
{{setvar::name::value}}	Set a variable (returns empty)
{{addvar::name::5}}	Add to a numeric variable (returns new value)
{{incvar::name}}	Increment by 1
{{decvar::name}}	Decrement by 1
{{hasvar::name}}	Check if variable exists (true / false)
{{delvar::name}}	Delete a variable

Global Variables (cross-chat)

Same interface, prefixed with global:

Macro	Description
{{getglobalvar::name}}	Get global variable
{{setglobalvar::name::value}}	Set global variable
{{addglobalvar::name::5}}	Add to global numeric variable
{{incglobalvar::name}}	Increment global by 1
{{decglobalvar::name}}	Decrement global by 1

Arrays & Objects

Macro	Description
{{pushvar::name::value}}	Push to array (returns new length)
{{popvar::name}}	Pop from array (returns popped value)
{{listvar::name}}	Array as comma-separated list
{{countvar::name}}	Count array items or object keys
{{allvars}}	Debug: dump all local variables as JSON

Dot Notation Shorthand

A convenient shorthand for working with variables:

Shorthand	Expands To
{{.hp}}	{{getvar::hp}}
{{.hp = 100}}	{{setvar::hp::100}}
{{.hp += 10}}	{{addvar::hp::10}}
{{.hp -= 5}}	{{addvar::hp::-5}}
{{.counter++}}	{{incvar::counter}}
{{.counter--}}	{{decvar::counter}}
{{$globalname}}	{{getglobalvar::globalname}}

Nested access is supported: {{.stats.strength}}, {{.inventory.0}}.

---

Conditionals

Control what text appears based on conditions.

Inline Conditionals

Macro	Description
{{if::condition::then}}	Show then if condition is truthy
{{if::condition::then::else}}	If-else
{{compare::a::op::b}}	Compare two values (returns true / false)
{{and::a::b::c}}	Logical AND -- all must be truthy
{{or::a::b::c}}	Logical OR -- any must be truthy
{{not::value}}	Logical NOT

Block Conditionals

For longer conditional sections, use block syntax:

{{if {{compare::{{getvar::mood}}::==::happy}}}}
{{char}} smiles warmly at {{user}}.
{{else}}
{{char}} looks away quietly.
{{/if}}

Comparison Operators

Use with {{compare::a::op::b}}:

Operator	Description
==	Equal (case-insensitive)
!=	Not equal (case-insensitive)
===	Exact match (case-sensitive)
!==	Not exact match
>, <, >=, <=	Numeric comparison
contains	Substring check
startswith	Prefix check
endswith	Suffix check
matches	Regex test

Switch

{{switch::{{getvar::mood}}::happy:smiles::sad:frowns::default:stares}}

Here's how switch works — each case is a <case:result> pair separated by ::, with an optional default as the last arg (no colon):

Basic — match a mood:

{{switch::{{getvar::mood}}::
happy:She smiles warmly.::     // reaction for mood==happy
angry:She glares at you.::     // reaction for mood==angry
sad:Her eyes are downcast.::   // reaction for mood==sad
She looks at you blankly.}}    // default

With dot-notation shorthand:

{{switch::{{.weather}}::rain:You hear raindrops on the roof.::snow:Frost covers the windows.::Clear skies stretch overhead.}}

Time of day flavor text:

{{switch::{{.timeofday}}::morning:The sun rises over the hills.::afternoon:The midday heat shimmers.::evening:Long shadows stretch across the ground.::night:Stars fill the sky.::The world is
quiet.}}

NPC reaction based on relationship level:

{{switch::{{.relationship}}::hostile:The guard draws his sword.::neutral:The guard eyes you warily.::friendly:The guard nods in greeting.::loved:"Welcome back, old friend!"}}

Key details:

• Matching is case-insensitive
• Each case is caseValue:result (single colon)
• Cases are separated by :: (double colon)
• The last arg without a colon is the default (returned if nothing matches)
• Returns empty string if no match and no default

Truthiness

These values are considered falsy: empty string, "false", "0", "null", "undefined". Everything else is truthy.

---

Lorebook

Access lorebook entries and metadata within prompts.

Macro	Description
{{lorebook::EntryName}}	Get a specific entry's content by name
{{lorebookrandom::GroupName}}	Random entry from a group
{{lorebookcount}}	Number of currently triggered entries
{{lorebooktokens}}	Approximate token count of triggered entries
{{triggeredentries}}	Comma-separated list of triggered entry names
{{lorebooklist}}	Comma-separated list of active lorebook names
{{outlet::name}}	Named insertion point for world info

---

Stats & Tokens

Information about token usage and context budget.

Macro	Aliases	Description
{{tokencount}}	{{tokens}}, {{prompttokens}}	Current prompt token count
{{tokenbudget}}	{{maxcontext}}, {{contextsize}}	Maximum context size
{{tokenremaining}}	{{tokensremaining}}	Remaining tokens in budget
{{responsetokens}}	{{maxtokens}}, {{maxresponse}}	Max response tokens setting
{{sessiontokens}}	{{totaltokens}}	Total tokens used this session
{{costestimate}}	{{cost}}, {{apicost}}	Estimated API cost
{{contextusage}}	{{usage}}	Context usage as percentage

---

Roleplay Convenience

Shorthand macros that read from commonly-used variables. These are equivalent to {{getvar::name}} but more readable in prompts.

Macro	Variable	Description
{{mood}}	mood	Current mood
{{relationship}}	relationship	Relationship status
{{location}}	location	Current location
{{timeofday}}	timeOfDay	In-story time of day
{{trust}}	trust	Trust level
{{affection}}	affection	Affection level
{{tension}}	tension	Scene tension
{{weather}}	weather	Scene weather

Set these with {{setvar::mood::happy}} or the shorthand {{.mood = happy}}.

---

Game Mechanics

RPG helpers for stat checks, dice rolls, and inventory management. These read from a stats variable object.

Macro	Description	Example
{{stat::strength}}	Get a stat value	14
{{check::strength::15}}	d20 + stat vs DC	Success
{{check::strength::15::verbose}}	With roll breakdown	Success (rolled 12 + 14 = 26 vs DC 15)
{{damage::2d6+3}}	Roll damage	11
{{damage::2d6+3::verbose}}	With breakdown	11 (3 + 5 + 3)
{{hp}}	Display HP as current/max	45/100
{{progress::45::100}}	Text progress bar	[######----] 45%
{{inventory}}	List inventory items	sword, shield, potion
{{queststatus::name}}	Quest status	active
{{gold}}	Currency amount	250
{{level}}	Character level	5
{{xp}}	Experience points	1200

---

User-Defined Macros

Create reusable macro templates with parameter placeholders.

Define a macro

{{macro::greet::Hello {{$1}}, welcome to {{$2}}!}}

Call it

{{macro::greet::Alice::Wonderland}}

Output: Hello Alice, welcome to Wonderland!

Use {{$1}}, {{$2}}, etc. as parameter placeholders in the body.

---

Runtime

System-level information about the current environment.

Macro	Description
{{maxprompt}}	Maximum context tokens
{{ismobile}}	Whether on a mobile device
{{lastgenerationtype}}	Last generation type (chat, impersonate, continue, regenerate, swipe, quiet)
{{input}}	Current content in the chat input field
{{banned}}	Mark text as banned for completion

---

Where Can I Use Macros?

Macros are processed everywhere in the prompt pipeline:

• Presets -- System prompts, prompt stack entries, injections
• Character Cards -- Description, personality, scenario, first message, example dialogues
• Lorebooks -- Entry content and trigger conditions
• Personas -- User persona descriptions
• Author Notes -- Depth notes and creator notes

---

Nesting

Macros can be nested inside each other. The inner macro is resolved first:

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

This first resolves {{char}} to the character name (e.g. "Alice"), then gets the variable Alice_mood.

Maximum nesting depth is 100 levels.

---

Block Variables

You can use block syntax to set variables with multi-line content:

{{setvar::backstory}}
{{char}} grew up in a small village.
They learned to fight at a young age.
{{/setvar}}

This stores the entire block as the value of backstory.

---

Tips

• Comments: Use {{// your note here}} to leave notes in prompts that won't appear in the output
• Whitespace: Use {{noop}} or {{// }} to consume unwanted newlines from block macros
• Debugging: Use {{allvars}} to dump all current variables as JSON
• Testing rolls: Use {{roll::1d20}} in your system prompt to add randomness to AI behavior
• Dynamic names: Combine {{char}} and {{user}} with variables for multi-character scenarios