Avatars and character-card import

Reusable avatars

Player avatars live under the roleplay root rather than inside one world. Create and edit them from the Avatars page. A world can copy selected avatars into its playable cast, or a player can bring avatars only into a new session without changing the world.

Copies are independent. Later edits to the reusable avatar do not rewrite worlds or existing sessions.

Use a reusable avatar for the stable parts of a player character: name, pronouns, appearance, voice, personality and a portable background. Keep world-specific relationships, local knowledge, possessions and starting location in the world or session copy. This prevents an avatar brought into several settings from carrying impossible knowledge between them.

World copy or session-only copy?

• Copy an avatar into a world when it belongs to that world's designed cast and should be offered in every future session.
• Add an avatar to a new session when one player wants to bring it into a particular run without changing the world.
• Edit the resulting copy when the setting needs a local variation. The reusable source remains unchanged.

Character cards

The importer accepts a supported character card, extracts its text and pictures, and asks an import agent to map the material into the native character format. Imported pictures enter the world's image library when they can be fetched and validated.

The importer also carries what a character knows of the world's places, things and the ways between places, gives the characters a card names in someone's relationships a plain acquaintance back, and lets each character know the lore that is about them.

Use Import without a model when no model is configured or when you want a direct conversion. It copies the card's character, lorebook, instructions and chosen opening without asking an assistant to interpret them. The lorebook remains visible only to the game master, and the instructions become the narration style. This route does not identify places, factions or other people. It finishes the world immediately, or keeps it as a draft when it cannot start. You can fill in the missing parts yourself or ask an assistant later.

If the finished import would not yet start a story (for example a character refers to a place that was not written), the world is still written, as a draft: its card shows a Draft tag, it cannot be played, and the assistant repairs it in the same turn, checking with check_world and reading the original card to restore what a reference was meant to point at. If it cannot, the world's editor shows what is wrong and three choices: Ask the assistant to repair it again, Keep as it is (an ordinary world that has to be mended by hand), or Discard (the folder moves to the trash folder of the roleplay root). A draft you or the assistant have mended turns into an ordinary world by itself. An import that stopped (a server restart, a chat that ended early) can carry on from where it was.

Some cards have no cast of their own: a narrator-only card, an open world, a scene. Their characters are made up while the story is played, from templates, tables or a mechanism the card describes. The importer keeps that guidance as game-master lore in the card's own words, so the game master and the world author read it when someone new is needed (they follow its pools of kinds and the fields it asks a profile to have). Such a world has no playable character of its own: bring one of your avatars when you start a session.

To give a world the narration style of a SillyTavern prompt preset, use Import narration preset in the world's editor header: the authoring assistant turns the preset's instructions into the world's narration and character-style prompts and asks you before replacing them. Rules of the game, formats and scripts in a preset are not carried.

Review imported data before play. Character cards rarely distinguish public facts, private state, stable appearance, starting activity and long-term goals as precisely as the native model does.

During review, pay particular attention to:

• facts that other characters may safely see versus secrets for inner_state or explicit knowledge;
• prose instructions that describe a chatbot response style rather than a person in a world;
• example dialogue that should become speech guidance rather than current dialogue;
• appearance details that are stable enough for visual identity;
• goals and starting activity, which give the character something to do when play begins;
• imported names or IDs that conflict with the existing cast.

An import is a draft, not a live compatibility layer. After conversion, the native character files and copied images are authoritative; changing the original card does not update them by itself.

A newer version of a card

A world that was imported from a card can be brought up to date with a newer version of that card, without running the import again. There are two ways in:

• Import the card as usual with Import card on the Worlds page, or choose one from the catalogue. If a card-imported world has the same name, the review page offers Update "name" from this card beside Import as a new world. A renamed card can update any card-imported world: choose Update another world, then select it from the list.
• You can also open a card-imported world and choose Update from card in its header. Select a PNG or JSON card, and the review opens with that world selected. This route is useful for a card stored on disk and does not involve the catalogue.

An update does not run the import again. Before anything changes, the plugin keeps a copy of the world as it is. The new card is kept in the world's .import/update folder, the world's authoring chat opens, and the assistant is told to bring the world up to date:

1. card_diff shows what changed between the two cards, worked out by the plugin: for each changed piece (field, greeting or lorebook entry) the sentences that differ, plus pieces that were added or dropped. Each changed piece lists the characters, places and things the import made from it, and a dropped piece lists which of them it alone made. It also lists what the card changed about the world itself.
2. The assistant reads the pieces it needs with card_read (version current is the old card, new the new one) and changes only what the new card changed, with its ordinary editing tools. A character, place or thing is edited like any other; what the world says about itself (description, tags, the opening and the other openings) is edited with edit_world_info. Each edit goes through the approval like any other, with the change shown. What was made only from a dropped piece is removed (the folder goes to the world's .trash) unless you edited it since the import.
3. card_update_finish makes the new card the world's source (the old one stays in .import/previous), notes the world's files as the new starting point for telling edits apart, replaces the world's portrait if it is still the picture that came with the old card and the new card has another, and fetches the picture addresses the world does not have yet. That includes addresses that failed last time for a reason that may have passed (a timeout, a server error); a picture the library already holds is recognised by the picture itself, not the file, so a mirror address does not add a second copy. Pictures from addresses the new card dropped stay in the library, and the assistant tells you which.

Only changed pieces cost anything, so a small card update costs a fraction of an import. The default depends on whether you have edited the world since its import (the plugin keeps a fingerprint of the world's files when the import's review ends; pictures do not count):

• If the world has the card's name and has not been edited, Update is preselected.
• If the world has been edited, Import as a new world is preselected. You can still update it. The assistant sees which files changed and is told to preserve those edits.
• For a world imported before fingerprints were recorded, the plugin cannot tell whether it changed and preselects a new world. You can still choose the update route, which asks the assistant to inspect the world before editing it.

An update keeps the world's name, and sessions already started from the world keep their own copy of it, so an update never changes them: start a new session to play the updated world.

If the result is not what you wanted, Undo card update in the world's header returns the world to what it was before the update, and restores the card it was made from. What the world held at that moment is moved to its .trash folder, so edits made after the update are still there to find. Pictures are not part of this.

Import limits, concurrency, reasoning effort, token budget and temperature are configured on the core plugin. Network images are fetched only after their addresses and response types pass validation.

If an import is too large or ambiguous, reduce the source material to the facts that define the character and add setting-specific material in the editor afterwards. A focused character with clear motives is more useful to the runtime than a long card full of duplicated examples and instructions.