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.'''

Overview
It is important to know how content is created in Monster Girl Dreams first, to understand how you will be modding.

All of the games content is made in a text file format called JSON. It is neatly found in a single folder in the games main directory (more on how to get there on each platform later), titled "renpy". 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 and temporarily inject into its "ListofLists", which it later uses to find all of the content it will need. 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/IDE support. (Search for "atom-ide-ui" and "json-ide" packages)
 * Built-in folder navigation.
 * Highly 'hackable' (read customizable)
 * Git integration. (If you don't know what git is, don't sweat it and move on)
 * Github integration. (If you don't know what github is, 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, useful for linter/IDE support. (Search for the package simply called "JSON")
 * Customizable.
 * Git integration.
 * Github integration possible.

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 IDE or 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 JSON IDE or Linter, then you can use this handy website to debug JSON formatting issues.
 * Windows only.
 * Battle-tested.
 * Was used by Threshold during the initial creation of the game.
 * Feature-lite.
 * Lightweight on your system compared to the other editors.
 * .... As a result, it is the fastest to boot up.
 * Supports packages and customization, with some effort. (Including JSON IDE/Linter solutions)

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, titled whatever you want, then ending with the file type ".json"
 * macOS: Contents/Resources/autorun/ModLoader/mods. Right click, and create a new file, titled whatever you want, then ending with the file type ".json"
 * Linux: ModLoader/mods. Right click, and create a new file, titled whatever you want, 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:


 * While they could be on the same line since JSON does not care about whitespace that is outside of double quotes (""), keeping them on separate lines improves readability for users. Now go to the empty line, and put in:


 * Anything typed like "blank" is what is called a string, to which you will provide content within the pair of double quotes (""). This one in particular is where you will put the name of your mod (within the ""). The name will be displayed when installing the mod and helps keep this mod uniquely identifiable.


 * Self-explanatory, you describe what your mod does here. It technically isn't needed, but it is encouraged. You could use the same description for your section on the mods list wiki page to boot.


 * Put your name, and anybody else who deserves credit here. It isn't technically needed, much like the "description": string, but it's important to give credit, even if it is just to yourself! Online names 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.


 * States which version of the ModLoader the mod is made for, and is used to prevent incompatibility issues. The version is a number, numbers have no double quotes. Beware some programs may expect numbers in the string form. Currently not used on a technical level, but it is important to clarify. As of this writing, the current version of ModLoader is 1.2.


 * State which mods, if any, are required to be installed before this one. This is an array which allows any number of things to be inside but each must be separated with a ,. 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. If your mod requires other mods, then in between the brackets ([]) add a string for each mod with the name of the mod, e.g. ["ExampleMod", "FarmMod"].


 * The name of the folder directory in which all of your mods content but the metadata file will be stored. With that in mind, let's make one! Go back to the mods folder in your file explorer/Finder. Right click, and create a new folder. Name it whatever you wish, though it is probably best to name it the same as this metadata file. After completing this, put the same exact name within the double quotes so that ModLoader knows what folder directory your metadata list will be referring to.
 * And with that, all of the base strings 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 strings you will be using to identify the contents of your mod for the sake of time. Remember that it is okay to leave strings blank. Start a new line, and copy paste the following into your metadata file...


 * Each of these properties tells the ModLoader what content you have in your mod. To add a file all you need to do is add a string to the appropriate list with the path relative to your BaseDir to the property. For example let us say you have a mod named SuperMonsters with the BaseDir SuperMonsters and inside it you have a folder Monsters and inside it you have SuperSuccubus.json and SuperImp.json then to add both you would do this to the MonsterList:


 * You have to use forward slashes, and remember to have the last piece of data in each array (arrays are made with []) and object (objects are made with {}) to not include a comma to ensure that this is a valid JSON file, otherwise the file can't be read properly. JSON files are fickle things.

But, it doesn't do much good to list your mod content, if you don't have any content yet, yeah? So let's get to how you can do 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.

For a full explanation of JSON, you can view this: 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 strings 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. 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.
 * /renpy/perks/thePerks | This will contain all of the perks in the game, including monster only perks.
 * /renpy/skills | This will contain all of the skills in the game, including the monster skills.
 * /renpy/items | This will contain all of the consumables, equipment, and key items in the game.
 * /renpy/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.
 * /renpy/adventure | This contains the quests, adventures (those first-time runs through a location), general 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.
 * Note, you will not find fetishes, brothel events, 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, often in /renpy/adventure. If you wish to see what kinds there are in the vanilla game easily in one spot, head to renpy/Lists and look at "addictionList", "brothelList", and "fetishList" .json files. This is also just a great spot to view where and how the game grabs and sees content from the renpy folder, and better understand how mods play in with the mod lists in there. But let's not get too off course.

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 maybe even the vanilla sound effects, these folders will be of interest to you. More on them in later sections. Go one step out of the renpy folder, and proceed 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, outside of the renpy folder, titled "Modding Guide.docx". This will contain information on all of the functions you can use, alongside explanations of various strings and how they work. Especially useful for learning about skill strings. 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. 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. For the sake of making the process of testing your mod easy. Update your metadata file, run ModLoader, and test.


 * Make additions to pre-existing characters. Note, if you release a mod that expands on a pre-existing MG, if Threshold ever decides to return to that character. your mod might break. This can be seen with Waifupocalypse, which has had to undergo surgery multiple times to stay functioning. Not as scary as it sounds, but still a fair warning. Update your metadata file, run ModLoader, and test.

So go forth. Create a goal for yourself, begin experimenting, and working on your mod! And really, give a look at how others do things, both from Threshold and other modders. Examine their work, see how it ticks. But remember, the best single tip you could ever be given for modding, is to just start tinkering.
 * .... Or, if you really feel wild, do what many other modders have done and directly begin working on your dream project that likely ignited your interest in learning how to mod MGD to start with. 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, and add the path to your metadata file, just like you would with a .json. The key difference is to specify what type of file it is at the end of the file path. So if it is an mp3 file, make sure it says .mp3 at the end, a png, .png, etc.

In-game Console
'''NOTE: This section is intentionally left as a stub. A page for console commands is currently being worked on. It will be linked here as soon as it is ready!'''

The in-game console can be very useful for debugging and testing your mod.

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 key 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 has commonly been the choice of 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. Though it has yet to be used to host an MGD mod. However, many other NSFW projects have been hosted on there.
 * 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 the server can currently handle mods up to 50MB in size. You are free to copy the download link and share it anywhere else, without requiring the downloader to fire up Discord. It would function like any other direct download link.

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. If you want exposure 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.