Modding

Dysmantle has no official support for modding and it is advisable to back up all of your game files before proceeding, but if you want to mod the game here are a few guides as to how to install and create mods.

Platform Support
 iOS
 MacOS
 Nintendo Switch
 Playstation
 Proton(some Linuxes, SteamOS, Steam Deck)
 Windows
 Xbox

## Installing Mods

### Installing Pak Files

1. Download the mod.
2. Decompress the downloaded file. Mods can be `.zip`, `.rar`, or `.7z` files. For `.7z`, use 7zip (external link). Once decompressed, you should have a `.pak` file. If the mod contains folders of other types of files with no `.pak`, refer to the Installing Loose Files section instead. Be warned that that method is more involved.
3. Move the `.pak` file to your game folder. This can be found in:
	* Steam:
		+ `C:\Program Files (x86)\Steam\steamapps\common\DYSMANTLE\`
		+ `D:\SteamLibrary\steamapps\common\DYSMANTLE\`
	* GOG:
		+ `C:\games\DYSMANTLE\`
		+ `D:\games\DYSMANTLE\`
4. Open the file `prog.xml` in your game folder in a plain text editor such as Notepad or Notepad++ (external link).
5. Look for a line in `prog.xml` that starts with `addon_packages="data` . This is a comma-separated list of the data files the game needs to load. If there is no such line, add it under the node of your platform, for example under: `<node id="WINDOWS"`
6. Append the name of the mod to this list, without the `.pak` file extension.
	* For example, if you started with:
		+ `addon_packages="data-gfx2160"`
	* If your mod file is called `example_mod.pak` you should end up with:
		+ `addon_packages="data-gfx2160,example_mod"`
	* And if you add more mods, the line should look something like:
		+ `addon_packages="data-gfx2160,example_mod,tank_engine_mod,pokemon_mod"`
	* ALWAYS add the mods to the very end of this list unless the mod developer tells you otherwise. This is because the order in which files are loaded is important.
	* Mods in the past advised to edit the line `packages="`, but that does not work on some platforms, so the current best practice is to use the `addon_packages="` line in the future on every platform. To migrate, move every mod you installed from the `packages="` line to the `addon_packages="` line.
7. Save the file.
8. Start the game. The mods should be installed now.

You will need to edit the `prog.xml` in this way every single time the game updates. This is because when Dysmantle updates, it will reset `prog.xml` to its original contents and your mods will stop working until you once again edit `prog.xml`. If a game update changes the game files that the mod uses, the `.pak` may become outdated and require an update.

Mods created earlier than 2023 are likely outdated and probably no longer work without manual changes. If you find mods which tell you to modify `.xml` files other than `prog.xml`, the process is much more involved. Instructions for that are in the next section.

### Installing Loose Files

#### First Time Setup

