Home Report an Issue /docs/modding-basics/

Modding Guide: Modding Basics

Using Mods

If you’re an end user looking to learn how to install a mod, see the page Add and Configure Mods.

Developing Mods

Enigma Engine is home to a powerful and useful tool known as ModCore. ModCore makes it easy to append, replace, or merge files without editing the game’s code.

Enigma Engine’s ModCore is powered by Polymod. Polymod is what handles loading the relevant assets, ensuring they are injected properly. It also handles ensuring mods are loaded in the proper order. The basic premise is that mods within the mods folder of your Enigma Engine install will be automatically loaded into the game.

Currently, ModCore allows users to do the following:

This page has a quick breakdown on how to make a basic mod, along with a more detailed explanation and some pro tips. If you’re looking to skip past the nitty gritty, simply follow these steps to make a simple mod:

Creating an Mod

The creation of every mod starts with these steps:

  1. Create a folder. The name should be lowercase, alphanumeric with dashes. You’ll be able to specify a full title with symbols and stuff later.
    • If you downloaded Enigma Engine from the link above, place the mod folder within the mods directory next to Enigma Engine.exe.
    • If you’re building Enigma Engine from source, place the mod in the example_mods folder. It will be automatically copied into the mods folder when you build.
      • Pro tip, if you’re just making a basic mod, or even a more complex mod, you shouldn’t need to modify the source or rebuild the game! Just download the game and put your content into the mods folder.
  2. Create a _polymod_meta.json file inside your newly created mod folder. Paste in the following content, modifying the title, description, and author as necessary. 
    {
 "title":"Example Mod",
 "description":"This is an example mod!",
 "author":"Foobar",
 "api_version":"0.1.0",
 "mod_version":"1.0.0",
 "license":"CC BY 4.0,MIT"
}
  3. (Optional) Create a _polymod_icon.png file inside your newly created mod folder. This is the icon that will be displayed in the mod menu.
  4. Place your assets into the mod folder. For example, a simple Boyfriend skin mod would look like this once installed: |- Enigma Engine |- Enigma.exe |- mods |- enaOverBf |- shared |- images |- characters |- BOYFRIEND.png |- BOYFRIEND.xml |- _polymod_meta.json |- _polymod_icon.png
  5. You’re done! The mod is now installed and ready to use. You can enable it by selecting “Play with all mods” or “Configure Mods” from the starting screen.

Metadata

You will want several pieces of metadata in order for Enigma Engine to identify and display your mod. Only _polymod_meta.json is mandatory, while other mods are recommended.

_polymod_meta.json

Here is an example of a valid mod metadata file.

Note that both api_version and mod_version should use valid Semantic Versioning 2.0.0 values.

{
	"title":"Daisy",
	"description":"This mod has a daisy",
	"author":"Lars A. Doucet",
	"api_version":"0.1.0",
	"mod_version":"1.0.0-alpha",
	"license":"CC BY 4.0,MIT"
}

Assets

You can create complex and elaborate mods simply by adding the relevant assets to your mod folder. By adding song data files to the data/songs folder, the game will be able to detect and load them if you add the relevant data to the weeks

Adding and Replacing

Asset additions and replacements are simple; just place the assets in the relevant subfolder.

Here’s what the mod folder might look like for a simple “XXX over Boyfriend” mod.

<modRoot> (name this anything)
|- _polymod_meta.json
|- images
  |- characters
    |- BOYFRIEND.xml
    |- BOYFRIEND.png
|- data
  |- characters
    |- boyfriend.json

Some tips:

Appending

Appending to assets is only slightly more involved. Appending is used when you want to add to the end of a particular text file without getting rid of what’s already there.

For example, using the above method on introText.txt will get rid of the base game’s intro text values, as well as any that other mods may have added. This may or may not be what you want. Appending will put your values at the end of the file for other mods to add to.

To perform asset appending, place the assets in the relevant subfolder under the _append folder, like so. Note the underscore before it.

<modRoot> (name this anything)
|- _polymod_meta.json
|- _append
  |- data
    |- introText.txt
    |- freeplaySonglist.txt

Some tips:

Merging

Merging is the most powerful yet the most convoluted method. Use it only if you can’t use replacement or appending.

Merging locates a given key in a file and replaces it with the intended value.

Modpacks

To create a modpack, make a mod containing a _polymod_pack.txt file with the following text:

foo:1.0.0,bar:1.*.*,abc,xyz

ModCore will search for, and load, the mods with the IDs foo, bar, abc, and xyz, in that order. It will fail any mods that fail the version check (foo must be exactly 1.0.0 while bar allows any 1.x version) and only load the mods which don’t fail.

Scripts

Coming soon…

Distributing Mods

The ideal means of distributing a mod is by creating a mod folder and distributing it, so that users can download Enigma Engine and install the mod themselves (or, in the future, use a tool that helps them do that).

However, if you are still set on distributing your mod as a standalone executable, here are the steps to follow for that:

Although this method of creating mods is not the preferred method (ideally you can distribute mods in both formats for the purposes of forwards compatibility) it is still officially endorsed, and you may create issues and bug reports related to it.