Tutorial: How to create a simple mod?

Hi!

Welcome to the first tutorial about modding Sex Purgatory!

In this tutorial I will explain how the mods are working in the game and I show you how you can create your own mod. We will create a donut 🍩 item which will be restoring food points anytime the player eats it. I hope everything in this tutorial will be clear, but if you spot any errors in it, don't hesitate to tell me this in comment so I can fix any issues in this tutorial.

Before we start, make sure you've started the game at least one, so every important directory or file is properly initialized. Also, make sure to force your system to always show full file names with extensions. To do this, go to your system setting and search "file extensions", click search hint "Show file extensions".

Then click "Show Setting" in File Explorer section and make sure option "Hide extensions for known file types" is unchecked. Don't forget to apply options 😉.

The Basics

First and foremost, we need to find all the important directories and files. Locate your game's folder, it contains main game executable ("SP.exe"), folders like "Engine" and "SP" and some other stuff. Go through "SP" directory, then "Addons", and now look for "Mods" folder (If you are seeing other directories or files, don't worry I've placed them here to test some features in game and I left them to keep the game functional, but don't touch any folders besides "Mods"). You can enter "Mods" directory. The "Mods" folder is one of the most important directories in the game. The "Mods" folder in game folder contains mods which will be added or updated after you run the game (you'll get more explanation after we find other important directories). In this folder there is one directory called "_base". You can explore it a bit if you like, but don't change anything in this folder. If you want to proceed to the next step of this tutorial, please return to "Mods" directory and keep the file explorer open.

Now, we need to know where the mod files are stored on our computer. Press [Windows] and type "%localappdata%" then press [Enter]. Now you need to find "SP DATA" directory. Notice that there is also a directory called simply "SP", but this folder is created by UE5 and contains miscellaneous config files only for the game engine itself, but we need to open "SP DATA" instead to get access to mod files. Open "SP DATA" and if you are seeing "mods" and "profiles" (and probably some other directories) you successfully found our game's main data folder!

Now some theory

These are the main elements that are making the mod system possible in Sex Purgatory. Here you can read about their purpose:

• %localappdata%/SP DATA - the game's main data directory. Contains all vital parts of the game, like mods and profiles.
• %localappdata%/SP DATA/mods - contains all the mods currently available to the game's mod loader.
• %localappdata%/SP DATA/profiles - contains all custom profiles in the form of text files. Profiles are lists of the mods that are loaded on start of the game. For example, when you don't want to use some mods, you can simply create a new profile and specify all the mods you want to load when the game runs this profile.
• %localappdata%/SP  DATA/profiles/_currentProfile.txt - special text file. The game will find and run the profile based on this file content. For example: if it contains "my_favorite_mods", then the game's mod loader will go to "%localappdata%/SP DATA/profiles/my_favorite_mods.txt" file and will try to load mods from this profile.
• {Game folder}/SP/Addons/Mods - directory contains all the mods that will be copied on each game startup. All the content will be copied to "%localappdata%/SP DATA/mods" directory, so all the mods in this folder will be overwritten each time you run Sex Purgatory game.

When you start the game, mod loader will first update all the mods from game folder to make sure every time Sex Purgatory receives content update you have the newest version of the game content. Next, the mod loader will load all mods listed in current profile. After that, the game profile is loaded and you can play the game.

Your first mod structure

So, let's make our very own custom mod for Sex Purgatory! In this example, I'll make a mod which add a simple food - donut, and the player would spawn it from Item Panel and eat it in game to restore some food points.

Firstly, we need to create our mod structure. Go to "%localappdata%/SP DATA/mods" and create folder "My First Mod" (you can name it whatever you like, mod system don't care on mods folder names). Open this folder, then create a file "mod.txt" and open it in your favorite text editor. "mod.txt" is a simple text file that Sex Purgatory will recognize and read information from it about mod.

Let's write some mod info in it:

id=my_first_mod
name=Tutorial Mod Name
author=Your name goes here
description=This mod adds some custom content to the game.
version=0.0.1
gameVersion=Alpha 0.8.1
icon=icon.png

Let's explain shortly these lines:

We also need to provide a main code file which will be run by Sex Purgatory's mod loader. To speed things up, just copy the "main.impulse" from "%localappdata%/SP DATA/mods/_base" directory and paste it in your own mod folder ("%localappdata%/SP DATA/mods/My First Mod"). This file contains special code written in Impulse language, an assembly-like code syntax created to customize Sex Purgatory content. There is one thing left: we need to make sure mod loader will load the profile with basic game content and our mod. To do this, we need to create a game profile containing these mods IDs. Go to "%localappdata%/SP DATA/profiles" and create a new text file "my_custom_profile.txt".

Let's populate it with data:

name=My Custom Profile
mods:
sex_purgatory
my_first_mod
:

Here is another neat table explaining these values:

And now let's tell mod loader to load "my_custom_profile" as the current game profile. Open "_currentProfile.txt" and replace "default" with "my_custom_profile". Now you can run the game. If you can see your mod in Mods panel in game, you've done everything correct and your mod loads properly!

How to add basic item?

In your mod directory create a new directory named "items" (from now on, you need to follow folder naming convention, because main.impulse file depends on proper folder structure in mod directory). Open it and add new .json file: "donut.json". JSON file format is a special text file used to store data. This file will be used to create a new item definition in Sex Purgatory. Now we need to write some data:

{
    "name": "Donut",
    "value": 1,
    "weight": 0.1,
    "image": "undefined",
    "data":
    {
        "mesh_0": "undefined",
        "material_0_0": "undefined",
        "class": "food",
        "food": 25
    }
}

You can define items like this with these variables:

If you now play the game, you'll notice a missing texture in the Item Panel. Since we didn't define a proper item image, the default appearance is classic magenta-black checkerboard. You can now use the item to restore 25 food points.

Coming soon...

For now, this is how to add a very basic item to Sex Purgatory. In the next tutorial, I cover how to add 3D meshes and textures, so our donut won't look like a glitch from a poorly written creepypasta story.

If you spot any error, missing information, or I didn't cover any topic completely, and you don't understand it, please write in the comments below what I can get better in the tutorial. I know this is very technical, but I think it's better to understand by people who are interested in game designing stuff.

Anyway, thanks for your time, and hopefully see you in the next tutorial! 😁