Category:Modder Guides

'''WARNING: The game is still in active alpha development. Mods you make aren't guaranteed to work with the latest version of the game. Your mods are entirely up to you to maintain, unless someone decides to patch your mod for you. Warning probably sounds scarier than it actually is.'''

Notice for v23 The metadata section of this guide will become no longer relevant in v23, as a dynamic loader is being implemented. The game will instead expect your .json files to be organized in folders of particular names, so it can easily locate them and load them into the correct databases on startup. Here is an optional guide on how to prepare your folder structure for v23: 

v23 file structure
Where they are placed within your mods folder does not particularly matter, for as long as all relevant .json files are under them. Be sure to check the base game's game/Json folder to see how Threshold chose to organize them. While maybe obvious, do not place them inside one another. You also only need to provide a certain JSON folder if you intend to use it.

With that out of the way, here is each type:


 * Adventures | Adventures are the first-time runs you do before you fully unlock a location. This also includes all special menu choices you have in the locations map, such as "Shortcut To Nara" or "Visit Amy", telling the game what they require to be unlocked or what event they will point to.


 * Events | Contains all events and combat events. Events encompass a vast number of scenes and moments within the game, you will find them pretty much everywhere you read the text box along the bottom of the screen. This includes brothel events. Combat events would be events specific to combat encounters when just a Skill is too simple. An example would be the blue slime asking if you are okay with anal insertion.


 * Fetishes | Contains both fetishes and addictions for the game. You can, in fact, make new fetishes. You only need to make a single json file that provides a list of new fetishes. Lesser known are addictions, which track particular milestones with Monster Girls. They work in a very similar manner and fall under the same system, but are typically hidden from the player. Do use them with some level of care.


 * Items | This will contain all of the consumables, equipment, and key items in the game.


 * Locations | Pretty self-descriptive, it encompasses all jsons related to the locations you find on the map when you select "Go Adventuring!" from the town. This includes what icons they should use, default BG and music, unlock requirements, what Adventures it has, and how the exploration via the grimoire will work.


 * Monsters | This will contain all of the monsters in the game, including NPCs. Note how they are organized per location in the base game, it's a handy tip. Also of note in the base game are outliers like the brothel specific iterations of various MGs, or certain NPCs not categorized into any particular folder.


 * Perks | This will contain all of the perks in the game, including monster only perks.


 * Skills | This will contain all of the skills in the game, including the monster skills.

Remember you do not have to follow how the base game organizes the contents within each of these folders, that can be done however you want!

At v23 launch
You will need to delete metadata file, and ensure the name of your mod directory now reflects the name of your mod. It is recommended to put the readme file in there, as the game will not load any data outside of the folders mentioned above. You will want to ensure when zipping your mod that it is putting your mod folder inside your zip file, not using the mod folder as the base of the zip file, so it does not paste the contents of the folder when unzipped.

Lastly, file paths. The mods folder will be in /game/Mods, due to technical limitations of the implementation via renpy functions for cross-platform compatibility. This might be addressed prior to launch, but there are no gaurantees. As such, any file paths refereed to in your jsons will need fixed.

This can easily be done with search and replace in your text editor.

Search for all instances of ../../Modloader/mods and replace with ../Mods

Your image and audio files can be placed wherever you like as always.

As a final aside, this page will take a dramatic change in a multitude of ways on v23 launch, and is being prepped ahead of time.

