# INSTRUCTIONS FOR GENERAL MODDING

Dicey Dungeons mods use the Polymod format, which you can read about here:
https://github.com/larsiusprime/polymod

This "data" folder contains all the data in the game. When you create a mod,
you'll create a separate folder that the game uses to replace or modify the
contents of this one, but without having to directly mess around with these
files. If you're trying to mod by changing the game's default data files
directly, you're doing it wrong!

# Creating a new mod

Create a folder called "mods" (all lowercase) and place it in the default Dicey
Dungeons mod location. As of this writing (2018-09-12), that location is:

<Dicey Dungeons Root Directory> (right next to the executable)

Next, you'll want to create a mod folder inside of "mods". You can give it any
name you want, but it must adhere to these rules:

* All lowercase
* Alphanumeric ASCII (only letters and numbers, and only basic english alphabet)
* Underscores are allowed but no other symbols of any kind
* Should not have the same name as any other mod you plan to use

So let's say I've created a mod called "abc", that will go in this location:

<Dicey Dungeons Root Directory>/mods/abc/

Within that folder you should add two more so that you have this structure:

<Dicey Dungeons Root Directory>/mods/abc/

<Dicey Dungeons Root Directory>/mods/abc/_append
<Dicey Dungeons Root Directory>/mods/abc/_merge

The first directory is the "abc" mod's *root* directory.

The second directory is the "abc" mod's *append* directory.
The third directory is the "abc" mod's *merge" directory.

Any files in the mod's root directory will *replace* files of the same name in
the default game files. So if you put a file named
"data/graphics/titlescreen/title_english.jpg" here, it will replace the title
screen.

Any files in the mod's append directory will attach their content to the *end*
of files of the same name in the default game files. So if you put a file named
"data/text/items.csv" here, it will attach the content lines after the header
fields
from your file to the end of the base game's item database.

NOTE: for CSV-type files headers are *required*. This is because when the
game engine gets updated, there may have been new columns added into a major
spreadsheet. This would normally break compatibility with mods that used the
previous
format. However, since the mod's CSV files provide header information, the engine
can
usually figure out how to interpret the data with less chance of breaking
something.
So long as the modding API of the mod is compatible with the engine's modding API
under
semantic versioning rules, the game will always try to do this.

Any files in the mod's merge directory will inject their content at a specified
location inside files of the same name in the default game files. This is a more
complex and error-prone operation that's only recommended for advanced users.

# Running a mod

Once your mod is set up, you can load it in by running the DiceyDungeons
executable from the command line like this (assuming Windows):

DiceyDungeons.exe mod=abc

That will make Dicey Dungeons look for the "mods/abc" folder and load in that
content.

You can also do this, however:

DiceyDungeons.exe mod=abc,123

That will load BOTH the "mods/abc" folder *and* the "mods/123" folder, and apply
their changes to the game's default data set in that order. There is no limit to
the number of mods you can combine in this matter, though there's no guarantee
any two mods will work properly together, and the more you load the more likely
something is to go wrong.

# Creating a mod pack

You can create a "mod pack" if you want to skip having to type the names of
several mods in a specific order every time. To do this, simply create a new
mod folder in "mods" and inside it create a single file named "_polymodpack.txt"
The only contents of this file should be a comma-separated list of mod ids. This
represents which mods you want to combine and in which order. So if you have a
mod "abc" and a mod "123", then you could create a mod called "mypack" that has
a _polymodpack.txt file with the following contents:

abc,123

In this example, invoking:

"DiceyDungeons.exe mod=mypack"

will be equivalent to:

"DiceyDungeons.exe mod=abc,123"

Note that if a _polymodpack.txt file is found, ALL other content in that mod
folder will be ignored. As of now, you cannot include any other content in a
mod pack. If you want to use mod packs to control dependencies, you should
create a separate individual mod, then create a modpack for it including the
both it and the mods it depends on.

# Troubleshooting & Errors

From Mod API 0.4.0 and up, the game will aggressively emit error information
regarding mods. The idea is that it is better to emit noisy errors with
meaningful information about how mods can be quickly fixed, rather than have
mods silently fail in subtle ways and give no information.
A WARNING is a non-fatal issue that should be addressed ASAP, but will not
block the game from running or the mod from loading.

The most common causes of warnings are missing icons and metadata files, and
any mismatch in Mod API version number while the game is still in pre-release.

An ERROR is a serious enough issue that the game anticipates a crash if the
mod isn't fixed -- the game will close immediately and emit a message about
how to fix the error rather than attempt to continue.

The most common causes of errors prior to mod API version 0.4.0 are missing
headers from CSV files. From now on, all CSV files will require these so
that we can minimize the amount of broken mods between releases. If you
receive this error message, the best way to fix it is to open the master
CSV file, copy the header files, and re-enter your data with the header
line included.

# TODO:

Modding is still WIP. This document will expand as more features come online.
Yes, a GUI interface for all this is planned. This is just the first step.
Thank you for pardoning our dust.