AI Character Cards: What’s Inside the Card File
An AI character card is a JSON file wearing a PNG. The six V1 fields, what V2 adds, and how the ccv3 chunk and .charx archives actually work.
A card is a file, not a picture
The card you download is usually a PNG. That is packaging, not content. Inside the image, stored in a metadata chunk, sits a JSON object describing a character: what they are called, how they speak, where the scene begins, and what they say first. The picture and the character have nothing to do with each other, which is why the same portrait can carry six different people and why a card with no art still works.
Knowing the format is useful even if you never write one. It explains why a bot behaves the way it does: the description was vague, the example dialogue was three words long, the opening message set a tone the rest of the file could not support. It also explains the compatibility complaints. A card that exports as V3 will not load in an app that only reads the V2 chara chunk, and no amount of re-saving the picture will fix that.
| What it is | JSON metadata describing a character, usually embedded in a PNG |
| Core fields | name, description, personality, scenario, first_mes, mes_example |
| V2 adds | data wrapper, alternate greetings, character_book, tags, creator, extensions |
| V3 adds | ccv3 tEXt chunk, and .charx zip archives with embedded assets |
Write the six fields before the picture
The character-sheet skill asks for the same six things a card needs — name, description, personality, scenario, opening line, sample dialogue — and keeps them consistent while you build a story around them.
The format, field by field
Two published specifications define almost everything in circulation: the V2 spec, which added structure to the original six fields, and the V3 spec, which added file formats and embedded assets. Neither is long, and both are worth ten minutes if you plan to write cards seriously.
- description does the heavy lifting — It is where behaviour lives: how the character talks, what they notice, what they refuse. Adjectives alone give a model nothing to act on.
- mes_example teaches the rhythm — The examples are a demonstration, not decoration. Two clipped lines of dialogue produce a clipped bot no matter what the description claims.
- character_book is the lorebook — In V2 the card can carry its own world-info entries — keys, content, insertion order. That is how a card arrives with its setting attached.
- extensions is a namespace — It is mandatory and must default to an empty object. Unknown keys have to survive a round trip, which is why cards written by one app load in another.
V1, V2 and V3 in plain terms
V1 — the six fields.name, description, personality, scenario, first_mes, mes_example. That is the entire original format: a name, a description, a personality note, the situation, the opening message, and some example dialogue. It is still the shape of every card in circulation.
V2 — the wrapper and the extras.
V2 keeps those six inside a data object, adds spec: "chara_card_v2" and spec_version, and adds creator_notes, system_prompt, post_history_instructions, alternate_greetings, character_book, tags, creator, character_version and extensions. The V2 spec was validated in May 2023.
V3 / CCv3 — files and assets.
V3 declares spec: "chara_card_v3", embeds in PNG or APNG as a tEXt chunk named ccv3 whose value is the JSON string, UTF-8 then base64. V2 used a chunk named chara; if an app finds both, it should read ccv3. A .charx file is a zip with card.json at the root and assets referenced as embeded://path/to/asset.png.
What this means for Neta
Neta does not ship a Tavern card exporter, and it does not pretend to. What it has is the same underlying idea in a different container: a character sheet holds the persona, and a lorebook-shaped set of facts holds the world, so a scene can stay consistent without a card file. If you are moving a character between tools, the six V1 fields are the portable part — write those first, and every format becomes a re-export rather than a rewrite. If you only ever play inside one app, the fields still matter, because they are the only part a model actually reads.
See how the fields look when they are filled
Real works on Neta Studio that show the format doing its job: portrait, role, one line that makes the character usable.
Cards as dossiers
Character Profile Card — Nyx and Character Profile Card — Evelyn Nocturne are the same six facts in two layouts — one a character profile, one an archive record. Put them side by side and you can see which field is doing the work in each.
Cards as rules
The Court Card makes the card a character is dealt into a constraint on what they can say, and Casefile: You turns a file about you into the antagonist. Quote Card — Detective Marlowe is the smallest possible card: one line of dialogue carrying the whole persona.
How to write a card that survives twenty turns
Start with the refusal
One line on what this character will not do, and why. It is the highest-leverage sentence in the file, and it is the one most cards leave out.
Write the opening message last
Once you know the voice, the first message writes itself. Doing it first locks you into a tone the rest of the card cannot support.
Test in a different app
Export, import, and say hello. If the character changes, the problem is a field your original app was quietly filling in for you.
The worlds, briefly
The file is portable; the character is not
A card can move between apps. A character only stays itself where the world around it is also remembered. Neta keeps the sheet and the setting together, in a scene you can walk back into.
Built with the character-sheet skill
character-sheet writes the six portable fields and keeps them consistent; holo-card makes the visual card if you want one, with its own layers, rarity border and back. They are different jobs: one writes the character, the other prints it. Neta does not claim to read or write Tavern card files — this page documents the format so you can see what a card is made of.
AI character cards FAQ
Is a character card just an image?
No. The image is the container. The character is a JSON object embedded in a metadata chunk of the PNG — usually the ccv3 chunk in V3, or chara in V2.
What are the six original fields?
name, description, personality, scenario, first_mes and mes_example. Everything added in V2 and V3 sits around that core.
What is the difference between V2 and V3?
V2 defines the data structure — alternate greetings, a character book, tags, creator notes, extensions. V3 defines files: the ccv3 chunk, standalone JSON, and .charx archives with assets inside.
What is a .charx file?
A zip archive with card.json at the root, plus assets referenced through embeded:// paths. It exists because a PNG can only carry so much.
Does Neta export character cards?
No. Neta keeps the persona in a character sheet and the setting in a lorebook-style fact set. The six V1 fields are the part that transfers cleanly if you move a character elsewhere.
Are downloaded cards safe?
Treat a card as untrusted input. They can carry large embedded assets and long instruction fields, and the text inside them is written by whoever made the card, not by the app you load it in.
Keep reading
Platform: Neta Studio · Type: AI Character Cards · Hub: neta.art/app/agent-skills · Works: Character Profile Card — Nyx · Character Profile Card — Evelyn Nocturne · Quote Card — Detective Marlowe · The Court Card · Casefile: You · Magix Origin: Dimension Shift
