Updated instructions on adding NPCs

docs/pages/adding_modded_npcs.md

@@ -1,11 +1,75 @@
 (adding-modded-npcs)=
 # Adding Modded NPCs
-Mantella allows you to talk to any NPC. If you cast the Mantella spell on an unknown / modded NPC, a message will display in Mantella.exe asking you to restart Skyrim or Fallout 4. Once this is done, the NPC will be able to speak to you. 
+Character override files can be used to either make new characters available to Mantella or override existing NPC bios.
 
-If a given NPC cannot be found in `MantellaSoftware/data/skyrim_characters.csv` or `MantellaSoftware/data/fallout4_characters.csv` (depending on your game install), Mantella will try its best to fill in the blanks on the NPC, making an educated guess on the NPC's background based on their name (eg Whiterun Guard) and on their voice model based on various factors such as race and sex.
+Character overrides can be added to this folder:  
+`..\Documents\My Games\Mantella\data\Skyrim\character_overrides\`
 
-Of course, if you are unhappy with Mantella's assumptions, you can add full support for modded NPCs to `MantellaSoftware/data/skyrim_characters.csv` or `MantellaSoftware/data/fallout4_characters.csv` by adding a new row containing the NPC's name (`name`), background description (`bio`), and voice model (`voice_model`). The rest of the column entries can be left blank (as long as the name isn't duplicated elsewhere in the list). If you don't have Excel, you can open this CSV file with [LibreOffice](https://www.libreoffice.org/). 
+```{admonition} Note
+:class: seealso
 
-Note that if the modded NPC is custom voiced there may not be an xVASynth model available, and you will need to assign the NPC a vanilla voice. By default, Mantella does not create memories for NPCs missing from `skyrim_characters.csv` or `fallout4_characters.csv` as they are assumed to be generic (eg there are many NPCs called "Whiterun Guard" so it does not make sense for them all to share the same memory).
+If you are a mod creator and want to include the bio of your NPC with your mod, please instead add your character override to `{mod location}\SKSE\Plugins\MantellaSoftware\data\Skyrim\character_overrides\`.
+```
+
+Any `.csv` or `.json` file placed in your overrides folder will be loaded on start-up of Mantella. Removing a file will remove the override on the next start of Mantella.
+
+If you intend to override an existing entry, you only need to include the columns/fields that are required to uniquely identify the row/entry you want to override in the original database as well as the fields you want to replace.
+
+If you are creating a new entry for an NPC not included in the database yet, make sure that your entry is unique and that it includes all the fields that Mantella requires like the bio and the voice model.
+
+**Example 1:**  
+
+`Lydia.json`
+```json
+{
+    "name": "Lydia",
+    "voice_model": "FemaleEvenToned",
+    "bio": "Lydia is a Bosmer thief. Her stew is horrible.",
+    "race": "Bosmer",
+    "species": "Elf"
+}
+```
+
+`Lydia.csv`
+```csv
+name,voice_model,bio,race,species
+Lydia,FemaleEvenToned,Lydia is a Bosmer thief. Her stew is horrible.,Bosmer,Elf
+```
+
+Both of these examples are identical. The first is in `.json` format the second one is `.csv`. Both files override Lydia's entry in the database, replacing her bio, race and species columns/fields. Her other fields like the voice model will stay as they are.
+
+Both formats can have multiple entries in one file.
+
+**Example 2:**  
+
+`Lydias.json`
+```json
+[
+    {
+        "name": "Lydia",
+        "bio": "Lydia is a Bosmer thief. Her stew is horrible.",
+        "race": "Bosmer",
+        "species": "Elf"
+    },
+    {
+        "name": "Lydia's evil twin",
+        "voice_model": "FemaleEvenToned",
+        "skyrim_voice_folder": "FemaleEvenToned",
+        "bio": "Where does she come from? Or is this just Lydia after she tasted her own stew?",
+        "race": "Nord",
+        "gender": "Female",
+        "species": "Human"
+    }
+]
+```
+
+`Lydias.csv`
+```csv
+name,voice_model,skyrim_voice_folder,bio,race,species
+Lydia,FemaleEvenToned,,Lydia is a Bosmer thief. Her stew is horrible.,Bosmer,Elf
+Lydia's evil twin,FemaleEvenToned,FemaleEvenToned,Where does she come from? Or is this just Lydia after she tasted her own stew?,Nord,Female,Human
+```
+
+The first entry/row will work exactly as in Example 1. The second entry will add a new NPC to the database as there is no entry for Lydia's evil twin that could be overwritten.
 
 For further support and examples of how other users have added modded NPCs, see the [custom-npcs channel on Discord](https://discord.gg/Q4BJAdtGUE).