Character Card Format Guide
Character cards are structured files, not just short descriptions. A card can include persona text, scenario, first message, example dialogue, alternate greetings, image metadata, tags, and tool-specific fields.
This guide focuses on format and compatibility. For the feature workflow around importing, editing, and organizing cards, use Character Cards in Tavern Studio.
What a character card contains
A useful card usually includes:
- name;
- description or persona;
- scenario;
- first message;
- example dialogue;
- optional alternate greetings;
- avatar or PNG image data;
- metadata used by the importing app.
Not every format stores fields in the same way. That is why a card can work in one tool but behave differently after import.
Character card format basics
The key format question is whether the card data is present and readable. PNG cards may embed structured data inside an image. JSON cards expose the structure directly. Some cards also include fields created by a specific editor or community tool.
If a card imports incorrectly, check whether the expected fields are present before changing model or API settings.
Templates and required fields
A template helps users keep role, tone, and opening behavior consistent. A simple template should separate:
- who the character is;
- what situation the chat starts in;
- how the character speaks;
- what the user should see first;
- any constraints the model should remember.
Avoid hiding everything in one long description. Clear fields are easier to edit, test, and migrate.
PNG metadata and import behavior
PNG character cards can fail in subtle ways. The image may display correctly while the embedded data is missing, encrypted, malformed, or stored in a field Tavern Studio does not recognize.
When troubleshooting:
- Try another known-good card.
- Check whether the same card opens in the original tool.
- Export a JSON copy if available.
- Remove unsupported or tool-specific fields only after making a backup.
Formatting descriptions and first messages
Formatting affects behavior. A long character description may crowd out the current scene. A first message may force a tone that does not fit later chats. Example dialogue may be useful, but too much example dialogue can overconstrain the model.
Review the card in this order:
- Description.
- Scenario.
- First message.
- Example dialogue.
- Alternate greetings.
- Linked world book or preset assumptions.
Alternate greetings and conversation starts
Alternate greetings are not product alternatives. They are optional first-message variants that let a user start a scene in different ways.
If you are setting up alternate greetings, treat them as first-message variations for a character rather than as part of a product comparison.
Common format mistakes
Common problems include:
- the first message is missing;
- persona and scenario are mixed together;
- example dialogue is too long;
- alternate greetings contradict the main first message;
- the card assumes a preset that is not active;
- the card relies on a world book that was not imported.
Importing formatted cards into Tavern Studio
After import, test a card with a short conversation before editing the whole library. If behavior differs from the original setup, compare the card format, preset, world book, and model route.
Format issues should be fixed at the card level. API errors should be handled in Troubleshooting API Errors.