What is a FOMOD?
FOMODs are scripted installers written in C# or XML for game mods. When written correctly, they can make potentially complex mods easy to install for most users. For mod authors, they also provide a way to ensure mod requirements are met before the mod, itself, or certain mod options are installed by users. These installers are parsed and displayed as a graphical user interface (GUI) capable of displaying pages with selectable options, images, and discriptions for each option. These pages are used to guide users in the proper installation of mods and their options. Though these installers can be written in C#, this guide will only focus on writting FOMODs using XML.
If followed, this guide will give users a fully functional FOMOD. The FOMOD created and referenced here is the actual FOMOD used for the STEP Compilation, which is installed by users towards the end of the STEP Guide.
Tools
The only tools which are required to write FOMODs is a text editor, Nexus Mod Manager, and Mod Organizer. Having an editor with syntax highlighting will make coding far easier. NotePad++ is highly recommended for this task and is what will be used in this guide. Nexus Mod Manager and Mod Organizer are used for testing the FOMODs. You may download these tools for free at the links below:
Mod Organizer vs Nexus Mod Manager
There are a two key differences between Mod Organizer (MO) and Nexus Mod Manager (NMM) that authors should keep in mind when writting and testing FOMOD installers. These are how errors are handled and how the info.xml file is handled.
The info.xml file is a script file which contains information about the mod being installed such as its name, version, categories, web link, and description. For installation in Mod Organizer, this file is used but MO isn't reliant upon it since MO can gleam most of this information from Nexus. However, Nexus Mod Manager uses this file to its fullest extent by displaying the information it contains on a "splash" screen before the mod installation is ran. Therefore, it is a good idea to always include this file and always provide meaningful information within it. Setting up the info.xml file is explained later in this Guide.
How errors are handled is the biggest and often the most frustrating difference between the two managers. Mod Organizer uses a huestics system which will attempt to correct or simply ignore issues it finds in the code. Sometimes this works and MO continues to work as expected. Other times when MO can't fix code, it will sometimes simply ignore the error and still allow the user to install the mod as expected. Finally, there are circumstances which Mod Organizer will hault the installation of the mod if it simply detects too big of an error. At all times during testing a FOMOD installer in Mod Organizer, the message pane at the bottom of the MO window will have valuable information which can be used to help narrow down the issue. How Nexus Mod Manager handles errors is completely different, however. At any time NMM runs into an error in the code, it will completely hault the installation and display an error message in its information box (bottom right pane). Right-clicking these messages will allow them to be copied and pasted into a text file so the entire error message can be read. These messages are only helpful approxiatemately 50 percent of the time. The majority of the error messages from Nexus Mod Manager will only allow authors to get an approximation of what is causing the error. This is the frustrating part with NMM, attempting to track down issues from obscure errors messages.
Once a FOMOD installer is written, it is recommended to first thoroughly test them using Mod Organizer. MO will better aid authors in correcting any issues within the code. However, it's also essential once the MO testing is completed that another thorough round of testing is completed using Nexus Mod Manager, since NMM will be far pickier than MO with parsing the XML script.
Building the Structure
There are a few basic which must be in place before scripting begins:
- Folder Structure
- Creating XML Files
The folder structure is something which should be considered before writting any scripts because if it is changed after the scripts are written, it could create a lot of necessary editting of the scripts to update the paths. This is not desirable since it only increases the potential for error. When considering the folder structure, also consider the mod managers used by the users. These mainly consist of Mod Organizer (MO), Nexus Mod Manager (NMM), and Wrye Bash (WB). MO and NMM do not care about the specific folder structure of the mod; however, Wrye Bash uses a format called Bash Installer (BAIN). BAIN uses a specific folder structure and it's for this reason it is recommended to use a BAIN-compatible folder structure for all mods which will be set up for installation by way of a FOMOD script. BAIN will be the file structure used in this guide. More information can be found on the BAIN structure on the Wrye Bash General Readme.
The first folder that is always required is the fomod folder. This folder is not case sensitive so you will see if displayed in multiple ways, but the case doesn't matter. Two files must be created within the fomod folder; info.xml and ModuleConfig.xml.
- From within the mod's folder, click the [New Folder] button on the ribbon bar. Alternatively, right-click in the window pane, hover over "New", and select [Folder]. Name this new folder fomod.
- Open the new fomod folder.
- Right-click in the window pane, hover over "New", and select [Text Document].
- Delete the entire name, including the extension, and name it "info.xml". If a message box appears, click [Yes] to change the file extension.
- Repeat steps 3 and 4, but this time name the file "ModuleConfig.xml".
Now that the required folder and files are created, it's time to create the remainder of the folder structure. For this guide, our mod will have required files which must be installed regardless of options chosen by the user, two optional components split into three folders, and six folders for each of the main plugins options. Folders need to be created for all of these options following the BAIN format. To do this:
- From within the mod's folder, click the [New Folder] button on the ribbon bar. Alternatively, right-click in the window pane, hover over "New", and select [Folder]. Name this new folder 00 Required.
- Repeat the step above for each option, naming the folders according. See image below for details and what the final product should look like.
Users should now have a folder structure like the one in the image above. If not, correct any mistakes before continuing. The setup stage is now completed. Users can populate the created folders with the correct files for their mods. In this case, the "Required" folder contains the ReadMe and required DynDOLOD files, the "Comp" folders contain the STEP Compilation files, and the "Patch" folders contain the individual patches. The remainder of this guide will focus on the XML scripting for the two XML files.
XML Scripting - The Basics
Scripting in XML is very similar to HTML/XHTML and even those who are familiar with BBCode can easily learn the basics of XML scripting. XML consists of elements, commonly called "tags", which must be opened and closed. Within select opening tags, there are various attributes that can be defined within them. The basic XML code looks like the following:
<installStep name="Select Option(s)">
<optionalFileGroups>
<group name="Install Options" type="SelectExactlyOne">...</group>
</optionalFileGroups>
</installStep>
XML structure consists of a "root element", elements, and child elements which can have attributes with defined values within them. In the example above, <installStep name="Select Option(s)"> is the root element with a "name" attribute whose value is defined as "Select Option(s)", <optionalFileGroups> is a custom element, and <group name="Install Options" type="SelectExactlyOne"> is a child element with two attributes within it.
When scripting XML, every tag is a set of two tags; an opening tag and a close tag. Opening tags are defined by enclosing the tags name within brackets; <textHere>. Closing tags are defined by the addition of the [/], in front of the tag's name; </textHere>. This can be seen in the example above. All opened elements were also closed in the order of which they were opened. This order of opening and closing is important in XML and is called, "nesting". All XML tags must be closed in the order they were opened. Some tags can be even be opened and closed within the the same element. To do this, add a [/] before the closing bracket. In FOMODs, this is seen used with the "image" element; <image path="Fomod\STEP.png" />.
Before moving on, another thing to note is the indention of each child element from its parent. In the example above, <installStep name="Select Option(s)"> is the parent element of <optionalFileGroups>. This makes <optionalFileGroups> the child of <installStep name="Select Option(s)">. Still following? It's basic family relationships! Each child element is indented from the parent. This is not necessary but is basic practice to help visualize the code. It's also great in helping to keep track of sections of code when the coding starts getting more complex. If using NotePad++, users can indent their code by using the [Tab] key.
Commenting the code
First, lets discuss comments and their importance while constructing a FOMOD. Comments are used for descriptions, instructions, and even as markers within XML documents. These comments are extremely helpful for authors; especially when colaberating with multiple authors. Descriptions can be left explaining what a section of code is for, instructions can be put within the code for others to follow who may come behind the author to edit the code, and markers can be placed to help seperate the code into sections because complex FOMODs can become quite large; often expanding hundreds and sometimes thousands of lines. Not only will leaving comments help others to follow and understand the code, but they will also serve as reminders for authors who must return to edit the code after enough time has past that they may have lost some familiarity with their own work. Yes, this can and does happen!
Outlined below are a few best practices for when and where to leave comments within the files:
- Leave descriptive comments where options or complex code, like conditions, need to be explained. Conditions are explained in the advanced section of this guide.
- Descriptive comments can also be used for information within the files, such as a changelog for when multiple authors are colaberating.
- For complex FOMODs, leave markers in the code using comments to help sectionialize the code; making it easier to read.
How to write a comment
To place a comment within XML, place the desired text between the comment tags;
Some authors like to create a theme for their comments and markers so that they stand out amoungst the code. An example is provided below which shows the use of the "=" symbol as a top and bottom border for the comment. All text is within the boundaries of the borders. This also shows the use of a comment section used for a changelog:
<!-- ============================================================================== STEP Installer FOMOD Version: 1.0 Created and Maintained by: The STEP Team Changelog: September 1st, 2015 - TechAngle85 Fomod written and released as v1.0 ============================================================================== -->
Pro Tip: Use comments to hide code when making or testing changes. For example, if you have a simple option that installs only one file when selected which is being converted into a complex option with coditional statements, then it's best to hide the known good code within comment tags until testing is complete. If anything anything happens that requires the code to be reverted, it's as simple as uncommenting the working code.
Info.xml File
As explained above, the "info.xml" file contains valueable information to the user before installation such as the mod name, author, version, and more. Navigate to this file which was created eariler in the guide and open it up in NotePad++. The first thing to do is change the programing language on the file for proper syntax highlighting.
- With the file open in NotePad++, click on [Language] in the Menu Bar.
- Select [XML] from the drop-down menu.
Now that the language is set, the document itself needs to be declared as a XML document. This allows the parser in the mod managers to parse the document properly. Do this be adding the following to the first line:
<?xml version="1.0" encoding="UTF-16"?>
This first element of this file will always be your fomod element. This defines the entire document as a FOMOD. It is always easier to open and close the tags at the same time to ensure the closing tag is not forgotten. If it is forgotten, the script will fail and the mod manager may not be able to install the mod using the FOMOD installer. Start by opening and closing the fomod element. The children elements will be added next.
<?xml version="1.0" encoding="UTF-16"?> <fomod> </fomod>
Now is time to finish the document by adding in the child elements which actually hold the information the mod managers will use to display to the users. The information is placed between the opening and closing tags. The elements are defined as such:
- Name
- This is the name of the mod and will be the name used during installation. Once the mod is installed, this is the name the user will see in their mod list.
- Author
- This is the name of the author for the mod. It can be one or multiple authors. There is no formatting here so the text will usually display is inputted.
- Version
- This is used to display the version of the mod and is used by mod managers so input to correct version here and be sure to update this element when the mod is updated.
- Website
- This element holds the website link to the mod. Nexus links to the page mod are most often used and mod managers will display this as a clickable link to the mod page.
- Groups
- The Groups element is a parent element to element tags. Within these child element tags, is where the catorgories can be defined which the mod fits into. The Nexus catorgies are most often used here.
- Description
- Just as is sounds, this element holds the description for the mod. This can be anything the mod author wishes, but it is best to add a meaniful description of the mod. Sometime authors like to also include a short changelog here to tell users what changed in the newest version.
Start with the name element and include each element listed above with a opening and closing tag. Remember that capitalization matters! Provided below is the example from the STEP Compilation. If following this guide for learning purposes, users should match exactly this example provided:
<?xml version="1.0" encoding="UTF-16"?>
<fomod>
<Name>STEP Mod Compilation and v2.2.9.2 Patches</Name>
<Author>The STEP Team</Author>
<Version MachineVersion="1.0">1.1</Version>
<Website>http://www.nexusmods.com/skyrim/mods/11/?</Website>
<Groups>
<element>replacers/textures</element>
<element>replacers/meshes</element>
</Groups>
<Description>
A compilation of mods and the STEP Patches.
Latest Changes
v1.11
- Fixed some issues with the Patches.
v1.0
- STEP installer released
Thanks for downloading!
</Description>
</fomod>
The information has been placed between the opening and closing tags, the tags have been indented for readibility, and the tags have carried the capitalization properly. This is a rather simple file which holds information for the mod managers and users. This concludes the info.xml file. Be sure to save the file before exiting!
ModuleConfig.xml File
The ModuleConfig.xml file is where all the magic happens, meaning it holds the code which the mod managers will use to configure and display the FOMOD installer to the user. This guide is using the STEP Compilation for reference and that ModuleConfig file is rather complex. Not all mod authors will needs such a complex configuration. Therefore, this section of the guide will start by completing a more basic version of ModuleConfig for users and add in the complexity of conditions and dependencies later in the Advanced Scripting section.
Advanced Scripting
Conditions
Conditions are instructions for the FOMOD installer to follow based upon a set state of a specific flag or flags. These conditions can be used for whether or not to display a specific page of the installer to users or whether or not to install specific files or mod options, all based upon the user's selection choices within the FOMOD installer itself.
Dependancies
Troubleshooting
Tags are case sensitive! It's important to know that XML tags are case sensitive.
NOTES
XML files should be saved with UTF-8 encoding.
