Character Card V1, V2 and V3 explained

A card is JSON hiding inside a PNG

A PNG file is a sequence of chunks. Some hold pixels; a tEXt chunk holds a keyword and a string, and nothing stops that string from being an entire character. That is the whole mechanism. A character card PNG carries a chunk with the keyword chara whose value is the card's JSON, base64-encoded so it survives a text-only field. Version 3 added a second chunk, ccv3, holding the V3 form of the same card.

Readers prefer ccv3 when it is present and fall back to chara, which is why a well-made V3 card still opens in a V2-only app: both chunks are written, and each reader takes the one it understands. LoreChat follows that order, and when it writes a PNG it writes both chunks fresh, dropping any stale copies first. If neither chunk is there, the file is just a picture, and you get "No character data found in this PNG".

Because the card is text and the picture is pixels, anything that re-encodes the image destroys the card. This is not a bug in the format so much as an unavoidable consequence of hiding data in a container that image tools feel free to rebuild.

The JSON envelope

V1 has no envelope. A V1 card is a bare object with name, description, personality, scenario, first_mes and mes_example at the top level, and that is all it is.

V2 introduced a wrapper so that readers could tell versions apart: spec is the string chara_card_v2, spec_version is 2.0, and every field lives under a data object. V3 keeps the same shape with spec set to chara_card_v3 and spec_version 3.0. Parsers that see an unfamiliar spec but a data block with a name in it can usually treat the card as V2 and be right, which is what LoreChat does before giving up.

• V1: bare object, name at the top level
• V2: { spec: "chara_card_v2", spec_version: "2.0", data: { ... } }
• V3: { spec: "chara_card_v3", spec_version: "3.0", data: { ... } }

The fields, one line each

These are the fields a card can carry. The first six exist in every version; the rest arrived with V2 or V3.

• name — what the character is called; substituted wherever {{char}} appears.
• description — the main block of character information, sent with every request.
• personality — a short summary of temperament, historically a one-line companion to the description.
• scenario — the situation the story opens in, and the setting the model should hold to.
• first_mes — the character's opening message, shown before you type anything.
• mes_example — sample exchanges that demonstrate voice and formatting, usually split into <START> blocks.
• alternate_greetings — additional opening messages you can pick between instead of first_mes.
• character_book — an embedded lorebook whose entries are injected when their keys appear in recent messages.
• creator_notes — notes for the human importing the card, never sent to the model.
• system_prompt — a prompt the card suggests should replace the app's default system prompt.
• post_history_instructions — instructions the card wants placed after the chat history, closest to the reply.
• tags — free-form labels used for browsing and search.
• creator — who made the card.
• character_version — the card author's own version string, for tracking revisions.
• extensions — an open object where apps store their own data without colliding.

What V2 added

V1 was a prompt in six fields. V2 turned the card into a document with metadata and machinery. alternate_greetings made a card replayable, since a second or third opening can put the same character in a different room. character_book embedded a lorebook in the card itself, so world detail could be injected on demand instead of bloating the description on every single request.

The rest of the additions are about control and provenance. system_prompt and post_history_instructions let a card author influence how the request is assembled, not just what it contains. creator_notes gave authors a place to write to the human rather than the model. tags, creator and character_version made cards browsable and versionable, which is what let sites like Chub become catalogues rather than file dumps. extensions gave every app a sanctioned place to stash its own fields.

What V3 added

V3's most visible change is the ccv3 PNG chunk, which lets a file carry a V3 card and a V2 card side by side. Beyond that it is mostly enrichment: assets lets a card reference more than one image, such as alternate portraits or expression sets; nickname gives a shorter name for use in prompts; source records where the card came from; creation_date and modification_date add real timestamps; and greetings can be marked as group-only, meaning they are offered when the character joins a multi-character scene rather than a one-to-one chat. The lorebook picked up decorators and finer activation controls in the same revision.

LoreChat reads V3 cards and keeps the V2 core: the fields listed above, plus the whole character_book. The V3-only extras — assets, group-only greetings, nickname, source, the creation and modification dates — are not used by the chat, so a V3 card behaves exactly like a well-filled V2 card here. Nothing errors, and nothing is silently misread; those fields simply have no effect on the story.

Which fields LoreChat actually uses

Name, description, personality, scenario, first message and example dialogue are assembled into the prompt for every reply. Alternate greetings are offered when a chat starts. The lorebook is scanned against the last few messages — scan_depth messages, 4 if the card does not say — and matching entries are inserted at their chosen position within a token_budget that defaults to 2048. Constant entries are always included; selective entries need a secondary key to match as well as a primary one. Keys written as /pattern/flags are treated as regular expressions for cards you imported yourself.

Creator notes, tags, creator and character version are shown to you rather than to the model: they are how you tell two versions of the same character apart six months later. When you export from the editor you can write the card back out as V2 JSON, V3 JSON, or a PNG carrying both chunks, so a card that arrives here can leave again without losing anything it came with.

FAQ