-
Notifications
You must be signed in to change notification settings - Fork 1
Mod Format XML
The following information is for mod developers who want to package their mod to be compatible with the Jackal Mod Manager. Mod customizations (modes/options) can be enabled and disabled by the user when they activate your mod and provide a good way for you to avoid having to package and distribute multiple versions of your mod.
To avoid confusion with the mod customization system it is advised you read this section first. The following terms are used:
Common refers to plugins and resources that are always used by the mod, it is possible to override common files with ones from a mode or option if you so choose.
Modes are mod customizations that require only one to be selected at a time. Modes are not required for a mod however exactly one mode will always be selected if any exist, if you want an option for none of your modes you can always create one that contains no plugins or resources and therefore does nothing. Mode files can override common files.
Examples: Difficulty (Easy/Medium/Hard), Zombie Density (Low/Regular/High)
Options are mod customizations that can be enabled and disabled independently of each other and any modes. Options are not required for a mod and there are no limits on how many can be enabled or disabled. Note that options can be used to override mode files if you choose along with overriding common files.
Examples: Graphical Tweaks (Bloom/Shadows/HDR), Cheats (Invulnerability/Flying/Noclip)
Mods should be structured as followed inside a ZIP archive:
ZIP file
|
---- data/
| |
| ---- (Plugin .dll files)
| |
| ---- (Resource directories)
| |
| ---- jackalContentGenConfig.xml
|
---- jackal.xml
|
---- icon.png
Additional files such as a readme file, install scripts for non-mod manager users, or anything else can be added and should not cause issues with the operation of the mod manager.
The icon is an optional image to be displayed in the mod manager. It should be 80x80 pixels in size and in the PNG (Portable Network Graphics) format with alpha transparency supported, smaller sized images may be used but keep in mind they will not be scaled and so will have extra blank space around them.
The jackal.xml file defines all data associated with the mod to the mod manager. An example file is shown below with each value explained:
<?xml version="1.0" encoding="UTF-8"?>
<mod>
<name>ModFormatExample</name>
<pretty>Mod Manager Format Example</pretty>
<author>Your Name</author>
<version>1.0</version>
<gameVersion>23</gameVersion>
<description><p>An example of the format used by the mod manager.</p></description>
<refreshScriptCache>false</refreshScriptCache>
<refreshWorld>false</refreshWorld>
<refreshInventory>false</refreshInventory>
<defaultMode>0</defaultMode>
<common>
<plugin>common_plugin</plugin>
<resource>common/directory</resource>
</common>
<mode>
<pretty>Mode 0</pretty>
<plugin>mode_plugin</plugin>
<resource>mode/directory</resource>
</mode>
<option>
<pretty>Option 0</pretty>
<default>false</default>
<plugin>option_plugin</plugin>
<resource>option/directory</resource>
</option>
</mod><name> - is the name for the mod used as the name of the directory it is installed to inside the mods directory and what it is internally referred to by the mod manager. This mod name should not contain spaces or characters that are not legal in directory names and should be unique to avoid conflicts since installing a mod that uses the same name will overwrite yours.
<pretty> - is the name for the mod displayed to the user except when contained inside or tags in which case it is the name for that mode or option displayed to the user. It may contain spaces.
<author> - is the name of the author(s) of the mod.
<version> - is a string for the mod version. Since it is a string the version may be defined in any format desired.
<gameVersion> - is the version number of The Dead Linger for which the mod was made and is known to be compatible. This is primarily included to let users know the age of the mod as game updates may cause mods to no longer function properly. The current TDL version can be found in the tdlversion.txt file in TDL's AppData directory and is also displayed by the mod manager, the number that appears when TDL starts is NOT the correct version number but rather is the next version that the updater is searching for. Note that is value is not the current build of TDL but rather is the value used by the TDL updater.
<description - is an optional block of formatted text displayed to the user. The text is displayed as Qt Rich Text which allows the use of HTML style tags for formatting and allows extras such as click-able URLs to be used, however it is important that you escape the < and > characters using < and > respectively as done in the example so that they are not interpreted as XML.
<refreshScriptCache> - should be set to 'true' if the mod requires the TDL script cache to be deleted and recreated.
<refreshWorld> - should be set to 'true' if the mod requires a new world to be created. Note that the user will have the option to decline deleting their existing world.
<refreshInventory> - should be set to true if the mod requires a fresh inventory. Note that the user will have the option to decline deleting their existing inventory.
<defaultMode> - determines which mode should be enabled by default. This value should be an integer with '0' representing the first mode in the order they are listed in the config.xml file, '1' representing the second mode, and so on. If this value is omitted the first mode listed will be used (or none if the mod has no modes). Note that you can create a mode containing no plugins or resources if you want if you want users to have a "None" option.
<common> - is an optional tag there for readability, any plugins or resources listed outside of or tags will be considered a common resource.
<mode> - defines a section containing the information for one of the mod's modes.
<option> - defines a section containing the information for one of mod's options.
<plugin> - is the name of a plugin .dll file used by the mod, the .dll extension should not be included or it will fail to load correctly. Using the names of any of the vanilla .dll files is not allowed.
<resource> - is a directory for resource files inside the mod's data directory. Any directory containing non-plugin mod files must have an entry in the jackal.xml file or they will not be loaded by the game. Resources for a mode or option must be in their own separate sub-directory to avoid them being loaded all at the same time. Note that since mode and option resources are loaded later than common ones they can override common files allowing them to modify your vanilla mod, similarly option files will override mode files.
This file would only be used by server side mods that replace the ContentGenConfig.xml file. The file is special because the --contentconfig command line option can be used to tell the server to use a non-default file which is then downloaded to connecting clients. This allows for certain mods to only require server side deployment such that vanilla clients can play on the modded server, if the file was directly replaced instead modded clients would be required to connect otherwise a crash or unexpected behavior will occur.
If you wish to use this feature rename your modified ContentGenConfig.xml file to jackalContentGenConfig.xml and then make it clear to your users that they must check the "Custom content generation config" option under Server->Configure when launching a dedicated server through the mod manager or add the --contentconfig=jackalContentGenConfig.xml command line option when launching a server through other means.
Note that in some cases it may be preferable to have clients without the mod installed crash rather than download the modded file as it will require them to install the mod in order to play on that server.