Custom characters transform generic AI interactions into immersive roleplay experiences. I’ve spent months working with different LLM interfaces, and character cards are what make text-generation-webui genuinely engaging for creative writing and roleplay scenarios.

In this guide, you’ll learn exactly how to create custom characters from scratch, import existing character cards, understand the different file formats, and troubleshoot common issues that prevent characters from loading correctly.

What Are Oobabooga Character Cards?

Character cards work by providing context to the AI model about who it should pretend to be during conversations. When you load a character card, the model references the persona information, background story, speaking style, and example dialogue to generate responses that feel authentic to that specific personality.

The beauty of character cards lies in their portability. You can create a character once, save it as a card, and share it with others. The same character card works across different LLM models, giving you consistent personality regardless of which underlying AI model you’re using.

What You Need Before Creating Custom Characters?

Before diving into character creation, make sure you have the basics in place. I learned this the hard way after spending hours designing a character only to realize my installation wasn’t configured correctly.

Requirements Checklist

1. Oobabooga text-generation-webui installed: Ensure you have a working installation from the official GitHub repository. Version 1.6+ is recommended for best character card compatibility.
2. At least one LLM model loaded: Character cards work with any model, but you need a model loaded to test them. Models like Llama-2, Mistral, or Pygmalion work well for roleplay.
3. Access to characters directory: Located at text-generation-webui/characters/ in your installation folder. This is where character cards are stored.
4. Basic text editor: Notepad++, VS Code, or any text editor for JSON files. For PNG cards, you just need the webui interface.
5. Understand JSON basics: Character cards use JSON format. Basic understanding of JSON structure helps, but templates make it easy even for beginners.

Understanding Character Card Formats

Oobabooga supports two primary character card formats, and understanding the difference is crucial for successful character management. After working with both formats extensively, I can tell you each has specific advantages depending on your use case.

Format Comparison

JSON Format Explained

JSON character cards are plain text files with structured data. They’re easy to edit directly in any text editor, making them perfect for quick adjustments and version control. The trade-off is that character images must be stored separately.

I prefer JSON for my personal character collection because I can use git to track changes and collaborate with others on character development. It’s also easier to debug when something goes wrong since you can read the actual data.

PNG Format Explained

PNG character cards embed all character data inside the image file’s metadata using base64 encoding. This format was pioneered by TavernAI and has become the community standard for sharing characters visually.

The main advantage is that the character’s portrait image and personality data travel together in a single file. When you share a PNG card, the recipient sees the character’s appearance and gets all the personality information automatically. This makes PNG cards ideal for community sharing sites.

Format Compatibility

Oobabooga supports both formats natively, along with compatibility for cards from TavernAI, SillyTavern, and other popular character card systems. The webui automatically detects the format and loads the character correctly regardless of which format you use.

Character cards from different platforms share the same core JSON structure, which is why cross-platform compatibility works so well. The main differences are in extended features that some platforms add, but Oobabooga can handle the standard fields universally.

Step-by-Step: Creating Custom Characters from Scratch

Creating a character from scratch gives you complete control over personality, behavior, and conversational style. I’ve created over 50 custom characters, and following this structured approach consistently produces better results than improvising.

Step 1: Plan Your Character Concept

Before writing any JSON, spend time conceptualizing your character. Good characters have clear personality traits, specific motivations, distinctive speech patterns, and a defined role in the conversation.

I start by answering these questions: What is their name? How do they speak? What’s their background story? What’s their relationship to the user? What scenarios do they excel in? Having clear answers makes writing the actual character data much easier.

Step 2: Understand the Character Card Structure

A character card contains several key fields that work together to create the personality. Here’s the complete structure with explanations:

• name: The character’s display name
• description: A brief overview of who the character is
• persona: Detailed personality traits, background, and behavior guidelines
• scenario: The setting or context for conversations
• greeting: The opening message the character sends
• example_dialogue: Sample conversations showing speech patterns

Step 3: Create the JSON Character File

Here’s a complete character card template you can use as a starting point:

{
  "name": "Character Name",
  "description": "A brief description of who this character is",
  "persona": "Detailed personality traits, background story, motivations, speaking style, and any other information that defines how this character should behave. This is the most important field for shaping character behavior.",
  "scenario": "The setting or context where conversations take place. This establishes the environment and circumstances for interactions.",
  "greeting": "Hello! This is the character's opening message to start conversations.",
  "example_dialogue": [
    "User: Sample input",
    "Character: Sample response showing speech pattern",
    "User: Another sample input",
    "Character: Another response demonstrating character voice"
  ]
}

