Goony.ai —

What is a character card? V2, V3 and PNG cards explained

A character card is a portable AI character: JSON fields, usually hidden inside a PNG. The V1, V2 and V3 formats, field by field, and how apps use them.

Updated Oct 29, 2026 · 8 min read

In this article
  1. Where the format came from
  2. Every field, and what apps do with it
  3. What a V2 card looks like inside
  4. How a card hides inside a PNG
  5. V2 vs V3 at a glance
  6. Lorebooks, briefly
  7. Which apps read character cards
  8. Where card fields land on Goony
  9. FAQ

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.

Characters to try

Try Goony.ai

Chat with any character for free — 20 messages a day, no card needed. Create your own or import one from the community.

Keep reading