A character card is a portable file that holds an AI roleplay character's definition (name, description, personality, scenario, first message and example dialogue) as JSON, usually hidden inside the character's PNG portrait. The format began as the informal "Tavern card" (now called V1), was formalized as Character Card V2 in May 2023, and was extended by V3, which adds assets and a zip format called CHARX. SillyTavern, RisuAI, Agnai and Chub all read it, and so do several hosted chat sites.
Because the definition travels with the file, a card lets you take a character from one app to another, share it, or keep it safe outside any single site.
Where the format came from
"Tavern card" comes from TavernAI, the app SillyTavern was forked from in February 2023. Cards spread through card-sharing sites before anyone wrote the rules down, which is why the V2 proposal describes V1 as "the format currently in use across the character card ecosystem as of May 4th 2023" (V2 spec repository).
V2 was marked "Spec approved" on 17 May 2023. It wrapped the original six fields in a data object, added a version marker, and brought in new fields: alternate greetings, a system prompt, a lorebook, tags and more. The projects it was written for include SillyTavern, RisuAI and Agnai.
V3 was written by the developer of RisuAI (V3 spec). It keeps the V2 fields and adds typed assets (icons, backgrounds, emotion images), a nickname, multilingual creator notes, a source list, greetings for group chats, timestamps, a reworked lorebook, and CHARX, a zip package for cards with many files.
Every field, and what apps do with it
The "in the prompt" column follows the V2 and V3 specs and SillyTavern's character design docs. Other apps build their prompts their own way, but most follow the same logic.
| Field | Since | What it's for | In the prompt? |
|---|---|---|---|
name |
V1 | The character's name; fills the {{char}} placeholder | Yes |
description |
V1 | The main definition: who they are, look, history, behavior | Every reply |
personality |
V1 | A short personality summary | Every reply |
scenario |
V1 | The situation the chat starts in | Every reply |
first_mes |
V1 | The opening message | Once, as the first message |
mes_example |
V1 | Example dialogue, each block starting with <START> |
Until chat history fills the context |
creator_notes |
V2 | Notes for people reading the card | Never: the spec says it "MUST NOT be used inside prompts" |
system_prompt |
V2 | Replaces the app's main instructions; {{original}} keeps them | Yes, where supported |
post_history_instructions |
V2 | Instructions placed after the chat history | Yes, where supported |
alternate_greetings |
V2 | Extra openers you can swipe between | The one you pick |
character_book |
V2 | A lorebook of keyword-triggered entries | Only entries whose keywords appear |
tags |
V2 | Sorting and filtering | No |
creator, character_version |
V2 | Credit and version | No |
extensions |
V2 | App-specific data | Depends on the app; editors must keep it intact |
nickname |
V3 | Replaces {{char}} in prompts when set | Yes |
assets |
V3 | Icon, background, user icon, emotion images | No, display only |
creator_notes_multilingual |
V3 | Creator notes per language | No |
source |
V3 | IDs or links to where the card came from | No |
group_only_greetings |
V3 | Greetings used only in group chats | In group chats |
creation_date, modification_date |
V3 | Unix timestamps | No |
Three of those rules shape how a card behaves in practice:
- Permanent fields cost you memory. SillyTavern sends the name, description, personality and scenario with every reply. Its docs give the example that, with a 2,048-token context, "a 1000-token character definition cuts the AI's 'memory' in half."
- Example dialogue is temporary. Examples stay in the prompt only while there's room, and drop out block by block as the chat grows.
- The first message sets the style. Models tend to copy its length and tone, so it shapes every reply after it.
What a V2 card looks like inside
Here is a small, complete V2 card. Every field under data is a string except the arrays and the extensions object.
{
"spec": "chara_card_v2",
"spec_version": "2.0",
"data": {
"name": "Mara Quill",
"description": "Mara Quill, 34, captain of the smuggling sloop Kestrel. Sharp, dry, fiercely loyal to her crew. Owes the harbor guild more than she admits.",
"personality": "Wry, guarded, brave when it counts.",
"scenario": "A rainy night in a busy port. Mara needs one more hand for a run past the blockade.",
"first_mes": "*Mara looks you over from the end of the pier.* \"They say you can read a tide chart. Prove it.\"",
"mes_example": "<START>\nYou: Where are we headed?\nMara: Somewhere the guild can't count my cargo.",
"creator_notes": "Adventure card. Works best with a slow start.",
"system_prompt": "",
"post_history_instructions": "",
"alternate_greetings": ["*The Kestrel's deck is empty except for Mara, mending a sail.* \"You're late.\""],
"tags": ["adventure", "pirates"],
"creator": "example",
"character_version": "1.0",
"extensions": {}
}
}
In real cards, example lines usually begin with the {{char}} and {{user}} placeholders rather than names, so the card keeps working if you rename the character. A V3 card has the same shape with "spec": "chara_card_v3", "spec_version": "3.0" and the extra V3 fields.
How a card hides inside a PNG
The JSON above, base64-encoded, sits in a text chunk of the portrait PNG: a chunk named chara for V2, ccv3 for V3. The V3 spec says an app that finds both should use ccv3, and SillyTavern writes both when it exports a PNG. The image and the card are separate parts of the same file, so a screenshot or a JPG conversion keeps the face and loses the character. If that's happened to you, our guide to a card PNG that won't import shows how to check a file and get a working copy.
V2 vs V3 at a glance
| V2 | V3 | |
|---|---|---|
| Spec string | chara_card_v2, version 2.0 |
chara_card_v3, version 3.0 |
| PNG chunk | chara |
ccv3 (a chara copy may sit alongside) |
| File types | PNG, JSON | PNG, JSON, CHARX (zip with card.json) |
| Assets | One portrait | Icons, backgrounds, emotion images and more |
| Lorebook | Keyword entries | Adds decorators (@@depth, @@activate and others) and required regex flags |
| Group chats | No special field | group_only_greetings |
| Compatibility | Widely read | Newer; some apps read V3 but write V2 |
If you're picking a format to keep or share, a V2 PNG plus a JSON copy is the safest bet today. SillyTavern's JSON export is V2, while RisuAI can export either version and CHARX (source).
Lorebooks, briefly
A lorebook (character_book) is a list of entries, each with trigger keys and content. When a key shows up in the conversation, the entry's content is added to the prompt; otherwise it stays out and costs nothing. That's the right place for world details, side characters and history that only matter some of the time. Entries can also be marked constant (always in), given an insertion_order, a priority, or secondary keys. Chub's editor calls it the Character Book; SillyTavern calls its version World Info and embeds it in the card on export.
Which apps read character cards
- Frontends you run or open yourself: SillyTavern (PNG, JSON, YAML, CHARX and more, plus links from six card sites), RisuAI (PNG, JSON, CHARX), Agnai (JSON or image).
- Card hubs: Chub's character pages offer PNG and JSON downloads, and its editor is where many cards are written.
- Hosted chat sites: SpicyChat, PolyBuzz and OurDream import PNG or JSON cards; Joyland's web app shows card import; Muah's app code reads V2 cards without documenting it.
- Goony: imports by link or ID from chub.ai, JanitorAI, AICharacterCards.com, Perchance, RisuRealm and TelegAI, and reads V2, V3, Risu and Perchance formats on its server. It has no file upload. The step-by-step is in our guide to importing a character card, and our guide to moving characters has a platform-by-platform table.
Where card fields land on Goony
Goony's character creator doesn't have one box per spec field. Here's how a card maps onto it.
| Card field | On Goony |
|---|---|
name |
Name |
description, personality, scenario, mes_example, system_prompt |
The character prompt (up to 4,000 characters in the creator). On import, Goony builds this prompt from the card's fields, and you can edit it before saving |
first_mes, alternate_greetings |
Opening scenarios (up to five in the creator) |
| Portrait | Portrait upload |
character_book |
No lorebook field: move the essentials into the prompt |
tags, creator_notes |
No equivalent in the creator |
| Not in the spec | Tagline, gender, style (anime or realistic), a structured sheet with an age of 18 or over, and an NSFW toggle |
The creator saves characters in your browser and needs no account; chatting needs a free one. Characters you create or import locally, and your Offline chats, live in your browser, not in Goony's database. Each reply is still generated on Goony's servers. Every character on Goony is an adult, and imported cards are checked against its content policy. To see what a finished character feels like before you write your own, the hand-made cast is on the home page, Kiri included at her chat.
FAQ
Is a Tavern card the same as a character card?
Yes. "Tavern card" is the older name, from TavernAI, for the same format. A Tavern card today usually means a V2 card, and most apps that read cards accept both V1 and V2.
What's the difference between Character Card V2 and V3?
V2 wraps the original fields in a data object and adds greetings, a system prompt, a lorebook and tags. V3 keeps all of that and adds assets, a nickname, multilingual notes, group-only greetings, timestamps, lorebook decorators and the CHARX zip format, stored in a ccv3 PNG chunk.
Can a JPG or WebP be a character card?
Not a standard PNG card. The card lives in a PNG text chunk, and converting the image to JPG or WebP throws it away. Keep the original PNG, or a JSON copy.
Which fields matter most?
The description, the first message and the example dialogue. The description is sent with every reply, the first message sets the style of every reply after it, and the examples teach the character's voice.
What is a lorebook in a character card?
A list of entries with trigger keywords. When a keyword appears in the chat, that entry is added to the prompt, so world details only take up space when they're relevant.
Do I need special software to make a character card?
No. Card editors such as Chub's creator or SillyTavern export PNG and JSON, and a JSON card is plain text you could write by hand. On Goony, the creator builds a character without any file at all.