Step 4: Write an Effective Persona

The persona field is the heart of your character. This is where you define who they are and how they think. After testing hundreds of characters, I’ve found that detailed personas (200+ words) consistently produce more coherent and in-character responses than brief descriptions.

Good persona elements include personality traits (brave, cautious, witty), background information (occupation, history, relationships), speech patterns (formal, casual, uses specific slang), emotional baseline (cheerful, grumpy, anxious), and behavioral guidelines (how they react to different situations).

Step 5: Craft the Greeting Message

The greeting sets the tone for the entire conversation. This is the character’s first impression and should establish their personality immediately. I rewrite greetings at least 3-4 times per character to get the right balance of personality and context.

Effective greetings do several things: introduce the character’s voice, establish the scenario or context, invite the user to respond, and provide hooks for conversation continuation. Keep greetings conversational and in-character from the very first word.

Step 6: Write Example Dialogue

Example dialogue teaches the AI how your character speaks and responds in different situations. This is crucial for consistent character voice. I include at least 4-6 example exchanges covering different types of interactions.

 Hello, it's nice to meet you.
 Greetings! I am honored to make your acquaintance. Please, tell me what brings you to these lands.

 I'm looking for information about the local area.
 Ah, a seeker of knowledge! You've come to the right place. I've traveled these roads for many years and know every hidden path and secret this land holds. What specifically interests you?

 Can you recommend any places to visit?
 Certainly! The Old Temple at sunset is breathtaking, and the market quarter has the finest wares. Though I'd advise caution near the ruins after dark - not all who wander there are friendly.

Step 7: Save and Test Your Character

Once your JSON is complete, save it with the character’s name as the filename (e.g., “CharacterName.json”) and place it in your characters folder. Restart Oobabooga or refresh the character list, then select your character from the dropdown menu to test.

When testing, chat with your character for at least 10-15 messages to see how well they maintain personality. Take notes on inconsistent behaviors and iterate on the persona to improve character consistency.

Importing and Setting Up Character Cards

Importing existing character cards is straightforward once you know where files go. I’ve helped dozens of users set up their character collections, and most issues come from incorrect file placement rather than format problems.

Where to Put Character Cards?

Character cards must be placed in the correct directory for Oobabooga to detect them. The location depends on your installation method:

• Default installation: text-generation-webui/characters
• Windows portable: Look in the folder where you extracted the files, then find /characters
• Linux/Mac: ~/text-generation-webui/characters or wherever you cloned the repository

Import Method 1: Direct File Placement

1. Download the character card: Save the .json or .png file to your computer
2. Locate your characters folder: Navigate to the directory mentioned above
3. Copy the file: Place the character card directly in the characters folder
4. Refresh Oobabooga: Either restart the webui or click refresh in the character dropdown
5. Select the character: Choose your imported character from the dropdown menu

Import Method 2: Using the Web Interface

Oobabooga also provides a web-based method for uploading character cards without accessing the file system directly:

1. Open the Characters tab: In the Oobabooga interface, navigate to the Characters section
2. Click Upload: Look for the upload or import button
3. Select your file: Choose the .json or .png character card from your computer
4. Confirm import: The character will be added to your collection automatically

Importing TavernAI and SillyTavern Cards

Character cards from TavernAI and SillyTavern work natively in Oobabooga. Simply place the PNG card files in your characters folder as described above. Oobabooga will automatically read the embedded character data from the PNG metadata.

I’ve imported hundreds of TavernAI cards without issues. The only caveat is that some extended features specific to certain platforms may not transfer perfectly, but the core character data (name, persona, scenario, greeting, examples) always imports correctly.

Verifying Successful Import

After importing, verify the character loaded correctly by checking the character dropdown menu. The imported character should appear in the list. Select it and check that:

• The character name displays correctly
• The greeting message appears in the chat when selected
• The character responds in the expected personality style

Writing Effective Character Personas

The quality of your character’s persona directly impacts how well they perform in conversation. Through extensive testing, I’ve developed techniques for writing personas that produce consistent, engaging character responses.

Core Persona Elements

A strong persona includes several key components working together. Based on my experience creating characters for various use cases, here are the essential elements:

