Adding a Persona Preset
このコンテンツはまだ日本語訳がありません。
How to add an official persona preset to the seed catalog. Locale variants of an existing preset are covered in Adding a Locale.
-
Create
src/db/seed/catalog/personas/<name>/with one file per language (en-US.ts,ja.ts), each exportingpersona: PersonaInput, and register each inpersonas/index.ts. There is no directory scan. Required fields:preset_lineage_id: identical in every language variant. It makes the variants one character and becomes the persona’spersona_lineage_id, which scopes its memories. A locale without a variant lists the base-language oren-USvariant instead.name,desc,attributes, pairedsampleDialoguesIn/sampleDialoguesOut,language,avatarPath,triggerWords.- Do not author
preset_attribute_public_flags.personaSeed.tsderives it: the first attribute is public and the rest are private. - Add the lineage to
OFFICIAL_LINEAGE_IDSinpersonaSeed.tsand to the naming snapshot intests/unit/db/personaNamingCatalog.test.ts. - Optional
isNsfw: truehides the preset from/persona defaultand/setup; the age-restricted/nsfw persona defaultlists only NSFW presets. Personas created from it copy the flag, and only/nsfw persona importaccepts a file that carries it.
-
Put the avatar image in the folder and set
avatarPathto the folder; the first image alphabetically is used. -
Optionally add sprites under
sprites/and list them per locale file:sprites: [{ name: "mad", file: "sprites/mad.png", usageInstructions: "Use when angry or annoyed." },{ name: "shy", file: "sprites/shy.png", isIdentity: false },],namebecomes thesprite_key,fileis relative toavatarPath,usageInstructionsis prompt guidance, andisIdentityrenders the name assprite (Persona). Optionally add a full-body character reference for reference-based image generation, in every locale file:characterReference: "character-reference/front.png". Keep it in a subfolder, because an image directly in the folder could become the avatar;bun run check-seed-catalogsenforces this. -
Add the lineage’s Natural Nudges defaults to
PRESET_NATURAL_NUDGE_DEFAULTSinsrc/db/seed/catalog/personas/naturalNudges.ts, keyed bypreset_lineage_id. Every language variant shares one entry, and the seeder fails without it.idleNudgestakes one to a fewPersonaAuthoredIdleNudgedefinitions (at most 20), each with:id: a stable slug of up to 24 letters, digits,_, or-, unique within the list. Never rename it once shipped, because the runtime key and a persona’s local on/off choice use it.category:ping_user,revive_topic,start_topic, orplay_scene. Skip the prerequisite the category already implies (CATEGORY_IMPLIED_PREREQUISITES), and keeprecommended_toolsfree of a tool atool:<name>prerequisite already requires. The/configeditor saves them that way.title,brief,agenda_hint: English text shared by every language variant, with{persona},{target}, and{partner}placeholders. Write from the character’s attributes and interests, and require atool:<name>prerequisite for any brief that needs a tool, such astool:imagefor a picture ortool:web_searchfor current facts.- Avoid a Ping User or Play Scene entry unless the brief needs a target or a partner. Entries add to the built-in and server nudges and share their frequency and daily limit. Interests drive Active Nudges, so idle nudges do not repeat them.
-
Add or edit shared system prompt presets in
src/db/seed/catalog/systemPrompts.tsif needed. -
Keep each image under 1 MiB;
bun run compress-mediashrinks oversized art.
How presets reach servers
Section titled “How presets reach servers”Applying a preset through /setup or /persona default creates a copy-on-write pointer:
personas.is_pointer = true with preset_lineage_id and preset_language. Reads resolve text and
config from the live persona_presets row, so seed edits reach every pointer persona after the next
boot.
- Sprites upload once to the immutable
presets/storage prefix intopreset_sprites, and every pointer persona resolves them live. Removing a sprite from the array removes it everywhere. - Avatars upload once to
presets/, recordingpreset_avatar_shared_urlandpreset_avatar_hash. Pointer alters resolve that URL live. A pointer main persona uses the bot’s guild avatar, whichreconcilePresetMainAvatarsre-uploads per guild whenapplied_avatar_hash != preset_avatar_hash. - Character references upload once to
presets/, recordingpreset_char_ref_shared_url. Pointer personas resolve it live; a fork keeps it, and changing the avatar removes it. - The first local content edit, including changing the main avatar in
/config, turns the pointer into an independent copy that keepspersona_idandpersona_lineage_id. Memory writes do not./persona defaultrestores the pointer and discards local changes. /persona exportwrites a self-contained copy stamped withpreset_lineage_id. Import re-links to the official pointer only when the content exactly matches the seeded preset of that lineage.
Verify
Section titled “Verify”bun run check-seed-catalogs # names, paired dialogues, attributes, sprite files, prompts, nudge defaultsbun run check-media-sizebun run checkbun run lintbun run test tests/unit/naturalNudges/idleNudges.test.tsThen seed a dev database and check /setup, /persona default, /persona export, and
/persona import. A pointer persona should show the seeded values, pick up a seed edit after cache
invalidation, and become a copy on its first local edit. Open /config > Persona > Nudges to see
the seeded idle nudges. See
Persona Presets for the pointer model.