Roleplay

Elftia includes a built-in Roleplay (RP) system compatible with SillyTavern, allowing you to create and import character cards, build world-building settings, and engage in immersive roleplay conversations with AI. It supports TavernCard V2/V3 formats, World Info knowledge bases, multi-character group chat, regex text replacement, and emotion sprite sheets.

Use Cases

• Create virtual characters and engage in immersive conversations with them
• Import character cards from SillyTavern or character card sharing websites (PNG with embedded metadata)
• Build world-building settings (World Info) so AI automatically references relevant knowledge based on conversation context
• Set up multi-character group chat scenarios with character interactions
• Use regex scripts to automatically replace or modify output text
• Configure emotion sprite sheets for characters to dynamically switch expressions based on emotions

Character Cards

Character cards are the foundation of roleplay, defining the AI character's personality, background, and behavioral patterns.

Card Formats

Elftia supports multiple character card formats:

Format	Identifier	Description
TavernCard V2	v2	Standard SillyTavern format with Base64-encoded JSON metadata embedded in PNG images
TavernCard V3	v3	Extended version of V2 with additional fields like Assets and creation date
CharX	charx	Extended character card format
BYAF	byaf	Build Your AI Friend format
JSON	json	Pure JSON character data format
Manual Creation	manual	Characters manually created in Elftia

Card Fields

Each character card contains the following fields:

Field	Description	Required
Name (name)	Character name	Yes
Description (description)	Detailed character description including appearance, identity, and background	Yes
Personality (personality)	Character personality traits	No
Scenario (scenario)	Scene setting for the conversation	No
First Message (first_mes)	Character's opening line	No
Example Dialogue (mes_example)	Examples of the character's dialogue style	No
System Prompt (system_prompt)	Character-specific system prompt	No
Post History Instructions (post_history_instructions)	Instructions inserted after message history	No
Alternate Greetings (alternate_greetings)	Multiple optional opening lines	No
Creator Notes (creator_notes)	Notes about the character card creation	No
Tags (tags)	Classification tags	No
Character Avatar (avatar)	Character avatar image	No

Creating Character Cards

Steps

1. Open the character card management page
2. Click the Create Character button
3. Fill in character information (name, description, personality, etc.)
4. (Optional) Upload character avatar
5. (Optional) Write example dialogues
6. (Optional) Set system prompt
7. Save the character card

Importing Character Cards

Elftia supports importing character cards from PNG files. Many character card sharing websites provide PNG images with embedded character data.

Importing from PNG

1. Click Import in character card management
2. Select a PNG file containing character data
3. System automatically parses the JSON metadata embedded in the PNG
4. Preview character information
5. Confirm import

:::info PNG Metadata Format

• V2 Format: Data stored in PNG's tEXt chunk with keyword chara, content is Base64-encoded JSON
• V3 Format: Keyword is ccv3, containing richer metadata :::

Importing from JSON

You can also directly import character data files in JSON format.

Exporting Character Cards

Character cards can be exported as PNG files (with embedded metadata) or JSON files for easy sharing and backup.

Exporting as PNG

1. Select the character card to export
2. Click the Export button
3. Select PNG Format
4. System embeds character data into the avatar PNG
5. Save the exported PNG file

The exported PNG file can be directly imported into SillyTavern or other compatible applications.

Using Characters in Conversations

Steps

1. Open the settings panel for your chat session
2. Expand the Roleplay settings area
3. Select a character card from the Character Selector
4. Configure RP-related parameters (see configuration table below)
5. Start chatting

RP Configuration Parameters

Parameter	Description	Default Value
Character Card (characterCardId)	Select which character to use	None
User Name (userName)	Your name in RP	User
User Persona (userPersona)	Your character background	None
Author's Note (authorsNote)	Hidden instructions inserted into conversation context	None
Author's Note Depth (authorsNoteDepth)	Position where note is inserted (distance from latest message)	4
Reply Prefix (replyPrefix)	Prefix automatically added before AI's reply	None
Quick Replies (quickReplies)	Preset quick reply buttons	None
Context Template (contextTemplateId)	Custom prompt assembly order	None
Summarization (summarizationEnabled)	Enable conversation summarization (compress long conversations)	No

World Info

World Info is a knowledge base system in roleplay that stores world-building knowledge entries. When keywords matching the conversation are found, relevant World Info entries are automatically injected into the AI's context.

