Modding

This page is to serve as a basic modding guide.

## Disclaimers

This guide assumes you know some programming basics.

Even if you don't, **experimenting is key!**

**This guide is in no way complete. If you are able to contribute, please do!**

Spoilers ahead, proceed with caution!

You will also want to have the Haxe documentation on hand, and the more accessible Haxe Code Cookbook.

## Creating a mod's structure

Open your Dicey Dungeons folder and go in *mods*. If there is no *mods* folder, create it.

In the folder create a new folder with the name of your mod.

Create 2 more folders in the mod's folder with the names *\_append* and *\_merge*, these will be used to add to CSV spreadsheets and modify particular rows in them respectively.

In each of these 2 folders, add a new folder named *data*. This one will contain the actual items, contestants, etc.

Create another *data* folder alongside *\_append* and *\_merge* for changes to contents of files that do not work with \_merge, such as generators and graphics.

Add *\_polymod\_icon.png* in the mod's folder, this will be your mod's icon - though it is never displayed anywhere yet.

Add *\_polymod\_meta.json* in the mod's folder, this will your mod's displayed name and description.

### \_append

This folder will be used to add new content without modifying currently existing content.

More about this further.

### \_merge

This folder will be used to modify specific parts of existing content without adding any.

More about this further.

### \_polymod\_icon.png

This is a simple .png image that should represent your mod. This is not actually displayed anywhere at the moment.

### \_polymod\_meta.json

This is a JSON file that contains some data about your mod. You can just copy and paste another mod's \_polymod\_meta.json here and then modify its contents to correspond to your mod.

The file should at least contain a title (the mod's name) a description, an author (you), an api\_version (should be the latest), and a mod\_version.

### Other files/folder

You are also free to add any other file and folders, but these won't be loaded automatically by the game.

## Adding new things and changing the others

Just like your *\_append* and *\_merge* folders have a data folder, so does the game, making it much easier for everyone to see how it works. (Note that your mod should *never* rely on the game's actual files being changed, instead you should put your changes into the "data" folder of your mod there.)

### animations

If you know what it does and how to change it, replace this category.

### fonts

If you know what it does and how to change it, replace this category.

### graphics

If you know what it does and how to change it, replace this category.

### text

Most of this folder will contain .csv files. These are really easy to create and modify, just open Excel or LibreOffice Calc and you'll see a ton of stuff. It's also recommended to copy-paste the column names, as these are what the game uses to get the values.

* challenges.csv contains the bestiary entries unlocked along with challenges. You cannot add new challenges yet.
* characters.csv contains all the game characters. Adding your own probably isn't just as simple as adding them there.
* credits.csv contains what you'd expect. You can add your own page if you want to supply credits for your mod.
* dungeonstyles.csv contains information for the different styles each floor can have. If you want to add your own, you'll also need to add stuff to graphics\.
* episodes.csv contains all the episodes and the scripts they run.
* equipment.csv contains all the equipment. All of it. Gadgets are not equipment.
* fighters.csv contains your enemies. It's understandable if you want to make them weaker.
* items.csv contains button effects - the Inventor's gadgets, the Robot's jackpot rewards in Parallel Universe and Bonus Round, and all limit breaks.
* levelpacks.csv is for a currently unused description applying to the mod's set of episodes. This will likely be used once support for custom episodes that don't overwrite existing episodes is added.
* remix.csv contains all the bonus round rules. New rules can be added as you please.
* statuseffects.csv, as you'd expect, contains the status effects. Currently all of the status's effects are hardcoded, so any new status effects you add here will do nothing (though equipment can still check for them, and they will still show up when inflicted upon someone.)

There are also a few more files, such as *achievements.xml*, which contains all the achievements, *audiosettings.txt*, "For specifying overwrite rules about how music is played in-game", *modsettings.json*, giving you a few debug features, *progresssettings.txt*, which is a quick hack for the Halloween mod and allows disabling normal progress.

To do: go into more detail about some of the CSVs with lots of columns, such as equipment.csv and episodes.csv?

## Testing your mod

At this point, you probably have a mod ready to be used, but it's best to check that everything works well first!

To do this, launch Dicey Dungeons with the mod loaded, either through the command line (*mod=<modname>*), or with the mods menu (this will restart the game with the mod(s) selected). It's better practice to launch through the command line or with a .bat shortcut, as this may reveal some debugging information upon crashes that the normal error message does not supply. ("Null Object Reference" will not tell you that you missed a bracket in your item's script, for example - and some scripts may silently fail *without* crashing the game, giving the impression that they are doing nothing whatsoever.)

On the main menu, press shift and click *credits*, which will be replaced by *editor*. You will get a small message and a warning. You will have access to **all** items in the game and **all** enemies too.

Just select a fighter on the left with *change*, make sure you **read the warning at the top**. When you're done, select an enemy on the right (or press random if you don't care who you're fighting).