Custom Data Files
Players and GMs can enter Custom, Override, or Amend data by creating additional data files. If you try to customize data by editing original data files, you are likely to lose your work each time you receive a Chummer update, and it will also be hard to sync these changes between multiple people. Custom, Override, and Amend files should be saved with UTF-8 encoding.
There are two options for where you can keep your custom data files:
- You can create a folder in Chummer's
customdatasubdirectory with a unique name, like Dave Home Campaign, to hold your Custom, Override, and Amend data files. Folders stored in thecustomdatasubdirectory are automatically detected and added to the list of custom data rulesets in Chummer when the program is started, though you will still need to enable them manually. However, be warned that putting your folder there can cause it to get deleted when upgrading or changing Chummer versions, so keep a backup handy. - You can create a folder anywhere on your computer to hold your Custom, Override, and Amend data files. If you place the folder inside your Chummer directory somewhere, the program will remember its location relative to the Chummer directory (which means it can keep track of it should you move your folder around), otherwise, the program will remember its absolute location. Should you choose this option, you will need to manually add your folder to Chummer's list of custom rulesets: go to Tools -> Global Settings, click the Custom Data Directories tab, and click the Add Directory button.
To use any folder containing custom data, you will need to create a custom Setting. Go into Tools -> Character Settings. Choose a Setting Name you wish to base your setting on and then click the Custom Data tab, and then check the checkboxes next to the custom rulesets you wish to use. You can also adjust the load order of your enabled custom rulesets in this tab, in case you have multiple custom rulesets that affect each other's content. Click the Save As... button and name your custom settings. If you already have a character, you can change what setting it uses by going to Special -> Change Settings File. You can also automatically enable singular custom data files by placing them directly into Chummer's data directory, though doing so means you cannot enable or disable the file from within Chummer's options menu, and you could accidentally lose the file when upgrading or changing Chummer versions.
Custom files are designed for when you wish to add new content without any special bells or whistles. Their file names must start with custom_ and end with _[datafile].xml, where [datafile] corresponds to the type of data being added by the given Custom file. For example, if you wanted to add a new piece of cyberware for a Flashlight retinal implant, you could create a new file called custom_cyberware.xml, custom_flashlighteyes_cyberware.xml, or custom_coolstuff_cyberware.xml (among others) and add a complete entry for Flashlight eyes inside. Custom Data can be spread across multiple Custom Data Files as long as they follow this file naming convention. GUIDs used for new items should be brand new and unique to each item; a web search will locate sites that create GUIDs online.
Chummer comes with many examples of Custom files that you can consult if you are lost. Each can be found in one of the folders that come with Chummer when you download it, located inside Chummer's customdata subdirectory.
Override files are designed for when you wish to completely replace a piece of existing content. Their file names must start with override_ and end with _[datafile].xml, where [datafile] corresponds to the type of data being overwritten by the given Override file. Chummer locates the content that you wish to override by matching your provided GUID with that of the original item. For example, if you wanted to replace the Jack of All Trades quality with a different effect, you could create a new file called override_qualities.xml, override_JoAT_qualities.xml, or override_coolstuff_qualities.xml (among others) and add an entry for the new effect you want the quality to have inside, making sure to match your entry's id tag with the id tag of the Jack of All Trades quality in the base Chummer data files. Override Data can be spread across multiple Override Data Files as long as they follow this file naming convention. Remember that the XML data in the override file completely replaces that of their matching items' in the base data file, so it is recommended you copy the XML from the base data file into your override file and then make the desired changes.
Chummer comes with a few examples of Override files that you can consult if you are lost. Each can be found in one of the folders that come with Chummer when you download it, located inside Chummer's customdata subdirectory.
Amend files are designed as significantly more versatile and/or powerful versions of Override files, though they can even replace Custom files if you want them to. They are capable of selectively modifying a given node's contents instead of replacing everything outright (the way that Override files would), adding new content in specific locations instead of only in the bottom-most location (the way that Custom files would), applying the same change simultaneously to multiple nodes using XPath filters, and more. Their file names must start with amend_ and end with _[datafile].xml, where [datafile] corresponds to the type of data being overwritten by the given Amend file. For example, if you wanted to decrease the Firewall rating of the Proteus Poseidon RCC, you could create a new file called amend_gear.xml, amend_proteusposeidon_gear.xml, or amend_coolstuff_gear.xml (among others) and add the appropriate amend entry inside. Custom Data can be spread across multiple Custom Data Files as long as they follow this file naming convention.
Though the way Amend files are structured can be complicated, minor changes with an Amend file can be done very easily. If you just want to replace a few parameters in existing data, you can just use the same format that you would for an Override file, but only specify the existing node's id (or name) and the data that you wish to replace; unlike Override files, Amend files do not replace all XML data, only the data that you have specified. If you wish to do anything more complicated though, a detailed explanation of the Amend system can be found below. Chummer comes with many examples of Amend files of varying complexity that you can consult if you are lost. Each can be found in one of the folders that come with Chummer when you download it, located inside Chummer's customdata subdirectory.
The Amend system works by repeatedly performing cycles of finding a target(s), then operating on it/them, then finding a target(s), then operating on it/them, and so on. This can be abbreviated as a "target -> operate" cycle, and with the help of a special operation (detailed later), Chummer will methodically "walk" through an Amend file and the specified base data file simultaneously, making changes to the latter as dictated by the "target -> operate" instructions in the former. There is only a single exception to Amend files being processed this way (detailed later). The reason you do not have to know about or deal with this system if you are making simple changes is that Chummer has a set of default "target" and "operate" settings that it chooses from depending on the context, and these are set up such that simple changes can rely on these default settings alone.
For the "target" step, the Amend system supports four methods of finding which node(s) to target. The first method looks for an id child node in the current Amend node and tries to find a node with a matching id child node in Chummer's data at the same level. The second method looks for a name child node in the current Amend node and tries to find a node with a matching name child node in Chummer's data at the same level, but only if the first method failed. These two methods are why using a format identical to an Override file works; however, keep in mind that only one of the two is necessary, which, among other things, lets you change the name of existing content using an Amend file. The third method looks for any child nodes in the current Amend node that have the attribute isidnode="True" and tries to find a node with a child node in Chummer's data at the current level whose name and content both match the Amend node's isidnode="True" child node. This is effectively identical to the first two methods, but instead of being forced to use a matching id or name child node, you can use a match based on any child node that you wish. The fourth and final method is the most powerful: you specify an xpathfilter attribute in your Amend node and directly match to targets that satisfy an XPath query in Chummer's data starting from the same level. If the xpathfilter attribute is present in the current Amend node, it overrides all other previously mentioned methods. If none of these targeting methods apply, Chummer defaults to targeting all nodes at the same level that have the same name as the Amend node.
For the "operate" step, if any targets were found, Chummer performs a specific operation on all nodes that were targeted. Chummer supports the following operations for Amend nodes:
- replace completely replaces all targeted nodes with data that is defined by the amending node. This is similar to how Override files work.
- remove removes all targeted nodes.
- addnode adds one instance of the amending node, complete with all children, to all previously targeted locations. It is the only exception to the "target -> operate" cycle, as no targeting step is performed. This is similar to how Custom files work.
- append adds text onto the end of the existing content if the target nodes contain pure text. If no target is found, it functions like addnode.
-
regexreplace functions like replace but uses the contents of a specified
regexpatternattribute as a Regular Expression pattern for determining how text contents should be replaced. If noregexpatternattribute is specified, it functions just like replace, otherwise, this operation ignores all non-text contents found in the targeted nodes. - recurse is special in that it does not manipulate data. Instead, it tells the system to recurse and repeat the "target -> operate" procedure on the children of all targeted nodes, which is what allows Amend files to make their changes anywhere you want them. If no target is found, Chummer will still step through the Amend node as usual, but it will ignore any operations found inside of it that have no effect without a target.
While only addnode and append do anything if there are no targets on which to operate, you can also use a special setting that will make Chummer treat replace and recurse as if they were addnode should no targets be found. Amend nodes with the attribute addifnotfound="True" will cause recurse or replace to behave as if they were addnode should no targets be found.
The operation that Chummer performs can be specified with an amendoperation attribute in the Amend node, e.g. amendoperation="remove" or amendoperation="addnode". If no amendoperation attribute is specified, Chummer uses the following defaults: recurse if the current Amend node has children, append if the current Amend node does not have children and no targets were detected (basically behaving like addnode), and replace with addifnotfound="True" if the amending node does not have children and at least one target was detected.
Chummer is very particular about how custom data files are to be formatted. Make sure your Custom file is 100% valid and properly formatted before attempting to use it with Chummer. Invalid/improperly formatted files that cannot be read will cause Chummer to ignore them completely, so if your data file seems to not be doing anything in Chummer, and you are sure you have the folder in which it is located enabled, try to remove formatting errors from your file and try again.
Data in Custom and Override Files follow the same data structure as in base data files. See the description of each data file type for more detail.
The easiest way to start a new Custom file is to copy an existing base data file. The <version> tag can be safely removed from your new file. When you are done editing it, your Custom file should only contain items (identified by GUID) that are not in the base Data File. If a duplicate item exists (same GUID), the information from the base Data File will be used.
Here is an example of how the contents of Custom file that adds a Flashlight eyeware could look like. You can find more examples of Custom files inside various folders in Chummer's customdata subdirectory.
<chummer>
<cyberwares>
<cyberware>
<id>GUID-GOES-HERE</id> <!--- IMPORTANT: You absolutely MUST include a new GUID with a new item, or copy the current item if making an existing item. www.guidgen.com makes GUIDs -->
<name>Flashlight</name>
<limit>False</limit>
<category>Eyeware</category>
<rating>0</rating>
<ess>0.1</ess>
<capacity>[1]</capacity>
<avail>2</avail>
<cost>1000</cost>
<source>SR5</source>
<page>0</page>
</cyberware>
</cyberwares>
</chummer>Here are a few examples of how the contents of an Amend file could look, each one followed by an expanded example showing Chummer's defaults for each node. You can find more examples of Amend files inside various folders in Chummer's customdata subdirectory.
The following example changes the nuyen cost of the Squatter lifestyle to 250.
<chummer>
<lifestyles>
<lifestyle>
<name>Squatter</name>
<cost>250</cost>
</lifestyle>
</lifestyles>
</chummer>
<chummer amendoperation="recurse">
<lifestyles amendoperation="recurse">
<lifestyle xpathfilter="name='Squatter'" amendoperation="recurse">
<cost amendoperation="replace">250</cost>
</lifestyle>
</lifestyles>
</chummer>The following example hides the Bad Rep quality from the list of qualities that characters can acquire.
<chummer>
<qualities>
<quality>
<name>Bad Rep</name>
<hide />
</quality>
</qualities>
</chummer>
<chummer amendoperation="recurse">
<qualities amendoperation="recurse">
<quality xpathfilter="name='Bad Rep'" amendoperation="recurse">
<hide amendoperation="addnode" />
</quality>
</qualities>
</chummer>The following example removes all extra requirements for learning the Mana Choke martial arts technique, which allows it to be learned by people without a Magic rating.
<chummer>
<techniques>
<technique>
<name>Mana Choke</name>
<required amendoperation="remove" />
</technique>
</techniques>
</chummer>
<chummer amendoperation="recurse">
<techniques amendoperation="recurse">
<technique xpathfilter="name='Mana Choke'" amendoperation="recurse">
<required amendoperation="remove" />
</technique>
</techniques>
</chummer>Since Nightly-v5.214.127 every custom data folder should have a Manifest.xml. This Manifest can hold information about the author(s), version, content, dependencies, and incompatibilities.
Every manifest needs to contain a unique GUID (www.guidgen.com). All other information is optional.
Versions are given as one to four different numbers separated by periods. Examples:
<version>1.2</version>
<version>5.201.2</version>
Authors can contain one or more authors, with each entry needing a name. One author should be defined as the main author, who will be specially marked as such in Chummer. Example:
<authors>
<author>
<name>Francis</name>
<main>True</main>
</author>
<author>
<name>Peterson</name>
<main>False</main>
</author>
</authors>Descriptions are language-specific and require a language code. Chummer will try to show the one that matches its current UI language and will otherwise default to US English if it is available.
<descriptions>
<description>
<text>This custom data folder will change all assault rifles to deal 5 more damage because they really needed a buff!</text>
<lang>en-us</lang>
</description>
<description>
<text>Dieser Ordner erhöht die Schaden von Sturmgewehren um 5. Geil, ne?</text>
<lang>de-de</lang>
</description>
</descriptions>Dependencies are other custom data folders that need to be loaded for a given folder to work correctly. Chummer will not force a user to enable any datasets on which the given dataset is dependent, but it will warn users if any dependencies are not met.
A custom data folder can have any number of dependencies. A dependency is defined by a guid and version range (minversion,maxversion). This version range is inclusive, meaning that the given numbers will also be accepted.
If no minversion or maxversion is given, the range is assumed to be open-ended. If no version information is given at all, only the guid is used to identify the requested custom dataset.
The name node is not used for identification, but is strictly required. Because tooltips will be useless to the user without a name to display.
The following example requires another custom data with the guid a8d6147d-68e9-4286-80fd-8f9ee4eb6cbd and the version has to be at least 2.
<dependencies>
<dependency>
<name>Needed example file</name>
<guid>a8d6147d-68e9-4286-80fd-8f9ee4eb6cbd</guid>
<minversion>2</minversion>
</dependency>
</dependencies>Incompatibilities are analogous to dependencies and work with the same syntax. Rather than requiring certain datasets to be enabled for the given dataset to work though, incompatibilities signal that the given custom dataset will not work (properly) if any of the specified custom datasets are enabled.