Add Full Support for BYAF Archives (#4701) * + Fix discarding all scenarios aside from the first one, which would cause all chats other than the first one to be lost. + Accumulate alternative starting messages from all scenarios, as different scenarios are how Backyard handles having alternative greetings. A scenario with multiple messages in its "firstMessages" array is invalid as per BYAF spec. + Return scenarios so that they can be used to populate chats, scenario overrides, and in the future, the other character settings overrides as well. * + Added support for importing chats (including swipes) from BYAF. This brings the core functionality of BYAF imports mostly in-line with the standard, without the inclusion of any features that are currently missing from ST. > The only supported feature not yet implemented is scenario overrides per-chat. This will be the the goal of the next commit. * + Implemented scenario overrides, fully bringing ST's BYAF import as in-line with the BYAF standard as possible without adding new feature functionality to ST. + Also added some new chat metadata fields in preparation for example message and system prompt overrides. * + Added support for pulling alternate icons from the BYAF archive. They are not used yet, but they are safely stored. + Added support for pulling backgrounds from the BYAF archive. They are not used yet but they are stored and linked to the chats they originally belonged to. + Saved every remaining field that was previously discarded from BYAF that a user actually needs in a way that could be used in the future, and can be accessed by the user if needed after import. Any fields that are not preserved at this point are specfic to either Backyard AI's desktop application, or to the BYAF manifest itself, and therefore have no relevance to a user. > With this, BYAF import should be fully supported and in-line with the official spec. * + Updated comments and method names to reflect changes appropriately. First round of touch ups. * + More comment updates. * - Removed commented code, that is no longer needed for reference. * > No longer sanitize for filenames in the character card, as there's no need. The sanitization now happens when generating the filename, which is subsequently used for file operations. + Added replacement function for sanitizing filenames which uses visually similar but valid for filenames replacement characters instead of deleting the characters for better data parity. * + Preserve isNSFW flag as a tag, so it's not lost on import. * + preserve labels on character alt avatars * + Deduplicate first messages, so that 5 chats with the same first message don't create 5 identical first messages. * + Adjusted icon naming logic to produce more sensible results. * > User path.basename and path.extname for getting the base name and extension of files, respectively. * > Should use camelCase for local function names. * > Use a set for greetings instead of explicitly checking for duplicates. * > Missed a snake case local function name. * > Updated background import logic to integrate with existing per-chat background system. * + Updated logic to skip import of chats and backgrounds when a character is being updated/replaced. * + Added copy of getUniqueName helper function from frontend utils to backend utils. + Refactored duplicated logic for getting unique filenames for backgrounds and character alt icons to use the newly available function. * > fixed adding an extra dot to the filenames for icons after switching to path.extname for getting the extension * > Updated metadata settings generation in byaf chat so that it doesn't overwrite valid yet 'falsy' values with defaults. Oops * > Remove variable for configuration that will likely never need to exist. * > custom_background should be an empty string if chat_background is falsy * > Make an array empty if chat_background is falsy. * > Prefer camelCase for local variable names. * + Added definitions for ByafParseResult and ByafChatBackground. > Updated overused and unweildy anonymous types to the newly defined types. * + When importing a character with chats, the character will now no longer open to a new empty chat, but instead will pick the first of the imported chats to open up to. * Rename prev_paths => paths * Prettify logs display * Set fallback chat name if scenario is untitled * card.data.name => card.name * Optimize first scenario message access * + Moved custom replacement function from importFromByaf into util.js as sanitizeSafeCharacterReplacements() so that the replacement logic may be reused anywhere for consistency. * > Missed a couple. Updated for consistency * + Preserve character full/display name without it needing to be safe as a filename. > Change logic for naming the folder the alt images live in to match the logic the sprites endpoint uses to get character sprites for consistency * > Only add full_name extension if displayName exists. * full_name => display_name * - No longer use safe lookalike replacements for filename sanitization to be consistent with how web browsers sanitize invalid characters in filenames before saving to disk. * Tiny formatting fix --------- Co-authored-by: Cohee <18619528+Cohee1207@users.noreply.github.com>

dd758161bdf8b27f7c3c9b12c246ff677e1081fa

docfail <4965997+docfail@users.noreply.github.com>

Signed

Parents: 5e033a9db9a7f0051f873f38e35144bb5edf547b

public/script.js+1 -0 Viewed

     const formData = new FormData();
     formData.append('avatar', file);
     formData.append('file_type', format);
+    formData.append('user_name', name1);
     if (preserveFileName) formData.append('preserved_name', preserveFileName);
     try {

src/byaf.js+226 -68 Viewed

-import sanitize from 'sanitize-filename';
 import { promises as fsPromises } from 'node:fs';
 import path from 'node:path';
 import urlJoin from 'url-join';

      * @returns {string} String with macros replaced
      * @private
      */
-    replaceMacros(str) {
+    static replaceMacros(str) {
         return String(str || '')
             .replace(/#{user}:/gi, '{{user}}:')
             .replace(/#{character}:/gi, '{{char}}:')

      * @returns {string} Formatted example messages
      * @private
      */
-    formatExampleMessages(examples) {
+    static formatExampleMessages(examples) {
         if (!Array.isArray(examples)) {
             return '';
+        }

             if (!example?.text) {
                 return;
+            }
-            formattedExamples += `<START>\n${this.replaceMacros(example.text)}\n`;
+            formattedExamples += `<START>\n${ByafParser.replaceMacros(example.text)}\n`;
         });
         return formattedExamples.trimEnd();

     /**
      * Formats alternate greetings for a character.
-     * @param {ByafExampleMessage[]} [greetings] Array of greeting objects
+     * @param {Partial<ByafScenario>[]} [scenarios] Array of scenario objects
      * @returns {string[]} Formatted alternate greetings
      * @private
      */
-    formatAlternateGreetings(greetings) {
+    formatAlternateGreetings(scenarios) {
-        if (!Array.isArray(greetings)) {
+        if (!Array.isArray(scenarios)) {
             return [];
+        }
-        if (greetings.length <= 1) {
+        // Skip one because it goes into 'first_mes'
+        if (scenarios.length <= 1) {
             return [];
+        }
+        const greetings = new Set();
-        // Skip one because it goes into 'first_mes'
+        const firstScenarioFirstMessage = scenarios?.[0]?.firstMessages?.[0]?.text;
-        return greetings.slice(1).map(g => this.replaceMacros(g?.text));
+        for (const scenario of scenarios.slice(1).filter(s => Array.isArray(s.firstMessages) && s.firstMessages.length > 0)) {
+            // As per the BYAF spec, "firstMessages" array MUST contain AT MOST one message.
+            // So we only consider the first one if it exists.
+            const firstMessage = scenario?.firstMessages?.[0];
+            if (firstMessage?.text && firstMessage.text !== firstScenarioFirstMessage) {
+                greetings.add(ByafParser.replaceMacros(firstMessage.text));
+            }
+        }
+        return Array.from(greetings);
+    }
     /**

                 return;
+            }
             book.entries.push({
-                keys: this.replaceMacros(item?.key).split(',').map(key => key.trim()).filter(Boolean),
+                keys: ByafParser.replaceMacros(item?.key).split(',').map(key => key.trim()).filter(Boolean),
-                content: this.replaceMacros(item?.value),
+                content: ByafParser.replaceMacros(item?.value),
                 extensions: {},
                 enabled: true,
                 insertion_order: index,

+    }
     /**
-     * Extracts a scenario object from BYAF buffer.
+     * Extracts all scenario objects from BYAF buffer.
      * @param {ByafManifest} manifest BYAF manifest
-     * @returns {Promise<Partial<ByafScenario>>} Scenario object
+     * @returns {Promise<Partial<ByafScenario>[]>} Scenarios array
      * @private
      */
-    async getScenarioFromManifest(manifest) {
+    async getScenariosFromManifest(manifest) {
         const scenariosArray = manifest?.scenarios;
         if (!Array.isArray(scenariosArray) || scenariosArray.length === 0) {
             console.warn('Warning: BYAF manifest contains no scenarios');
-            return {};
+            return [{}];
+        }
-        if (scenariosArray.length > 1) {
+        const scenarios = [];
-            console.warn('Warning: BYAF manifest contains more than one scenario, only the first one will be imported');
-        }
-        const scenarioPath = scenariosArray[0];
+        for (const scenarioPath of scenariosArray) {
-        if (!scenarioPath) {
+            const scenarioBuffer = await extractFileFromZipBuffer(this.#data, scenarioPath);
-            console.warn('Warning: missing BYAF scenario path');
+            if (!scenarioBuffer) {
-            return {};
+                console.warn('Warning: failed to extract BYAF scenario JSON');
+            }
+            if (scenarioBuffer) {
+                try {
+                    scenarios.push(JSON.parse(scenarioBuffer.toString()));
+                } catch (error) {
+                    console.warn('Warning: BYAF scenario is not a valid JSON', error);
+                }
+            }
+        }
-        const scenarioBuffer = await extractFileFromZipBuffer(this.#data, scenarioPath);
+        if (scenarios.length === 0) {
-        if (!scenarioBuffer) {
+            console.warn('Warning: BYAF manifest contains no valid scenarios');
-            console.warn('Warning: failed to extract BYAF scenario JSON');
+            return [{}];
-            return {};
+        }
-        try {
+        return scenarios;
-            return JSON.parse(scenarioBuffer.toString());
-        } catch (error) {
-            console.warn('Warning: BYAF scenario is not a valid JSON', error);
-            return {};
-        }
+    }
     /**
-     * Extracts an image from BYAF buffer.
+     * Extracts all character icon images from BYAF buffer.
      * @param {ByafCharacter} character Character object
      * @param {string} characterPath Path to the character in the BYAF manifest
-     * @return {Promise<Buffer>} Image buffer
+     * @return {Promise<{filename: string, image: Buffer, label: string}[]>} Image buffer
      * @private
      */
-    async getCharacterImage(character, characterPath) {
+    async getCharacterImages(character, characterPath) {
         const defaultAvatarBuffer = await fsPromises.readFile(DEFAULT_AVATAR_PATH);
         const characterImages = character?.images;
         if (!Array.isArray(characterImages) || characterImages.length === 0) {
             console.warn('Warning: BYAF character has no images');
-            return defaultAvatarBuffer;
+            return [{ filename: '', image: defaultAvatarBuffer, label: '' }];
+        }
-        const imagePath = characterImages[0]?.path;
+        const imageBuffers = [];
-        if (!imagePath) {
+        for (const image of characterImages) {
-            console.warn('Warning: BYAF character image path is empty');
+            const imagePath = image?.path;
-            return defaultAvatarBuffer;
+            if (!imagePath) {
-        }
+                console.warn('Warning: BYAF character image path is empty');
+                continue;
+            }
-        const fullImagePath = urlJoin(path.dirname(characterPath), imagePath);
+            const fullImagePath = urlJoin(path.dirname(characterPath), imagePath);
-        const imageBuffer = await extractFileFromZipBuffer(this.#data, fullImagePath);
+            const imageBuffer = await extractFileFromZipBuffer(this.#data, fullImagePath);
-        if (!imageBuffer) {
+            if (!imageBuffer) {
-            console.warn('Warning: failed to extract BYAF character image');
+                console.warn('Warning: failed to extract BYAF character image');
-            return defaultAvatarBuffer;
+                continue;
-        }
+            }
-        return imageBuffer;
+            imageBuffers.push({ filename: path.basename(imagePath), image: imageBuffer, label: image?.label || '' });
+        }
+        if (imageBuffers.length === 0) {
+            console.warn('Warning: BYAF character has no valid images');
+            return [{ filename: '', image: defaultAvatarBuffer, label: '' }];
+        }
+        return imageBuffers;
+    }
     /**
      * Formats BYAF data as a character card.
      * @param {ByafManifest} manifest BYAF manifest
      * @param {ByafCharacter} character Character object
-     * @param {Partial<ByafScenario>} scenario Scenario object
+     * @param {Partial<ByafScenario>[]} scenarios Scenarios array
      * @return {TavernCardV2} Character card object
      * @private
      */
-    getCharacterCard(manifest, character, scenario) {
+    getCharacterCard(manifest, character, scenarios) {
         return {
             spec: 'chara_card_v2',
             spec_version: '2.0',
             data: {
-                name: sanitize(character?.name || character?.displayName || ''),
+                name: character?.name || character?.displayName || '',
-                description: this.replaceMacros(character?.persona),
+                description: ByafParser.replaceMacros(character?.persona),
                 personality: '',
-                scenario: this.replaceMacros(scenario?.narrative),
+                scenario: ByafParser.replaceMacros(scenarios[0]?.narrative),
-                first_mes: this.replaceMacros(scenario?.firstMessages?.[0]?.text),
+                first_mes: ByafParser.replaceMacros(scenarios[0]?.firstMessages?.[0]?.text),
-                mes_example: this.formatExampleMessages(scenario?.exampleMessages),
+                mes_example: ByafParser.formatExampleMessages(scenarios[0]?.exampleMessages),
-                creator_notes: '',
+                creator_notes: manifest?.author?.backyardURL || '', // To preserve the link to the author from BYAF manifest, this is a good place.
-                system_prompt: this.replaceMacros(scenario?.formattingInstructions),
+                system_prompt: ByafParser.replaceMacros(scenarios[0]?.formattingInstructions),
                 post_history_instructions: '',
-                alternate_greetings: this.formatAlternateGreetings(scenario?.firstMessages),
+                alternate_greetings: this.formatAlternateGreetings(scenarios),
                 character_book: this.convertCharacterBook(character?.loreItems),
-                tags: [],
+                tags: character?.isNSFW ? ['nsfw'] : [], // Since there are no tags in BYAF spec, we can use this to preserve the isNSFW flag.
                 creator: manifest?.author?.name || '',
                 character_version: '',
-                extensions: {},
+                extensions: { ...(character?.displayName && { 'display_name': character?.displayName }) }, // Preserve display name unmodified using extensions. "display_name" is not used by SillyTavern currently.
             },
             // @ts-ignore Non-standard spec extension
             create_date: humanizedISO8601DateTime(),
         };
+    }
+    /**
+     * Gets chat backgrounds from BYAF data mapped to their respective scenarios.
+     * @param {ByafCharacter} character Character object
+     * @param {Partial<ByafScenario>[]} scenarios Scenarios array
+     * @returns {Promise<Array<ByafChatBackground>>} Chat backgrounds
+     * @private
+     */
+    async getChatBackgrounds(character, scenarios) {
+        // Implementation for extracting chat backgrounds from BYAF data
+        const backgrounds = [];
+        let i = 1;
+        for (const scenario of scenarios) {
+            const bgImagePath = scenario?.backgroundImage;
+            if (bgImagePath) {
+                const data = await extractFileFromZipBuffer(this.#data, bgImagePath);
+                if (data) {
+                    const existingIndex = backgrounds.findIndex(bg => bg.data.compare(data) === 0);
+                    if (existingIndex !== -1) {
+                        backgrounds[existingIndex].paths.push(bgImagePath);
+                        continue; // Skip adding a new background since it already exists
+                    }
+                    backgrounds.push({
+                        name: `${character?.name} bg ${i++}` || '',
+                        data: data,
+                        paths: [bgImagePath],
+                    });
+                }
+            }
+        }
+        return backgrounds;
+    }
     /**
      * Gets the manifest from the BYAF data.

+    }
     /**
+     * Imports a chat from BYAF format.
+     * @param {Partial<ByafScenario>} scenario Scenario object
+     * @param {string} userName User name
+     * @param {string} characterName Character name
+     * @param {Array<ByafChatBackground>} chatBackgrounds Chat backgrounds
+     * @returns {string} Chat data
+     */
+    static getChatFromScenario(scenario, userName, characterName, chatBackgrounds) {
+        const chatStartDate = scenario?.messages?.length == 0 ? humanizedISO8601DateTime() : scenario?.messages?.filter(m => 'createdAt' in m)[0].createdAt;
+        const chatBackground = chatBackgrounds.find(bg => bg.paths.includes(scenario?.backgroundImage || ''))?.name || '';
+        /** @type {object[]} */
+        const chat = [{
+            user_name: userName,
+            character_name: characterName,
+            create_date: chatStartDate,
+            chat_metadata: {
+                scenario: scenario?.narrative ?? '',
+                mes_example: ByafParser.formatExampleMessages(scenario?.exampleMessages),
+                system_prompt: ByafParser.replaceMacros(scenario?.formattingInstructions),
+                mes_examples_optional: scenario?.canDeleteExampleMessages ?? false,
+                byaf_model_settings: {
+                    model: scenario?.model ?? '',
+                    temperature: scenario?.temperature ?? 1.2,
+                    top_k: scenario?.topK ?? 40,
+                    top_p: scenario?.topP ?? 0.9,
+                    min_p: scenario?.minP ?? 0.1,
+                    min_p_enabled: scenario?.minPEnabled ?? true,
+                    repeat_penalty: scenario?.repeatPenalty ?? 1.05,
+                    repeat_penalty_tokens: scenario?.repeatLastN ?? 256,
+                    by_prompt_template: scenario?.promptTemplate ?? 'general',
+                    grammar: scenario?.grammar ?? null,
+                },
+                chat_backgrounds: chatBackground ? [chatBackground] : [],
+                custom_background: chatBackground ? `url("${encodeURI(chatBackground)}")` : '',
+            },
+        }];
+        // Add the first message IF it exists.
+        if (scenario?.firstMessages?.length && scenario?.firstMessages?.length > 0 && scenario?.firstMessages?.[0]?.text) {
+            chat.push({
+                name: characterName,
+                is_user: false,
+                send_date: chatStartDate,
+                mes: scenario?.firstMessages?.[0]?.text || '',
+            });
+        }
+        const sortByTimestamp = (newest, curr) => {
+            const aTime = new Date(newest.activeTimestamp);
+            const bTime = new Date(curr.activeTimestamp);
+            return aTime >= bTime ? newest : curr;
+        };
+        const getNewestAiMessage = (message) => {
+            return message.outputs.reduce(sortByTimestamp);
+        };
+        const getSwipesForAiMessage = (aiMessage) => {
+            return aiMessage.outputs.map(output => output.text);
+        };
+        const userMessages = scenario?.messages?.filter(msg => msg.type === 'human');
+        const characterMessages = scenario?.messages?.filter(msg => msg.type === 'ai');
+        /**
+         * Reorders messages by interleaving user and character messages so that they are in correct chronological order.
+         * This is only needed to import old chats from Backyard AI that were incorrectly imported by an earlier version
+         * that completely messed up the order of messages. Backyard AI Windows frontend never supported creation of chats
+         * with which were ordered like this in the first place, so for most users this is desired functionality.
+         */
+        if (userMessages && characterMessages && userMessages.length === characterMessages.length) { // Only do the reordering if there are equal numbers of user and character messages, otherwise just import in existing order, because it's probably correct already.
+            for (let i = 0; i < userMessages.length; i++) {
+                chat.push({
+                    name: userName,
+                    is_user: true,
+                    send_date: Number(userMessages[i]?.createdAt),
+                    mes: userMessages[i]?.text,
+                });
+                const aiMessage = getNewestAiMessage(characterMessages[i]);
+                const aiSwipes = getSwipesForAiMessage(characterMessages[i]);
+                chat.push({
+                    name: characterName,
+                    is_user: false,
+                    send_date: Number(aiMessage.createdAt),
+                    mes: aiMessage.text,
+                    swipes: aiSwipes,
+                    swipe_id: aiSwipes.findIndex(s => s === aiMessage.text),
+                });
+            }
+        } else if (scenario?.messages) {
+            for (const message of scenario.messages) {
+                const isUser = message.type === 'human';
+                const aiMessage = !isUser ? getNewestAiMessage(message) : null;
+                const chatMessage = {
+                    name: isUser ? userName : characterName,
+                    is_user: isUser,
+                    send_date: Number(isUser ? message.createdAt : aiMessage.createdAt),
+                    mes: isUser ? message.text : aiMessage.text,
+                };
+                if (!isUser) {
+                    const aiSwipes = getSwipesForAiMessage(message);
+                    chatMessage.swipes = aiSwipes;
+                    chatMessage.swipe_id = aiSwipes.findIndex(s => s === aiMessage.text);
+                }
+                chat.push(chatMessage);
+            }
+        } else {
+            console.warn('Warning: BYAF scenario contained no messages property.');
+        }
+        return chat.map(obj => JSON.stringify(obj)).join('\n');
+    }
+    /**
      * Parses the BYAF data.
-     * @return {Promise<{card: TavernCardV2, image: Buffer}>} Parsed character card and image buffer
+     * @return {Promise<ByafParseResult>} Parsed character card and image buffer
      */
     async parse() {
         const manifest = await this.getManifest();
         const { character, characterPath } = await this.getCharacterFromManifest(manifest);
-        const scenario = await this.getScenarioFromManifest(manifest);
+        const scenarios = await this.getScenariosFromManifest(manifest);
-        const image = await this.getCharacterImage(character, characterPath);
+        const images = await this.getCharacterImages(character, characterPath);
-        const card = this.getCharacterCard(manifest, character, scenario);
+        const card = this.getCharacterCard(manifest, character, scenarios);
+        const chatBackgrounds = await this.getChatBackgrounds(character, scenarios);
-        return { card, image };
+        return { card, images, scenarios, chatBackgrounds, character };
+    }
+}

src/endpoints/characters.js+64 -3 Viewed

 import { AVATAR_WIDTH, AVATAR_HEIGHT, DEFAULT_AVATAR_PATH } from '../constants.js';
 import { default as validateAvatarUrlMiddleware, getFileNameValidationFunction } from '../middleware/validateFileName.js';
-import { deepMerge, humanizedISO8601DateTime, tryParse, extractFileFromZipBuffer, MemoryLimitedMap, getConfigValue, mutateJsonString } from '../util.js';
+import { deepMerge, humanizedISO8601DateTime, tryParse, extractFileFromZipBuffer, MemoryLimitedMap, getConfigValue, mutateJsonString, clientRelativePath, getUniqueName, sanitizeSafeCharacterReplacements } from '../util.js';
 import { TavernCardValidator } from '../validator/TavernCardValidator.js';
 import { parse, read, write } from '../character-card-parser.js';
 import { readWorldInfoFile } from './worldinfo.js';

     const byafData = await new ByafParser(data).parse();
     const card = readFromV2(byafData.card);
-    const fileName = preservedFileName || getPngName(card.name, request.user.directories);
+    const fileName = preservedFileName || getPngName(sanitize(byafData.character.displayName || card.name, { replacement: sanitizeSafeCharacterReplacements }), request.user.directories);
-    const result = await writeCharacterData(byafData.image, JSON.stringify(card), fileName, request);
+    // Don't import chats and images if the character is being replaced or updated, instead of newly imported.
+    if (!preservedFileName) {
+        /**
+         * @param {Partial<ByafScenario>} scenario
+        */
+        const createChatAsCurrentPersona = (scenario) => {
+            const chatName = sanitize(`${scenario.title || card.name} - ${humanizedISO8601DateTime()} imported.jsonl`, { replacement: sanitizeSafeCharacterReplacements });
+            const filePath = path.join(request.user.directories.chats, path.basename(fileName), chatName);
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            writeFileAtomicSync(filePath, ByafParser.getChatFromScenario(scenario, request.body.user_name, card.name, byafData.chatBackgrounds), 'utf8');
+            console.log(`Created ${chatName} chat from BYAF import`);
+            return chatName;
+        };
+        // Upload backgrounds
+        for (const bg of byafData.chatBackgrounds) {
+            const extension = path.extname(bg.paths?.[0]) || '.png';
+            const baseName = `${path.basename(fileName)}_bg`;
+            const filePath = path.join(request.user.directories.userImages, fileName);
+            if (!fs.existsSync(filePath)) fs.mkdirSync(filePath, { recursive: true });
+            const file = getUniqueName(baseName, (name) => fs.existsSync(path.join(filePath, `${name}${extension}`)));
+            if (Buffer.isBuffer(bg.data)) {
+                const newFile = `${file}${extension}`;
+                writeFileAtomicSync(path.join(filePath, newFile), bg.data);
+                bg.name = clientRelativePath(request.user.directories.root, path.join(filePath, newFile)); // Update background name to the new file
+                console.log(`Created ${newFile} background from BYAF import`);
+            }
+        }
+        const chats = [];
+        // Create chats for each scenario
+        if (Array.isArray(byafData.scenarios)) {
+            for (const scenario of byafData.scenarios) {
+                chats.push(createChatAsCurrentPersona(scenario));
+            }
+        }
+        // Update the default chat if there are any so we open to an existing chat instead of creating a new one and opening that.
+        if (chats.length > 0) {
+            card.chat = path.basename(chats[0], path.extname(chats[0]));
+        }
+        // Save alternate icons for the character.
+        for (const icon of byafData.images.slice(1)) {
+            // BYAF does not support character expressions, so using the same structure will not result in conflicts,
+            // even if the expression system did not tolerate additional icons that are not mapped to expressions.
+            // This will not yet allow changing icons within the UI but at least the icons will be available for manual selection, rather than being lost.
+            const altImagesFolder = path.join(request.user.directories.characters, sanitize(card.name));
+            if (!fs.existsSync(altImagesFolder)) fs.mkdirSync(altImagesFolder, { recursive: true });
+            const extension = path.extname(icon.filename) || '.png';
+            const file = getUniqueName(`${sanitize(icon.label, { replacement: sanitizeSafeCharacterReplacements }) || 'alt'}`, (name) => fs.existsSync(path.join(altImagesFolder, `${name}${extension}`)));
+            if (Buffer.isBuffer(icon.image)) {
+                writeFileAtomicSync(path.join(altImagesFolder, `${file}${extension}`), icon.image);
+                console.log(`Created ${file}${extension} alternate icon from BYAF import`);
+            }
+        }
+    }
+    const result = await writeCharacterData(byafData.images[0].image, JSON.stringify(card), fileName, request);
     return result ? fileName : '';
+}

src/types/byaf.d.ts+14 -0 Viewed

     messages: Array<ByafAiMessage | ByafHumanMessage>;
     backgroundImage?: string;
 };
+type ByafChatBackground = {
+    name: string;
+    data: Buffer;
+    paths: string[];
+};
+type ByafParseResult = {
+    card: TavernCardV2,
+    images: { filename: string, image: Buffer, label: string }[],
+    scenarios: Partial<ByafScenario>[],
+    chatBackgrounds: Array<ByafChatBackground>,
+    character: ByafCharacter
+};

src/util.js+25 -0 Viewed

+}
 /**
+ * Returns a name that is unique among the names that exist.
+ * @param {string} name The name to check.
+ * @param {{ (name: string): boolean; }} exists Function to check if name exists.
+ * @returns {string} A unique name.
+ */
+export function getUniqueName(name, exists) {
+    let i = 1;
+    let baseName = name;
+    while (exists(name)) {
+        name = `${baseName} (${i})`;
+        i++;
+    }
+    return name;
+}
+/**
+ * Provides safe replacements for characters in filenames. Intended for use with sanitize() from the sanitize-filename package.
+ * @param {string} char Character to sanitize
+ * @returns {string} Safe replacement character
+ */
+export function sanitizeSafeCharacterReplacements(char) {
+    return '_';
+}
+/**
  * Strip the last file extension from a given file name. If there are multiple extensions, only the last is removed.
  * @param {string} filename The file name to remove the extension from.
  * @returns The file name, sans extension