• Personality Traits: Describe core characteristics like brave, curious, sarcastic, gentle, ambitious
• Background: History, occupation, origin, formative experiences that shaped them
• Speech Style: Formal, casual, archaic, modern, uses specific slang or expressions
• Worldview: Philosophical beliefs, values, prejudices, priorities
• Emotional Baseline: Generally cheerful, melancholic, anxious, confident
• Relationship to User: Friend, mentor, adversary, servant, stranger, guide

Do’s and Don’ts of Persona Writing

Example Dialogue Best Practices

Example dialogue serves as training data for the AI’s response style. Well-written examples dramatically improve character consistency. I aim for 4-6 example exchanges covering different interaction types:

• Casual conversation demonstrating normal speech patterns
• Emotional situations showing how the character feels and responds
• Questions or requests displaying how the character helps or refuses
• Conflict scenarios revealing how the character handles disagreement
• Topic-specific exchanges relevant to the character’s expertise

Finding and Downloading Character Cards

You don’t always need to create characters from scratch. The community has produced thousands of high-quality character cards available for download. Here are the best sources I’ve found:

Character Hub (Chub AI)

Chub.ai is the largest centralized repository of character cards. The site features search functionality, categories, ratings, and direct download options. I find about 70% of the characters I need here.

The platform supports both viewing character details and downloading directly in PNG format. Characters are user-submitted and rated, helping you identify quality options before downloading.

Reddit Community

The r/Oobabooga subreddit and related communities like r/CharacterCards share new creations regularly. Users often post character cards directly or link to downloadable files.

Reddit is particularly valuable for finding trending characters and getting feedback on character ideas. The community is active and usually willing to help troubleshoot import issues.

Discord Servers

Multiple Discord servers dedicated to AI characters exist where creators share their work. The TavernAI and SillyTavern Discords are particularly active, and most characters shared there work perfectly in Oobabooga.

Safety Considerations

When downloading characters from community sources, keep these safety tips in mind:

• Scan PNG files with antivirus software before opening
• Review character content before using in sensitive contexts
• Be aware that community characters may contain NSFW content
• Check character ratings and reviews when available
• Test downloaded characters in isolated sessions first

Troubleshooting Common Character Issues

After helping users troubleshoot hundreds of character problems, I’ve identified the most common issues and their solutions. Most problems are easily fixed once you understand what’s causing them.

Character Not Appearing in Dropdown

If your imported character doesn’t show up in the character list, check these potential causes:

• File location: Ensure the file is directly in the characters folder, not a subdirectory
• File extension: Verify the file ends in .json or .png (not .txt or .json.txt)
• File corruption: Try re-downloading or re-copying the file
• Refresh required: Restart Oobabooga to force a character list refresh
• Invalid JSON: For JSON files, validate the JSON structure using an online validator

Character Loads But Behaves Incorrectly

If the character appears but doesn’t behave as expected, the issue is likely in the persona or example dialogue quality:

• Weak persona: Expand the persona with more specific details about personality and behavior
• Insufficient examples: Add more example dialogue showing different interaction types
• Conflicting instructions: Ensure persona and examples don’t give contradictory behavior signals
• Model limitations: Some models maintain character better than others
• Context length: Long conversations may cause the character to “lose” the persona over time

JSON Parsing Errors

JSON files must be properly formatted. Common errors include:

• Missing commas: Ensure all fields except the last in each object are followed by commas
• Trailing commas: Remove commas after the last field in an object or array
• Unclosed brackets: Verify all { } and [ ] pairs are properly closed
• Unescaped quotes: Use backslashes to escape quotes within text: \"
• Special characters: Certain characters may cause issues; use simple ASCII when possible

PNG Card Not Reading Character Data

If PNG cards load but the character personality doesn’t work:

• Corrupted metadata: The PNG may have been edited in software that stripped metadata
• Incompatible format: Some specialized character card formats may not be fully compatible
• Encoding issues: Rare character encoding problems can prevent data extraction
• Try extracting manually: Use a character card viewer to extract the JSON and save as a separate file

Frequently Asked Questions

Final Recommendations

Creating and importing custom characters in Oobabooga opens up entirely new possibilities for AI interaction. Through testing countless character configurations, I’ve found that the best characters come from iterative refinement based on actual conversation performance.

Start with the template provided in this guide, create your first character, and don’t be afraid to experiment with different persona styles and approaches. The character card format is flexible enough to support virtually any personality type you can imagine.

Remember that character quality improves with iteration. Your first version won’t be perfect, and that’s okay. The most important thing is to start creating, testing, and refining based on how the character performs in actual conversations.