1. Download the modding kit and unzip it wherever you like.
2. In the `modding_kit/tools` folder, create 2 new folders called `original-files` and `mod-files` . The first will hold the unmodified game files, and the second will hold the mod pack files from all the mods you want to install.
3. Open your Dysmantle game folder. This can be found in:
	* Steam:
		+ `C:\Program Files (x86)\Steam\steamapps\common\DYSMANTLE\`
		+ `D:\SteamLibrary\steamapps\common\DYSMANTLE\`
	* GOG:
		+ `C:\games\DYSMANTLE\`
		+ `D:\games\DYSMANTLE\`
4. From your Dysmantle game folder copy `data-windows.pak` and paste it into `original-files`. If the mod includes separate high res graphics, also copy and paste `data-windows-gfx2160.pak` into original-files.
5. Open the `tools` and `original-files` folders side by side. One at a time, drag and drop the `.pak` files from `original-files` onto `nx-pak-tool.exe`. This will unpack all the game files into `original-files`. You'll need to do this step again whenever the game has an update to get the latest original files.
6. If the mod includes separate high res graphics, copy the unpacked `data-windows-gfx2160` folder from `original-files` into `mod-files`. We'll be overwriting the art in these files to make changes, and we need to include everything so it all loads into the game.
7. Inside the `mod-files` folder create a new folder called `mod-pack`. We'll put our modified data files in the `mod-pack` folder. Unlike the gfx folder that needs everything, we only need to include our modified files in here.

#### Assembling the Mod Pack

1. Download the mod.
2. Decompress the downloaded file. Mods can be `.zip`, `.rar`, or `.7z` files. For `.7z`, use 7zip (external link). Once decompressed, you should have a folder of loose files matching those in the game. If the mod contains a `.pak` file and doesn't instruct that it needs to be merged with other files, refer to the Installing Pak Files section instead. It's a much simpler method.
3. Copy the contents of the mod into `mod-files/mod-pack`.
	* Make sure the files end up in the same folders as they are in `original-files`.
		+ For example, if the mod changes the `crowbar.nut` file, make sure it's copied into the `mod-pack/items/tools` folder, as it is in the original game files, otherwise the modded file won't take effect.
	* If a file would overwrite those already in the `mod-pack`, do not overwrite. You'll need to take extra steps.
		+ If the mod changes a shared file, like `recipes.xml` or `inventions.xml`, the contents must be merged into the original game file along with any other mods which modify the same shared file. Refer to the Merging Mod Files section.
		+ If the mod changes an individual file that another mod in your pack already changed, like an item `.nut` file, the mods are probably incompatible unless you selectively merge each line. Attempt this only if you know what you're doing.
4. If the mod includes high res asset files, copy those into `mod-files/data-windows-gfx2160` and overwrite existing files.

#### Merging Mod Files

If the mod includes files which need to be merged with original game files and/or other mods, complete these steps. Otherwise, skip this section.

1. For this section, we'll use `recipes.xml` as an example. Similar steps will work for other shared files, but the contents will look a bit different. If this is the first time you're merging this file into your mod pack, you'll need to start with the original file.
	* For example, if the mod changes `recipes.xml`, copy the `recipes.xml` file from `original-files/data-windows/dysmantle` to `mod-files/mod-pack/dysmantle`. We'll be combining the modified recipe contents from all mods into this file.
2. Open the main `recipes.xml` and the mod's `recipes.xml` in a plain text editor such as Notepad, Notepad++, or VS Code.
3. You'll notice that the original file is a big list of similar looking blocks, and the mod will have one or more of these blocks in its file.
	* For example, in `recipes.xml` there is a list of `<node id="ITEM_NAME" ... />` blocks inside the `<array id="RECIPES">` container.
	* Copy and paste all of the mod's node blocks into the bottom of `recipes.xml` above the line `</array>`. Remember to save the file.
		+ For example, the bottom of the original `recipes.xml` looks like this:

````
  <node id="OBELISK_OF_FIRE"
   category="OBELISK"
   display_name="Obelisk of Fire"
   key.FLOAT.critical_hit_chance_absolute_increase="6"
  />
</array>

````
If the mod includes changes to, for example, the baseball cap item:

````
  <node id="BASEBALL_CAP"
   category="CRAFTING"
   level_requirement="1"
   requires_materials="1xSCRAP_FABRIC"
   output_item_id="items/headgears/baseball-cap.nut"
   upgrade_1_materials="1xSCRAP_FABRIC"
   upgrade_2_materials="1xSCRAP_FABRIC"
   upgrade_3_materials="1xSCRAP_FABRIC"
  />

````
You would then copy this modified block into the original file like so:

````
  <node id="OBELISK_OF_FIRE"
   category="OBELISK"
   display_name="Obelisk of Fire"
   key.FLOAT.critical_hit_chance_absolute_increase="6"
  />

  <node id="BASEBALL_CAP"
   category="CRAFTING"
   level_requirement=""
   requires_materials="1xSCRAP_FABRIC"
   output_item_id="items/headgears/baseball-cap.nut"
   upgrade_1_materials="1xSCRAP_FABRIC"
   upgrade_2_materials="1xSCRAP_FABRIC"
   upgrade_3_materials="1xSCRAP_FABRIC"
  />
</array>

````
Repeat this for each mod which changes the `recipes.xml` file, copying their blocks in after each other
Repeat this section for any other files which need to be merged between mods.

#### Installation

1. Place a copy of your mod into the game directory (IMPORTANT: always keep a backup of your mod files as otherwise they may be lost when the game updates) and follow the steps for installing Pak files from step 4.

## Uninstalling Mods

Caution: Save files which played with mods installed may or may not work properly after uninstalling mods.

### From Backup Files

Use this method if you did not overwrite any original game files, or kept a backup of the game's original files, as recommended above.

1. Delete any mod files from the game folder.
2. Open the file `prog.xml` in your game folder in a plain text editor such as Notepad or Notepad++ (external link).
3. Look for a line in `prog.xml` that starts with `addon_packages="data` .
4. Remove the names of all mod `.pak` files from this line.
	* It should look like this if done correctly: `addon_packages="data-gfx2160"` or `addon_packages="data-macos"`, etc
