Macros & Variables

Dynamic text replacement using variables and macros for flexible character definitions.

What are Macros?

Macros are dynamic placeholders that get replaced with actual values during conversation. They make character definitions flexible and reusable.

Why Use Macros?

  • Reference character/user names dynamically
  • Insert contextual information automatically
  • Add randomness and variety
  • Create reusable character templates
  • Avoid hardcoding values

Built-in Variables

Basic Variables

{{char}} - Character's name {{user}} - User's current persona name {{Char}} - Character's name (capitalized) {{User}} - User's name (capitalized) {{CHAR}} - Character's name (UPPERCASE) {{USER}} - User's name (UPPERCASE)

Example Usage

Character Definition:{{char}} is a detective who works with {{user}} on complex cases. When {{user}} asks for help, {{char}} always responds professionally.Becomes (during chat):Morgan is a detective who works with Alex on complex cases. When Alex asks for help, Morgan always responds professionally.

Contextual Variables

Time & Date

{{time}} - Current time in setting (12:30 PM) {{date}} - Current date (January 15, 2025) {{day}} - Day of week (Monday) {{season}} - Current season (if set) {{time_of_day}} - Morning/Afternoon/Evening/Night

Location & Setting

{{location}} - Current location name {{setting}} - General setting description {{weather}} - Current weather (if set)

Conversation Metadata

{{message_count}} - Number of messages so far {{tokens}} - Approximate token count {{model}} - Current AI model name

Random Selection Macros

Add variety by randomly selecting from options.

Syntax

{{random:option1|option2|option3}}

Examples

Random Personality Trait

{{char}} greets {{user}} with a {{random:warm smile|friendly wave|polite nod|enthusiastic grin}}.

Random Dialogue

When nervous, {{char}} says {{random:"Um, well..."|"I think..."|"Let me see..."|"Hmm..."}}.

Random Action

{{char}} {{random:taps their fingers on the desk|adjusts their glasses|looks out the window|takes a sip of coffee}} while thinking.

Multi-Level Random

Nest random macros for more complexity:

{{char}} is feeling {{random:happy|sad|{{random:excited|nervous|contemplative}}}}.

Conditional Macros

Display text based on conditions.

If/Else Syntax

{{if:condition|then_text|else_text}}

Conditions

{{if:nsfw|Adult content warning|Safe for all ages}} {{if:first_message|Nice to meet you!|Good to see you again.}} {{if:message_count>10|We've been talking a while|Just getting started}}

Example in Character Definition

{{char}} treats {{user}} {{if:first_message|with polite formality|with comfortable familiarity}}.

Custom Variables

Define your own variables for reuse throughout character definition.

Defining Custom Variables

In Character Settings → Advanced → Custom Variables:

{{set:title=Detective}} {{set:location=Precinct 42}} {{set:mood=serious}}

Using Custom Variables

{{title}} {{char}} works at {{location}}. Today's {{mood}} atmosphere affects how they interact with {{user}}.

Dynamic Variables

Update variables during conversation:

{{update:mood=cheerful}} - Changes mood variable {{get:mood}} - Retrieves current mood value

Advanced Macro Functions

Number Operations

{{add:5+3}} - Addition (8) {{subtract:10-4}} - Subtraction (6) {{multiply:3*4}} - Multiplication (12) {{divide:20/5}} - Division (4) {{random:1-100}} - Random number between 1-100

String Operations

{{upper:text}} - UPPERCASE {{lower:TEXT}} - lowercase {{capitalize:text}} - Capitalize First Letter {{length:text}} - Character count {{trim: text }} - Remove whitespace

Array Operations

{{pick:list}} - Random item from list {{first:list}} - First item {{last:list}} - Last item {{count:list}} - Number of items

Macro Best Practices

When to Use Macros

  • ✅ Character/user name references
  • ✅ Adding variety to responses
  • ✅ Contextual information that changes
  • ✅ Reusable character templates
  • ❌ Simple static text
  • ❌ When hardcoded text is clearer

Keep It Simple

  • Don't over-use macros - they can make text hard to read
  • Use clear variable names
  • Test macros to ensure they work as expected
  • Balance dynamic and static content

Performance Tips

  • Limit nested random selections (max 2-3 levels)
  • Avoid excessive conditional logic
  • Cache frequently-used values in custom variables
  • Keep macro expressions short

Common Patterns

Dynamic Greetings

{{random:*waves*|*nods*|*smiles*}} {{random:Hey|Hi|Hello}} {{user}}! {{if:first_message|Nice to meet you!|Good to see you again!}}

Contextual Behavior

{{char}} is {{if:message_count<5|still getting comfortable|relaxed and familiar}} with {{user}}. {{char}}'s tone is {{random:professional|friendly|casual}}.

Setting Description

The scene takes place at {{location}} during {{time_of_day}}. The weather is {{weather|clear and pleasant}}.

Character Mood

{{char}} is feeling {{get:mood|neutral}} today, which affects how they respond to {{user}}'s questions.

Troubleshooting

Macro Not Working

  • Check syntax: must be {{macro}} with double braces
  • Verify variable name is correct
  • Ensure no extra spaces inside braces
  • Check if variable is defined (for custom variables)

Random Selection Always Same

  • Random is evaluated once per conversation turn
  • If defined in character description, it's set at start
  • Use in greeting for per-chat randomization
  • Or use regex scripts for dynamic per-message randomization

Unexpected Output

  • Test macros in isolation first
  • Check for typos in macro names
  • Verify conditional logic is correct
  • Use debug mode to see macro expansion
💡 Pro Tip: Use {{char}} and {{user}} everywhere instead of hardcoding names. This makes your character portable - others can import and use it with their own persona names.
Extensions & Scripts →Character Creation →Lorebook System →