Creator docs
Character Card Import Spec
Foreverse imports cards according to the chara_card_v3 spec, with backward compatibility for V1 / V2. This page lists what each of the three container formats supports, how far field compatibility goes, and what to check first when an import fails.
The spec family: v1, v2, chara_card_v3
Character cards are defined by community specs, not by any single app. Three generations matter in practice:
- v1 — the original TavernAI-era card: six flat fields (name, description, personality, scenario, first_mes, mes_example), no version marker.
- v2 — the character-card-spec-v2 envelope (
spec/spec_version/data) plus alternate greetings, system prompt overrides, creator notes, tags, and the embeddedcharacter_book. - v3 — the chara_card_v3 spec: assets (sprites, audio),
nickname, multilingual creator notes, group-chat greetings, lorebook decorators, and the.charxzip container. Backward compatible with v2 by design.
SillyTavern is the reference implementation most cards are authored against; its documentation is the best companion reference for authoring behavior. Foreverse imports all three generations and follows v3 semantics where the generations disagree.
Container formats
| Format | Notes |
|---|---|
| PNG steganographic card | Reads card data from PNG text chunks; the ccv3 chunk takes priority over the older chara chunk. Note: images forwarded through WeChat and similar apps may be recompressed and lose text chunks. Confirm you have the original image before importing |
| JSON file | Raw V1 / V2 / V3 JSON can be imported directly |
.charx (V3 zip container) | Parses card.json plus embedded assets: icon (name=main takes priority as avatar), emotion / expression -> expression sprites, background -> immersive background, and the rest as misc; recognized by zip magic bytes or the .charx suffix |
Field compatibility
- V1 / V2 core fields (description, personality, scenario, first_mes, mes_example) are fully supported.
- V3 additions:
nickname(used before name for chat addressing), alternate greetings (switchable on the chat page), embedded worldbook (character_book, including V3 decorators; see the Worldbook spec for semantics), and embedded regex scripts. - Unrecognized V3 extension fields inside the card are preserved during import and won't be lost.
- If
first_mesis empty and alternate greetings exist, the first alternate greeting is used as the opener.
Group chat JSON
Foreverse can import group chat JSON exported by desktop Tavern: member cards, speaking-order strategy (natural / ordered / random), and group settings come in together. The corresponding member character cards must already be in your library; missing members are listed in the import report.
Import failure checks
- PNG import does nothing: most likely the image was recompressed by a forwarding channel and its text chunks are gone. Ask the author for the original file, or use JSON / .charx.
- JSON reports a format error: check whether the file is UTF-8 and whether a download tool truncated it.
- Import succeeds but the worldbook doesn't work: see the trigger checklist in the Worldbook spec.
- V3 card behaves differently in another app: V3 decorators are ignored by apps that only support V2. That difference is expected.
More troubleshooting cases are in the blog: 9 reasons character card import fails.