Skip to main content

Catalogue

The Catalogue page browses worlds held by a Roleplay Catalogue and installs them as worlds of your own. You can add more than one catalogue, and you can also install a world from the address of its archive.

Set up a catalogue​

Open Settings → Role Play → Catalogues and choose Add a catalogue:

  • Name: what you call it. Names must be different from each other.
  • API address: the catalogue's API root, for example https://catalogue.example/api, or http://localhost:9798 for a catalogue that serves its API without a prefix. It must be a web address with no user name, query or fragment.
  • Key name (optional): the credential the key is stored under, for example ROLEPLAY_CATALOGUE_HOME_API_KEY. Leave it empty to use a name made from the catalogue's name. A name has letters, digits and _ and does not start with a digit.
  • API key (optional): a key created in the catalogue. With one, the page also shows the private worlds that key may read. Without one, only public worlds show.

The key is not kept in the profile's configuration. It goes to DSH's credential store, the same one that holds your model keys, and the page only learns whether a key is set and where it comes from (the store's file, or the environment you launched DSH in), never the key. Store key and Remove key act at once; Save keeps the list and the key names in the profile's configuration. A key in the store wins over one supplied by the environment (ROLEPLAY_CATALOGUE_HOME_API_KEY=… dsh), which applies only while the store holds none; remove the stored key to fall back to it. If the credential plugin in use cannot write, the page says so and the key can only be changed there. The store resolves the key for each request, so a replaced key is used by the next one without a restart, and a credential plugin that replaces the store, such as one backed by your system's keychain, protects these keys too. Use a key made for this purpose, with as little reach as the catalogue allows.

:::note Upgrading from 0.3 Version 0.4.0 moved the key out of the configuration. A key you saved earlier is still used until you move it: the row shows a notice with Move it to the credential store. Saving the settings afterwards removes the plain text from the configuration. A profile with no credential store keeps working with a key in the configuration, but cannot store new ones. :::

Browse and install​

The page lists published worlds of the catalogue you pick, with search and a newest or popular order. A line under the toolbar says whether your key is in use. Saving a different key (or removing it) in Settings updates the page by itself, so private worlds appear or disappear without a reload.

Select a world to see its description, tags and releases. Install downloads the chosen release, checks it against the checksum the catalogue published, and adds it to your worlds. You can then play it or edit it like any world; it is a copy, and the catalogue is not contacted again. If another world already uses the same folder name, the new one gets a numbered folder. A world installed from a release remembers which release it came from, so the page can tell you when a newer one exists.

A world may come with interface packs. A pack runs its own scripts, inside the sandbox that holds every pack, when you play. The page tells you which packs came along; read them first if you do not know the author.

Update an installed world​

When a catalogue has a newer release of a world you installed from it, the page lists it above the grid. Select it and choose Update. The new release replaces the world in its own folder, so your sessions keep working, and your previous files are moved to .trash/worlds/ in your roleplay root rather than deleted right away. They are removed after catalogueTrashDays days (30 by default; 0 keeps them for good), checked at startup and after each update. To get something back sooner, copy the folder out of the trash into worlds/.

If you changed the world since you installed it (any file added, edited or removed), the page says so, lists the differences and asks:

  • Overwrite my version replaces your version with the release. Your version is still kept in the trash folder.
  • Keep both installs the release as a separate world named "(copy)", with its own identity, and leaves yours alone. The copy is not tied to the catalogue, so it is not offered updates.

A world with no record of its release (installed before releases were remembered, or copied by hand) gets the same question, because there is no telling whether you changed it. Install as a separate copy is also available any time you already have a world.

Character cards​

The Character cards tab lists SillyTavern character cards the catalogue holds. Review and convert downloads the card with the catalogue's key and shows what it holds, the same review as a card import from a file: the world's name, which lorebook entries are read at all, and which greeting opens the story. Import then makes a new world with those choices, and its authoring chat converts the card and opens. Cancelling makes nothing.

Converting the same card again makes a new world: the conversion is done by an agent that makes its own choices, so two conversions give different worlds. If you already have a world with the card's name that was itself imported from a card, the review offers to update it instead, which has the world's authoring assistant apply what the new version changes and costs a fraction of a conversion; see a newer version of a card. Update is preselected when you have not edited that world since its import, and a new world when you have. A card you have on disk can update a world too, without the catalogue: use Update from card in the world's header. Nothing replaces your files without the assistant's edits being approved, and whatever it replaces or deletes goes to the world's .trash folder.

Presets​

The Presets tab lists SillyTavern presets the catalogue holds. Import as a preset downloads one with the catalogue's key, asks which of its prompts to bring and whether to keep its sampling, then starts the preset import: a new preset is made in your library and its authoring chat writes the narration prompts, then opens. Like a card, a preset is never updated in place; importing it again makes another preset.

Lorebooks​

The Lorebooks tab lists SillyTavern lorebooks the catalogue holds (resource type sillytavern/lorebook). Import as a lorebook downloads one with the catalogue's key, asks which of its entries to bring, then starts the lorebook import: a new lorebook is made in your library and its authoring chat fills it with entries, then opens. Like a card, a lorebook is never updated in place; importing it again makes another one.

Import from an address​

Import from address installs a world from the address of its ZIP archive:

  • an address on a catalogue you added is asked for with that catalogue's key, so a private release works when the key may read it;
  • any other address is fetched as it is. It must be a public web address on a standard port, and the import fails with the reason if it needs a sign-in;
  • the key is only ever sent to the site it was configured for, also when a download redirects elsewhere.

An archive must hold one top-level folder with a world.json. The world is written beside your worlds first and moved in only when whole, so a refused archive leaves nothing behind. Archives with links, unsafe or repeated paths, encryption, or more than the size limit catalogueMaxBytes (256 MiB unpacked) are refused.