Overview
It is important to know how content is created in Monster Girl Dreams first, to understand how you will be modding. You will not be coding in python. You will be utilizing functions Threshold specifically made for  developing content, in a text file format called JSON. It is neatly found in a single folder in the games main directory (Check the Mod List's How-To Guides), the 'game' folder, then the appropriately titled 'Json' folder. You will find all of the games .json files to be plainly readable and modifiable as-is. You can also find music, images, and sound effects called upon by the JSON files in the "game" folder in the main game directory.

You however, will not be modding these files directly. That can cause all sorts of problems. Instead, you will be creating a folder that will contain all of the JSON and media related files you made for your mod, that will then by loaded into the game by a program called ModLoader. This includes mods that only intend to add to and/or change vanilla content. You will put your mod folder in ModLoader/mods, located in the games main directory.

ModLoader is capable of doing this by adding your JSONs to a series of lists in ModLoader/lists, that the game will check upon runtime through a master list called the "ListofLists". In order for ModLoader to know what you want it to use from your mod folder to begin with, you will create a separate JSON file you will place alongside (not in) your mod folder in ModLoader/mods. It is called your metadata file.

This guide will help prepare and set you up to begin modding. It will not give you a step-by-step guide on how to make an exact kind of content, both due to the wish to keep this being no longer than it already is, and the games constantly developing nature making it difficult to give anything more concrete. Regardless, you should feel properly prepared by the end of this. We will begin with going over Editors, and then how to make the metadata file.

Editors
Have no doubts, you do need an editor beyond the one that came with your system. They will properly read and understand .json files, will come with a boat load of useful features, and generally make you have a much better time while modding. Don't stress your editor choice too much, as you can easily change it at any time (though there may be issues with indents). Do know that these all have portable versions if you want your editor and modding work on say, a USB, separate from your main system. There are other well-made text editors beyond the three listed here, but these are among the best free editors out there. Two of the editors here have a proven track record with Threshold himself.

Atom
Portable version(download the zip/archive for your platform from the latest release.)
 * Supports all desktop platforms.
 * Well featured.
 * Built-in package support, useful for linter support. (Search for "linter", "linter-ui-default", and "linter-jsonlint" packages. Say yes to any dependencies.)
 * Built-in folder navigation.
 * Highly flexible customization.
 * The fastest and most reliable syntax highlighting, but slow boot times on setups with a heavy number of packages.
 * Git and github integration. (If you don't know what these are, don't sweat it and move on)
 * Currently used by Threshold.

Visual Studio Code
Portable version
 * Supports all desktop platforms.
 * Most featured editor out of the box.
 * Built-in folder navigation.
 * Fast built-in package support with the largest collection. JSON linter pre-installed.
 * Simplest to use customization.
 * Middle-of-the-road boot times and performance.
 * Git and github integration.

Notepad++
For the portable version, go to the Downloads page, select the latest version, and grab the zip file. It is HIGHLY encouraged to use a JSON Linter in your editor of choice. It will help you avoid critical errors that cause the game to crash from improper JSON formatting. If you really don't wish to use a Linter, then you can use this handy website to debug JSON formatting issues.
 * Windows only.
 * Was used by Threshold during the initial creation of the game.
 * Feature-lite.
 * Has built-in folder navigation under View -> Folder As Workspace.
 * Lightweight on your system compared to the other editors, thanks to a lack of electron.
 * .... As a result, it is the fastest to boot up.
 * Supports packages and customization, though not quite as convenient.

Metadata, the ListofList, and BaseDIR
'''This section will cover how to make your metadata file and mod folder in a beginner-friendly manner. Those who are more technically inclined might find the information redundant and a little lengthy. But, for the sake of keeping the bar of entry as low as possible, every step was explained as directly and clearly as possible. This will go from making the metadata.json file, the mod folder it will refer to, and the contents of your metadata.json file. If you feel confidant, you can just skim to the part where you start seeing code block examples.'''

Let's begin with a in-depth reminder. Your metadata.json file will tell ModLoader what content you want it to use from your mod folder. After the user runs the ModLoader application, your metadata file's data will be organized into ModLoader/lists. This contains the information your metadata.json file provided ModLoader, scattered throughout multiple .json files, which the game will automatically check and load into the the base games "ListofLists" upon playing.

With that explanation out of the way, onto making your metadata file...


 * Go to your game folder, and navigate to
 * Windows: ModLoader\mods. Right click, and create a new file, uniquely titled after the name of your mod, then ending with the file type ".json"
 * macOS: Contents/Resources/autorun/ModLoader/mods. Right click, and create a new file, uniquely titled after the name of your mod, then ending with the file type ".json"
 * Linux: ModLoader/mods. Right click, and create a new file, uniquely titled after the name of your mod, then ending with the file type ".json"


 * Before we begin it is a good idea to know what JSON means. JSON stands for JavaScript Object Notation, so if you already know JavaScript you will already know the syntax.
 * Open your newly created file in your editor of choice. We will now begin writing the contents of your Metadata list, explaining what each one does as we go.
 * Start by making an open curly bracket, a new line with the enter key, and then another new line with a closing curly bracket, Like the below.


 * This is called an object. You can have objects within objects, though in the case of the metadata file, you won't have to worry about that.
 * While they could be on the same line since JSON does not care about whitespace, keeping them on separate lines improves readability for users. Now go to the empty line, and put in:


 * Anything typed within double quotes (such as "name" or "" in the above) is what is called a string. You will be putting most of your content within strings. Any string followed by : is a key, such as "name": in the above. Keys always use strings, and you will not have to fiddle with them directly all that often. Note that whitespace is important when inside of a string.
 * For the "name": key, you will to put the title of your mod in the following empty string. It will display the title of your mod when installing the mod and helps keep this mod uniquely identifiable from the rest. You can freely change this at any time regardless of what you do later without consequence.
 * Lastly, ensure it ends with a comma, so it knows it is okay to move onto the next key. You will otherwise get an error that will prevent ModLoader from processing the metadata file. Do be sure to use a Linter for real-time error warnings or check with a formatting check website often as stated in the Editors section of this guide.


 * Self-explanatory, you describe what your mod does here. It technically isn't needed, but it is encouraged. You can freely change this at any time regardless of what you do later without consequence.


 * Put your name, and anybody else who deserves credit here. It isn't technically needed, much like the "description": key, but it's important to give credit, even if it is just to yourself! Online names will do fine, given the taboo field we're dealing with. You could even use your full discord handle, public email, or anything else so people have a way to contact you. You can freely change this at any time regardless of what you do later without consequence.


 * States which version of the ModLoader the mod is made for, and is used to prevent incompatibility issues. This key is currently not used on a technical level, but it is important to clarify. The current version is 1.2.
 * The lack of double quotes is intentional, as this is a plain number value for the key. Please note you will still be primarily providing numbers in strings in most other cases. This is a rare exception, as you will rarely ever use data that isn't inside of a string while modding.


 * State which mods, if any, are required to be installed before this one. It is technically not used at the moment as a feature of ModLoader, but still serves as a warning to players about what mods they need to load into their game before yours.
 * The use of brackets [] here is intentional, as this is what is called an array. Arrays allow any number of strings to be inside in the scenario a key can be provided with more than one string. Note, each string you provide within the array must still be separated from one another with a comma. The last string marks the end of the array, and thus does not need a comma, so it knows to exit the array and move onto the next key. e.g. ["exampleMod", "anotherMod", "farmMod"]
 * Since you're just starting, it is highly unlikely you have any intended prerequisites, so you can leave the array empty. That's safe to do!


 * The name of the folder directory in which all of your mods content (excluding this metadata file you are making, of course) will be found. This is so the ModLoader knows where to grab the files your metadata file will be referring to is located. With that in mind, let's make one!
 * Go back to the ModLoader/mods folder in your File Explorer/Finder. Right click and create a new folder. Name it whatever you wish, though it is recommended to name it the same as your metadata file. After completing this, make the string for the "baseDir": key with the name of your newly created mod folder. so that ModLoader knows what folder directory your metadata list will be referring to.
 * And with that, all of the base parameter keys for your metadata file are done. From there, after getting comfortable writing some lines, we'll just copy and paste in the actual list of keys you will be using to identify the contents of your mod for the sake of time. It is okay to leave Arrays blank, but do not leave empty strings within the arrays, or else bad things will happen! Start a new line, and copy paste the following into your metadata file...


 * Each of these keys tells the ModLoader what content you have in your mod. You will need all the keys listed in the above code block, not just the ones you intend to use. To add a file all you need to do is to go to the appropriate key, and add a string containing the path inside of the folder you directed it to from your "baseDir": key.
 * For an example, let us say you have a mod named SuperMonsters, with your baseDir as "baseDir": "SuperMonsters". Inside of your SuperMonsters folder, you have a folder titled Enemies and inside it you have SuperSuccubus.json and SuperImp.json then to add both you would do this to the "MonsterList": key, as these would be structured and recognized as Monster JSON files. The folder you contain them in can be named whatever you want. For simplicity sake, you could simply title the folder as "Monster".


 * When stating the file path, you have to use forward slashes, and remember to not have the last string in a a array as a comma.
 * Lastly, notice how the array for the last key called "AddictionLists": doesn't end in a comma? That's because there are no more keys for it to read, thus your object (the curly brackets {} you placed at the beginning) is done and must be told to exit or else-you guessed it-would cause an error and prevent ModLoader from processing your metadata file. JSON files are fickle things. That's why it's highly recommended to use a Linter to avoid these mistakes.

But, it doesn't do much good to list your mod content, if you don't have any content to begin with, yeah? So let's get to how you can approach that... But first, save your work! Either press ctrl + s, or go to File -> Save. You can leave your metadata file up in its tab, or close it now.

If you want a better grasp at how JSON works in general, see here: https://www.w3schools.com/js/js_json_syntax.asp

For an advanced technical explanation, see here: https://www.json.org/json-en.html

The MGD Directory
This is the biggest learning curve you'll have getting into modding. That said, when you get past it, everything becomes breezy. And really, you already have everything you need to learn: '''the main game directory. '''It contains everything you need to learn all the types of JSON files you can make, how to use them, and the functions you can utilize within them. Now, let me introduce you to your new best friend: Threshold.

Learning by example
No seriously, the best way to learn the ropes of modding is to learn from example. And who better than the best of the best? Remember that all of the content he has made for the base game is done in JSON files. That means you'll be making content exactly how he does while modding. There is pretty much no real difference in how you mod, and how he makes content for the game, barring him creating the very functions and keys you will use, and that he doesn't need ModLoader. This should give you an idea of how powerful and flexible modding can be. So, let's go over where you can pick apart and examine his work... Because Threshold is a kind soul, he has also provided blank and example .jsons throughout these folders for modders to learn from and refer to, which can allow you to better grasp how the various of strings within these .jsons work. They can be easily spotted with the _ underscore _ before their name. I'd highly encourage copy and pasting the contents of the blanks as the basis of your JSON files, instead of manually typing all of the strings out.
 * /Json/Adventures | This contains the adventure jsons for the game. Adventures are the first-time runs you do before you fully unlock the location. This also includes all special menu choices you have in the locations map, such as "Shortcut To Nara" or "Visit Amy", telling the game what they require to be unlocked or what event they will point to.
 * /Json/Locations | Locations folder is pretty self-descriptive descriptive, it encompasses all jsons related to the locations you find on the map when you select "Go Adventuring!" from the town. Their icons, default BG and music, unlock requirements, what Adventures it has, and how the exploration via the grimoire will work.
 * /Json/Events | Contains all events and combat events. Combat events would be events specific to combat encounters when just a skill is too simple. An example would be the blue slime asking if you are okay with anal insertion.
 * /Json/Monsters | This will contain all of the monsters in the game, and NPCs. Note how they are organized per location. Outliers like the brothel specific iterations of various MGs, or certain NPCs can be seen not categorized into any particular folder.
 * /Json/Perks | This will contain all of the perks in the game, including monster only perks.
 * /Json/Skills | This will contain all of the skills in the game, including the monster skills.
 * /Json/Items | This will contain all of the consumables, equipment, and key items in the game.
 * Brothel events can be found under Events/Town/Brothel. As a pro-tip, you will want to make use of the MenuAddition function to make your events viewable in the nightlife menu. See the Modding Guide.docx file in the main game directory for more information on the function. More on the Modding Guide.docx later.
 * Note, you will not find fetishes, nor addiction folders here. These are "invisible" in that they don't actually have their own standalone files. They're created and referenced in the various of other .json files. If you wish to see what kinds there are in the vanilla game easily in one spot, head to game/Lists and look at 'addictionList' and 'fetishList' .json files. This is also just a great spot to view where and how the game grabs and sees content from the Json folder, and better understand how mods play in with the mod lists in there. But let's not get too off course.
 * Note that addictions and especially fetishes are very powerful features that internally don't work like any of the other things you can add to the game, as you may have found out from the previous bullet point. While you shouldn't be afraid, you should be certain you need them, as they are not that far explored of a frontier, and changing your mind later on could cause quite the headache. There could be issues yet to be discovered with them.

Note, please refer to late game content over early game content when researching a method of how to do something. The late game content is often where the latest techniques and functions Threshold has made will be utilized, while a lot of the early game content will be some of his earlier work, which might be using functional but dated methods. That said, there are still things you can learn from the older .jsons.

For those interested in the file paths to various of game assets, be it you want vanilla music for your scenes or monster encounters, to utilize certain backgrounds, or even the vanilla sound effects, these folders will be of interest to you. More on them in later sections. Go to the game folder, and head to...
 * game/images | All character art, background art, and generally all visual assets are found here, including vfx.
 * game/music | All music, self explanatory.
 * game/sfx | All sound effects.

Lastly, if you get a wild hair, you should also pick apart the work of other modders to see how they do everything, since they'll always be the closest thing in setup to what you'll be doing.

The Modding Guide, and practice
Moving on from learning by example, would be direct documentation. Meet what will be your second best friend: the Modding Guide. It is located outside in the base of the game directory, titled "Modding Guide.docx". This will contain information on all of the functions you can use, alongside explanations of various functions and how they work. Especially useful for learning about skill functions. Once you are in the thick of modding, you will be referring to this more than anything else.

Lastly, the final and most important method, would be to learn from practicing. There are various of ways you can start, and continue to refine your understanding.


 * Copy the files of a pre-existing MG, and make a variant of them, with custom dialogue, or skills. Adjust their stats. Give them custom loss scenes. It doesn't need to be the most amazing writing, just something to get you familiar with it all. Generic, simple enemies like the Elf, Alraune, or Blue Slime are a good start. Update your metadata file, run ModLoader, and test.


 * Make a basic MG and encounter from the ground up. I'd make it an event in say, the forest, rather than a quest. It's far faster to test events rather than quests. Update your metadata file, run ModLoader, and test.


 * Make additions to pre-existing characters. Note, if you release a mod that modifies vanilla content through additions, such as a pre-existing MG, your mod might break, if Threshold ever updates that character in the future. This can be seen with the long-lived mod, Waifupocalypse, undergoing surgery multiple times to stay functioning. Not as scary nor as common as it sounds, but a fair warning is due. Update your metadata file, run ModLoader, and test.

So go forth. Create a goal for yourself, begin experimenting, and testing out your work in-game as you go. Look at how others do things, both from Threshold and other modders. Examine their work, see how it ticks. The best single tip you could ever be given for modding, is to just start tinkering. Update your metadata file, run ModLoader, and test.
 * .... Or, if you really feel wild, do what many other modders have done despite being ill-advised and directly begin working on your dream project that likely ignited your interest in learning how to mod. What matters most is fueling yourself with the energy you need to reach the finish line. Do whatever it takes to motivate yourself to see through it to the very end. Update your metadata file, run ModLoader, and test.

Brief Music & Art Summary
These don't work much differently from JSON files in how you interact with them, beyond the actual creative process, which this guide will not be covering. You're free to add whatever you please, just do try to be sensible not use copyrighted materials in a reckless manner. Give credit to your sources.

All one has to do when adding their own game assets like music or art, is include it in your mod folder. No need to put them in the metadata file!

Note that when referring to the filepath of your assets via functions in your .jsons, you will be naturally fighting the default vanilla filepaths that are hard-coded in the functions. As such, you will typically be using a file path similar to the code block below.

To explain, ../ tells the game that you wish to go back a directory. So if you were in Directory/FolderA/FolderB, using ../ will take you to Directory/FolderA. Any image, music, or sound will require you to go two folders back up. Map related assets are three directories deep (game/images/map), so you will need to use ../ thrice in cases where you are making a new location on the map.

In-game Console
The in-game console can be very useful for debugging and testing your mod at a rapid pace, without having to manually build up a save towards what you want manually. See here for the Console page.

Releasing
When you feel your work is ready to be shared with the world, you'll have a couple of choices on how you can go about uploading it and making it easily accessible for all to find. No worries, as there are more than plenty of free file hosts out there!

... The trick is finding ones that allow mods for NSFW games.

Uploading

 * Mega is a popular one for its flexible TOU, file cap size, and download speed. However, you may run into long term hosting issues. It also requires an account. This was a common choice for MGD modders.
 * Anonfile has a very flexible TOU, good download speed, a large file cap of 20GB, and what is assumed to be lifetime hosting. While it has yet to be used to host an MGD mod, there are plenty of other NSFW projects that have used this platform as their host.
 * For the technically inclined, Github has proven to be a very advanced and appealing hosting platform, as it doubles as a place for people to download your mod, and to help you manage your work. Especially useful for those who intend to collaborate on mod projects. Given its more advance use-case, it isn't a good choice for those wishing for as simple of a modding experience as possible.
 * Lastly, the MGD Discord. Simply upload your mod alongside your post in #mod-posting, and share the download link anywhere else, without requiring the downloader to fire up Discord. The server can currently handle mods up to 50MB in size.

Where to share
There are two key places you are encouraged to share the link to your mod. Otherwise, you're free to share it anywhere you like, at least, as far as you can with something like this.
 * The Mod List page on the wiki. There is a tab in the How-To Guides section for how you should format and include your mod in the list, for the sake of keeping a clean presentation. Don't sweat it too hard. The popularity of downloads here is only second to...
 * In #mod-posting on the MGD Discord. This makes up for a majority of mod downloads during your first week or two of launch, then most traffic will be coming from people checking the Mod List. If you want instantanous exposure and feedback for your creation, this place will get you it.

Help
If you need help, please get on the MGD Discord. There are tons of knowledgeable, depraved, and friendly people there willing to help you, no matter how big or small your problem is. Head to the #modding-help channel towards the bottom of the list. You can also leave comments down below on this page, though it may take longer to get a response in comparison.