5. Save the file.
6. If you modified `data-windows-gfx2160.pak`, copy your saved backup of this file and paste it into the game folder, accepting overwrite.
7. Start the game. The game should run in its original state.

### By Verifying Game Files

Use this method if you overwrote any game files and do not have a backup of the game's original files, or if the above method did not work.

1. Delete any mod files from the game folder.
2. Delete `prog.xml`, `data-windows.pak`, and `data-windows-gfx2160.pak`. If you used `developer.xml`, delete it as well.
3. Run the Verify/Repair game files tool.
	* Steam instructions
	* GOG instructions

If neither of the above options work, your last option is to uninstall and reinstall the game via your game launcher.

## Creating Mods

### Learning the code

1. FIRSTLY: Back up your save files. This is because there is a button and a keyboard shortcut on the develper interface that changes your save file into a testing version, thereby "corrupting" it permenantly. You can find your save files at `%appdata%\10tons\dysmantle\save\` .
2. Download the modding kit from https://dysmantle.com/secret/modding\_kit.zip. It contains the program to extract the `.pak` files into directories, called `nx-pak-tool.exe`. This is a command line tool, so use it on the command line, but it basically has two uses: unpack and pack. If you give it a `.pak` file as an argument, it will unpack, if you give it a directory, it will pack. Uncompress `modding_kit.zip` to a folder where you want to create your mods.
3. Open the `modding_kit` folder and edit `developer.xml`. Add `NO_POPUPS` to the `features` list.
4. Copy `data-windows.pak` from your game folder (see step 3. under Installing Pak Files above for where to find this) to your modding folder so you have a backup. You do not need `data-windows-gfx2160.pak`, these just contain higher quality textures and contain no files that you are likely to want to modify.
5. Use the `nx-pak-tool.exe` to unpack `data-windows.pak` (you can delete the unpak-ed copy of `data-windows.pak` that you created in step 4. now, this step is just for safety). Go through the newly created folder to familiarise yourself with how the game works. Some parts of the scripting cannot be seen here as it is in the compliled C++ part of the game.
6. In addition to this, you can copy across `developer.xml` into your game directory in order to enable "developer mode". This gives you access to tools such as stage editors, cheat menus and actor viewers (basically it allows you to preview object models and test animations). Disabling developer mode is as easy as just removing `developer.xml` from your game directory.

### Testing mods

1. Place your mods in a file directory with the same structure of the original files. So for example if you modified what the axe obtains when it is upgraded (the relevant file is found in `data-windows/items/tools/axe.nut`) then your mod directory structure should be something like `example_mod/items/tools/axe.nut` .
2. Pak your folder using the pak tool from the modding kit. You will have to use the command line to do this.
3. Place a copy of your mod into the game directory (IMPORTANT: always keep a backup of your mod files as otherwise they may be lost when the game updates) and follow the steps for installing Pak files from step 4.
4. Run your game.