User:TechAngel85/Sandbox2

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 descriptions 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 writing 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.

Before getting started, a little explanation of why this guide exists. When writing FOMODs there aren't many references to go use in order to learn how FOMODs are written besides looking at other author's work. The only real guide has been the Guide to FOMOD scripting by nyrb. This PDF guide covers the basics and gets the information presented but isn't presented as ideally as it could be. It also only gives users a basic layout of the moduleConfig.xml file without going to the detail that is needed to make more complex FOMODs in order to fully utilize their potential. This guide aims to provide users the knowledge required to learn to create everything from simple FOMODs to more in-depth and complex FOMOD installers.

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:

• NotePad++
• Mod Organizer
• Nexus Mod Manager

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 writing 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 heuristics 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 halt 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 halt 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 approximately 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 writing any scripts because if it is changed after the scripts are written, it could create a lot of necessary editing 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.

1. 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.
2. Open the new fomod folder.
3. Right-click in the window pane, hover over "New", and select [Text Document].
4. Delete the entire name, including the extension, and name it "info.xml". If a message box appears, click [Yes] to change the file extension.
5. 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:

1. 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.
2. 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 collaborating 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 separate 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 collaborating.
• For complex FOMODs, leave markers in the code using comments to help sectionalize 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;

<!-- Text goes here -->

Some authors like to create a theme for their comments and markers so that they stand out among 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:
	November 23rd, 2015 - TechAngle85
		Fomod written and released as v1.0 for the STEP v2.2.9.2 release.
=================================================================================
-->

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 conditional 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 un-commenting the working code.

Info.xml File

As explained above, the "info.xml" file contains valuable information to the user before installation such as the mod name, author, version, and more. Navigate to this file which was created earlier in the guide and open it up in NotePad++. The first thing to do is change the programming language for the file for proper syntax highlighting and ensure the encoding is set properly.

1. With the file open in NotePad++, click on [Language] in the Menu Bar.
2. Select [XML] from the drop-down menu. This will allow proper syntax highlighting.
3. Now select [Encoding] in the Menu Bar.
4. Ensure [Encode in UTF-8] is selected.

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 categories can be defined which the mod fits into. The Nexus categories 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 meaningful 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 readability, 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.

The Header

The header section is the beginning section of the ModuleConfig file which consists of three elements (tags): config, moduleName, and requiredInstallFiles. Of these elements, only the requiredInstallFiles tag is optional.

config Element

Just like the info.xml file, the ModuleConfig.xml file must start with a specific line of code. This time, it's the config tag. This tag holds a very specific set of attributes within in which tell the XML parser how to read and handle the file. Unlike the info.xml file, this starting tag must also be closed and all other elements within the the file will be nested between the config tags. To get started, navigate to the ModuleConfig.xml file which was created earlier in the guide and open it up in NotePad++. The first thing to do is change the programming language for the file for proper syntax highlighting and ensure the encoding is set properly as was done with the info.xml file.

1. With the file open in NotePad++, click on [Language] in the Menu Bar.
2. Select [XML] from the drop-down menu. This will allow proper syntax highlighting.
3. Now select [Encoding] in the Menu Bar.
4. Ensure [Encode in UTF-8] is selected.

Now it's time to include the config tags. Knowing what this tag's attributes do is not important. Knowing that the tag must be included exactly as below, is! It's recommended to copy and paste this into the editor to ensure no mistakes are made:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://qconsulting.ca/fo3/ModConfig5.0.xsd">

</config>

moduleName Element

The moduleName tag holds the name of the module. This can be anything, but it's recommended to use the name of the mod which the FOMOD is being created for. This tag is nested below the config' tag. This tag is defined as such:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://qconsulting.ca/fo3/ModConfig5.0.xsd">
   <moduleName>The STEP Installer</moduleName>
</config>

The name of the module is placed between the opening and closing tags. For this guide, the moduleName is defined as The STEP Installer.

requiredInstallFiles Element

The requiredInstallFiles element's section is completely optional, meaning it does not need to be included within the ModuleConfig file. The reason any mod author would want to include this element's section is if the mod the installer is being written for requires file to be install regardless of the user options chosen. This are normally files such as a ReadMe or files that the mod requires to function properly. For this guide, we're using the STEP Compilation as a reference; therefore, the included requiredInstallFiles section here includes files which are required for DynDOLOD to funtion properly with a STEP Guide installation.

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.

Troubleshooting

Tags are case sensitive! It's important to know that XML tags are case sensitive.

NOTES

Nothing as of yet...