Core Concepts

Concept	Description
Book	Container for World Info, can contain multiple entries
Entry	Single knowledge item with trigger keywords and content
Keys	List of keywords that trigger an entry
Scan Depth	How many recent messages to scan for keyword matches
Token Budget	Maximum tokens World Info can consume
Recursive Scanning	Whether to continue scanning keywords within triggered entry content

Creating World Info

1. Open the World Info management page
2. Create a Book
3. Add Entries to the book
4. Set trigger keywords and content for each entry

Entry Configuration

Field	Description
Keywords (keys)	List of keywords that trigger this entry
Content (content)	Knowledge content of the entry
Enabled (enabled)	Whether this entry is enabled
Insertion Order (insertion_order)	Priority sorting when multiple entries are triggered
Case Sensitive (case_sensitive)	Whether keyword matching is case-sensitive
Selective Matching (selective)	Whether both primary and secondary keywords must match
Secondary Keys (secondary_keys)	Secondary keywords for selective matching
Constant (constant)	Whether to always include in context
Position (position)	Where to insert in context
Depth (depth)	Custom insertion depth
Probability (probability)	Trigger probability (0-100%)
Match Whole Words (match_whole_words)	Whether to match only complete words

World Info Scan Settings

Setting	Description	Default
Scan Depth	How many recent messages to scan	10
Token Budget	Maximum tokens to consume	2048
Recursive Scanning	Continue matching within triggered content	No

Using World Info

1. Select one or more books in the RP settings panel
2. Configure scan parameters
3. System automatically scans and injects matching entries during conversation

Character Embedded Knowledge Book

Character cards can include an embedded Character Book, which automatically creates the corresponding World Info knowledge base when imported.

Group Chat

Group chat mode allows multiple characters to participate in conversations simultaneously, simulating multi-person interactions.

Steps

1. Create a group chat configuration
2. Add participating characters (character cards)
3. Select the group chat configuration in RP settings
4. Start group chat conversation

Behavior

• In each round of conversation, the system determines which character replies based on configuration
• Each character's personality and settings remain independent
• Support for manually specifying the next character to reply

Regex Scripts

Regex scripts allow you to use regular expressions to automatically replace and modify AI's input or output.

Use Cases

• Automatically format AI's output
• Replace specific text patterns
• Add or remove specific tags

Configuration

In the Regex Scripts area of the RP settings panel:

1. Add a new regex rule
2. Enter the matching regular expression
3. Enter the replacement text
4. Select where to apply (input / output)
5. Enable the rule

Emotion Sprite Sheets

Emotion sprite sheet functionality allows characters to dynamically switch displayed expressions based on emotions expressed in conversation.

Setup

1. Prepare a set of expression images for the character (e.g., happy, sad, angry, etc.)
2. Upload the expression image set in character settings
3. Label each image with corresponding emotion tags
4. AI will automatically detect emotional tone in replies and switch expressions

SillyTavern Compatibility

Elftia's roleplay system is highly compatible with SillyTavern:

Feature	Compatibility
TavernCard V2 Import/Export	Fully compatible
TavernCard V3 Import/Export	Fully compatible
Character Book	Fully compatible
World Info Format	Fully compatible
PNG Embedded Metadata	Fully compatible
Regex Scripts	Compatible
Emotion Sprite Sheets	Compatible

You can directly use character cards and World Info exported from SillyTavern without format conversion.

FAQs

Question	Solution
PNG import fails	Confirm the PNG file contains valid character data (chara or ccv3 keyword in tEXt chunk)
Character doesn't reply as designed	Check if character description and system prompt are detailed enough, provide more example dialogues
World Info entries don't trigger	Confirm keyword spelling is correct, check if scan depth is sufficient
World Info exceeds token budget	Reduce the number of constant entries or increase token budget
Group chat characters confused	Ensure each character's description is unique enough, avoid personality overlap
Expressions not switching	Confirm expression images are uploaded correctly and labeled with emotion tags
Other apps can't recognize after export	Confirm export format is compatible with target app (V2 has widest compatibility)
Author's note not working	Check author's note depth setting, ensure depth doesn't exceed current message count

Related Links

• Chat — Using roleplay in chat
• LLM Providers — Configuring AI models for RP
• Prompts — Customizing prompt templates