User:TechAngel85/Sandbox2

Preface

If followed, this Guide will give users a fully functional FOMOD. Before getting started, a little explanation of why this guide exists.

There aren't many references for users to learn how FOMODs are scripted, besides looking at another author's work. The only real reference has been the Guide to FOMOD scripting by nyrb. This PDF guide covers the basics and gets the information presented, but it isn't presented as ideally as it could be. For example, it only gives users a basic layout of the moduleConfig.xml file, without delving into enough detail for users to learn how to make more complex FOMODs to fully utilize thier potential. This Guide aims to provide users the knowledge required to learn to produce everything from simple FOMOD installers to more in-depth and complex ones. The information will be presented in an order to promote learning, while being more detailed to explain the code and how to employ it.

What is a FOMOD?

FOMODs are scripted installers for game mods. Though they can be deployed for any mod, when scripted correctly, they make particularly complex mod installations an easy experience. They also provide an effective way for authors to ensure mod requirements are satisfied before the mod/options is installed by users. FOMOD scripts are parsed and displayed as a graphical user interface (GUI) of pages with selectable options. These pages are utilized to guide users through a mod's installation and its possible options. Though these installers can be scripted in C#, this guide will only focus on FOMODs using XML. It's recommended to become familiar with the terms associated with XML since this Guide uses them extensively.

Tools

The only tool required to script a FOMOD is a text editor. 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's examples. Users will see a customized XML style in the default Dark Mode style. Notepad++ is highly customizable to suit any user. These colors were used as they suit the wiki styles for this Guide better.

Mod Mangers parse the scripts into a GUI for the user to install a mod; therefore, one is required for testing. Each Manager's GUI may be slightly different, but the outcome of should be the same. Once a FOMOD script is complete, it's recommended to thoroughly test them using a mod manager. Mod Organizer is used for testing in this Guide.

There is a FOMOD Validator by Ganda that is very help in tracking down errors. Simply run it, point it to the mod's root folder, and Validate. A list of issues and their line numbers will be printed out, when present.

Users may download these tools for free at the links below:

• NotePad++
• Mod Organizer
• FOMOD Validator

Differences Between Mod Managers

The main difference between mod manages are the GUI, how coding errors are handled, and how the info.xml file is handled.

The GUI isn't anything to worry about as it can't be controlled. However, how errors are handled is the biggest difference between managers. Mod Organizer uses a heuristics system that attempts to correct any issues it finds in the code. Often MO continues to works as expected even when it can't fix the code; simply ignores the error and continues to install the mod as expected. There are circumstances where Mod Organizer will halt an installation, if the error is too big. During a FOMOD installation in Mod Organizer, the message pane at the bottom of the window will have valuable information, which can be used to help narrow down the issue.
Other Managers handle errors completely different. For example, when an error in the code is found some managers may completely halt the installation and display an error message in its information box. The hope is the manager's message is coded well enough to be helpful in resolving the error.

The info.xml script contains information about the mod being installed such as its name, version, categories, web link, and description. For Mod Organizer this script is used, but MO isn't reliant upon it since MO can gleam most of this information from Nexus via API. However, other managers may use this script to its fullest extent by displaying the information it contains to the user. It's recommended to always include this script and always provide meaningful information within it. Setting up the info.xml script is explained later in this Guide.

Building the Structure

There are a few basics that must be in place before scripting begins:

• Creating XML Files
• Folder Structure

The folder structure is something that should be considered before writing any scripts. If it's changed after the scripts are written, it causes lot of necessary editing of the scripts to update folder names. Though FOMODs do not require any specific folder structure, it's recommended to use something sensible to both mod managers and users. A format from Wrye Bash called, Bash Installer (BAIN), is perfect for this. It's both organized and easy for users to understand. As such, it's the folder structure recommend by this Guide. More information can be found on the BAIN structure on the Wrye Bash General Readme.

XML Files

The first folder that is always required is the fomod folder. This folder is not case sensitive, though authors format in multiple ways. Two files must be created within the fomod folder; info.xml and ModuleConfig.xml.

1. From within the mod's root 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

   

   NOTE:

   For steps 3 through 5 to work properly, users must have extensions enabled for files. If it's not done, please do so by following this guide.

Folder Structure

Now that the files are created, it's time to create the remainder of the folder structure. For this Guide, our mod will have:

• required files that must be installed, regardless of options chosen by the user
• two required choices for two plugin versions
• two optional choices that provide three install options

Folders need to be created for all of the above following the BAIN format. To do this:

1. For each new folder, click the [New Folder] button on the ribbon bar. Alternatively, right-click in the window pane, hover over "New", and select [Folder].
2. Name the first new folder: 000 Required - Core Files
3. Repeat, naming the folders as follows:
   • 100 Required - PluginVersion01
   • 100 Required - PluginVersion02
   • 200 Optional - Addon01
   • 200 Optional - Addon01 - Addon02 Compatible
   • 210 Optional - Addon02

BAIN Numbering

Users familiar with the BAIN schema may skip ahead as this is a basic introduction.
Lets review the BAIN folder structure above, which is all in the numbering. With BAIN, the numbers correspond to specific option "groups". It's recommended to always use a 3-digit schema, as it allows for greater flexibility and expansion as mods develop. The schema remains the same, so once it's understood and if set up correctly, any user should be abled to install the mod manually by following BAIN.

The first number is always 000, which is used to signify files that are always installed with the mod. Anytime a folder starts with 000, a user should automatically know to install it first. The next "group" would be numbered 100. Note that both folders in the example start with 100! In the BAIN schema, when multiple options exist for something like a plugin but the user should only install one of them, they are given the same number. In this example, since only one of the plugins should be installed, not both, they both start with 100.

The next "group" starts with 200. Note that there is the same setup as explained above for Addon01; however, Addon02 has the second digit increased. In the BAIN schema, advancing the second digit keeps those folders within the larger 200 "group", while signifying it being a separate folder that can be installed within the larger group. In the example, users would only install one of the 200 folders, but can also install the 210 folder as well.

That is BAIN just a quick review of the basics with BAIN. Adding more folders is as simple as continuing the BAIN schema.

BAIN Folders

The next thing to know about BAIN is that each folder only contains game files. These means the only files and folders within the root BAIN folders are game-specific files. Do not put any sub-folder structures within these root folders! To be clear...

Don't do this!	Do this!
Mod Folder 100 FolderName 110 Option01 111 Option01 Color01 111 Option01 Color02 120 Option02 This is not BAIN!	Mod Folder 100 FolderName 110 Option01 111 Option01 Color01 111 Option01 Color02 120 Option02 Everything is a root folder in BAIN.

The rest is simply using a naming schema that is organized and easy for users to understand. The example shows the use of a user-readable schema that notifies the user if the folder is required or optional. This is followed by a recognizable name that usually corresponds to the name of what the folder contains (e.g., 200 Optional - NoRunning).

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. The remainder of this Guide will focus on the XML scripting for the two XML files.

XML Scripting - The Basics

Users familiar with XML scripting may skip ahead as this is a basic introduction.
Scripting in XML is very similar to HTML. 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, just like HTML. The basic XML code looks like the following:

<installStep name="Select Option(s)">
     <optionalFileGroups>
          <group name="Install Options" type="SelectExactlyOne">...</group>
     </optionalFileGroups>
</installStep>

NOTE:

XML tags are case sensitive! <optionalfilegroups> is not the same as <optionalFileGroups> in XML scripting!

XML structure consists of a "root element", elements, and child elements; each may or may not have attributes with defined values within them. In the example above,

• <installStep name="Select Option(s)"> is the root element with a "name" attribute defined as "Select Option(s)"
• <optionalFileGroups> is an element
• <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 a forward slash ( / ), 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 forward slash before the closing bracket. In FOMODs, this is seen used with the "image" element; <image path="Fomod\fomodImage.png" />.

Before moving on, another thing to note is the indention of each child element from its parent. In the example above, each child is indented from the parent. This is not necessary but is basic practice to help humans visualize the code. It also helps to keep track of sections of code when the scripting starts getting more complex. If using NotePad++, users can indent their code by using the [Tab] key.

XML Comments

Comments in any scripting are used many things such as descriptions explaining what a section of code does, instructions for others to follow who may come behind the author to edit, and markers to help separate the code into sections for complex or large FOMODs. They will also serve as reminders for authors who may return for edits after a long period of time has past and some familiarity with their own work is rusty (this happens often).

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 that 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 happens that requires the code to be reverted, it's as simple as un-commenting the working code.

Outlined below are a few best practices for when and where to leave comments within FOMOD scripts:

• 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 and find different sections.

Comments in XML are the same as they are in HTML:

<!-- 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 SkyrimSE Guide FOMOD
Version: 1.0
Created and Maintained by: The STEP Team

Changelog:
	November 23rd, 2015 - TechAngle85
		Fomod written and released as v1.0 for Step v2.2.9 release.
=================================================================================
-->

XML CDATA

In XML scripting, text will be parsed ignoring any line breaks by default. Therefore, text blocks (separate paragraphs) are ignored and displayed as one continuous block. To prevent this from happening, CDATA (character data) tags are placed to encapsulate text blocks. Doing so tells the parser to honor all characters within these tags, thus honoring line breaks. These are most often used for descriptions within FOMOD scripts.

No CDATA	CDATA
<Description> My first line with some some information. My second line with something clever: - My list item - My list item </Description>	<Description> <![CDATA[My first line with some some information. My second line with something clever: - My list item - My list item]]> </Description>
Parsed and displayed as:
My first line with some some information.My second line with something clever:- My list item- My list item	My first line with some some information. My second line with something clever: - My list item - My list item

NOTE

Most mod managers will honor the formatting without CDATA being present due to their own, internal programming. Regardless of this fact, it is a coding best practice to use CDATA for all text blocks using writing XML.

Info.xml File

As explained above within Differences Between Mod Managers, the "info.xml" file contains valuable information that is typically displayed to the user such as the mod name, author, version, and more. Navigate to this file, which was created earlier in the Guide, and open it with a text editor. The first thing to do is change the programming language and encoding for the file for proper syntax highlighting, if not already set.

Set the Language to XML and the Encoding to UTF-16. FOMOD scripts should always be written and saved with UTF-16 encoding or issues may arise. This is due to the XML declaration specifying UTF-16.

Now the document itself needs to be declared as a XML document and the root only element is placed. The root element for the info.xml script is: <fomod>
It is always easier to open and close tags at the same time to ensure the closing tag is not forgotten; causing the script to fail. The script for the declaration and root element look as such:

<?xml version="1.0" encoding="UTF-16"?>
<fomod>

</fomod>

Finish the script by adding the fomod element's children. These children elements hold information mod managers use to display to users. The information is placed between the opening and closing tags of each child element. There is no formatting available, therefore, the text will usually display is inputted. The elements are defined as such:

• Name : this is the name of the mod and will be the initial name used by the mod manager for installation
• Author : this is the name of the author(s) for the mod
• ID : this is the ID of the mod, which may only be used by Vortex (unknown)
• Version : this is used to display the version of the mod. Be sure the MachineVersion attribute matches that of text for the version

  This element requires updating every time the mod increments version numbers!

• Website : this element holds the website link to the mod. Mod managers will typically display this as a clickable link.
• Groups : the Groups element is a parent element to the element element.
  • element : within these children elements is where the categories are defined that the mod fits into. Nexus Mods categories are most commonly used.
• Description : this element holds the description of the mod. This can be anything the mod author wishes, but is best to add a meaningful description of the mod.

Add each element listed above to the info.xml' script. Remember that capitalization matters if the tag format is changed! The text placed between the opening and closing tags is what will be displayed to users.

<?xml version="1.0" encoding="UTF-16"?>
<fomod>
   <Name>My Mod Name</Name>
   <Author>Author01, Author02, Author03</Author>
   <Id>xxxx</Id>
   <Version MachineVersion="1.0">1.0</Version>
   <Website>https://www.LinkToModPage.com/</Website>
   <Groups>
      <element>Models and Textures</element>
      <element>Patches</element>
      <element>My Category</element>
   </Groups>
   <Description>
<![CDATA[
My mod's beautiful, short description.

Changes this release:
- Fixed some issues with the Patches
- Updated FOMOD installer

Thanks for downloading and remember to endorse, if you enjoy it!]]>
   </Description>
</fomod>

Once complete, this concludes the info.xml script. Be sure to save before exiting!

ModuleConfig.xml File

The ModuleConfig.xml file is where all the magic happens. It houses the code used by mod managers to configure and display the GUI to the user. This Guide intends to cover all of the scripting available and FOMODs can be fairly complex; however, not all users need complex configurations. As such this section of the Guide will cover the basic elements for users and the more advanced elements within the Advanced Scripting section.

NOTE

The headings below are only named as such to help sectionalize the different areas of the code in relation to this Guide and, therefore, are NOT in any way official sections within the ModuleConfig.xml file. They are only used for context.

The Header

The header section is the beginning section of the ModuleConfig file which consists of four elements (tags): config, moduleName, requiredInstallFiles, and installSteps. 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-16] 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="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://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="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://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 files to be install, regardless of the options chosen by the user. These are normally files such as a ReadMe or files that the mod requires to function properly. For this guide, the STEP Compilation is being used as a reference; therefore, the included requiredInstallFiles section here includes files which are required for DynDOLOD to function properly with a STEP Guide installation.

The requiredInstallFiles element has an opening and closing tag; however, unlike most the the tags thus far, it only houses child elements: either a file element, a folder element, or multiple of each or both mixed. For this guide, it houses a single folder tag as such:

<config xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qconsulting.ca/fo3/ModConfig5.0.xsd">
   <moduleName>The STEP Installer</moduleName>
   <requiredInstallFiles>
      <folder source="00 Required" destination="" priority="1"/>
   </requiredInstallFiles>
</config>

Within each file or folder tag are up to three attributes: source, destination, and priority. These attributes are always defined as attributeName="attributeValue"; where the value is always encased between quotation marks.

The source attribute always lists the path to the file or folder being installed from the mod's root folder. In the case of folders, this will always be a single level path, as seen in the example above. This means the entire contents of the "00 Required" folder will be installed to the Data directory in Skyrim. Therefore, within these folders users should have the proper folder structure for the assets being installed. When installing a single file, the path needs to be defined to the file's location within the directory structure and include the file name, itself. For example:

source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds"

The destination attribute defines the destination of where the file or folder from the source attribute's value will be installed. When installing a specific file, unless that file will be installed within the Data directory itself, the destination will be the path to the folder where that file should be installed, omitting the Data folder in the path. See the example below. When installing an entire folder rather than a file, most often it will be installed in the Data folder. In these cases, destination should not be defined because the default directory for this attribute is the Data folder, and is also the reason it's omitted from the path. Leaving this undefined, as in the example above, the folder or file will be installed into the Data folder.

   <requiredInstallFiles>
      <folder source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds" destination="textures\terrain\tamriel\trees\" priority="1"/>
   </requiredInstallFiles>

The priority attribute defines the priority in which files or folders from the entire FOMOD should be installed. The lower the number, the lower the priority will be during file/folder installation. This means a file or folder with a priority value of "1" will be installed before any other files or folder. A file or folder with a priority value of "2" will overwrite any file or folder with a priority or "1" or lower. Think of it as the installation order for the files and folders where the mod author can control the order in which the files are installed. This is useful for mean reasons. For example, if a mod author has a set of armor meshes and textures in the assets which are installed automatically with the requiredInstallFiles element but wants to provide compatibility with another armor mod retexture. The author can simply give those compatibility files a higher priority and the installer will overwrite the default textures with the compatible textures. Understanding how priorities work within a FOMOD script can be a powerful asset to make potentially complex FOMODs more simple. You can see in the examples above, the priority attribute was given a value of "1", for this guide. To suit their preferences, users can start from 0 or 1 for this value. The starting value isn't important as long as the priorities are set properly.

installSteps Element

The final element of the header section is the installSteps element. This element is similar to the config element above in that it contains all the FOMOD "pages" between its opening and closing tags. The installSteps tag contains one attribute, order, and should be defined as below. The order attribute with a value of Explicit ensures the pages of the FOMOD are displayed in the order which they are written in the script. If this attribute is not defined, the order will be alphabetical using the names from the installStep element. This is usually not desired behavior so including the attribute will allow mod authors to guide users through the installer in a specific manner.

<config xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qconsulting.ca/fo3/ModConfig5.0.xsd">
   <moduleName>The STEP Installer</moduleName>
   <requiredInstallFiles>
      <folder source="00 Required" destination="" priority="1"/>
   </requiredInstallFiles>
   <installSteps order="Explicit">
   </installSteps>
</config>

FOMOD Pages

FOMODs can consist of one or multiple pages to suit to needs of the mod author. Each page is constructed by using various sets of elements which are explained below. There are more elements which can be include than listed below, however, these are considered advanced so they will be discussed later in the Advanced Scripting section of this guide.

installStep

This is the first element for any FOMOD page and tells the XML parser that a new page is starting. This element will contain all other child elements listed below between its opening and closing tags. There is only attribute within this element, name. The name attribute gives the page a name for the mod managers to display. Remember, if you didn't include the order="Explicit" attribute in the installSteps element above in the Header, then the FOMOD will list the pages in alphabetical order using the value placed within the name attribute here and on subsequent pages.

optionalFileGroups

This element houses the rest of the page elements between its opening and closing tags. Think of this element as a container for the group elements below.

group

The next element is the group element. This element will house the plugin elements for each group between its opening and closing tags. There can be one or multiple group elements for each page. Each group element has two available attributes: name and type. The name attribute assigns a name to the corresponding group. The type attribute assigns the type of selection each group is. The available types are:

SelectAny

This type displays checkboxes and allows users to select any of the listed options. If a group has no install options and is simply used for informational purposes, this type must be used. Use this type when all or none of the options from the group can be selected by the user.

SelectExactlyOne

This type displays radio buttons and allows users to select only one option from the listed options. Use this type when only one option should be selected from the group and at least one option is required to be selected.

SelectAtMostOne

This type displays radio buttons and allows users to select only one option from the listed options like SelectExactlyOne; however, it will add a None option for users to select if none of the options are desired. Use the type when only one option should be selected from a group, but also when none of the options are required.

SelectAtLeastOne

This type displays checkboxes and allows users to select any of the listed options like SelectAny; however, it's also similar to SelectExactlyOne in that at least one option must be selected. This type is not often used. Use it whenever a user must select at least one option from the group, but also has the option of selecting more than one or all options available.

SelectAll

This type displays checkboxes, but requires users to select all listed options and will automatically have these options selected. MO users will not be able to deselect these options and NMM users will receive a warning if they attempt to do so. This is the least used type and is typically only used in combination with conditions and flags, which is discussed in the Advanced Scripting section of this guide. Use this whenever all options in a group must be selected.

plugins

Like the optionalFileGroups element, the plugins element is mainly a container for the plugin elements. This element will house all the plugin elements between its opening and closing tags. It also has one attribute, order. This attribute does the same as it does in the installSteps element explained earlier in the Header section. When used, the order="Explicit" attribute will maintain the list of plugins in the order they are listed. If this attribute is omitted, the plugins within that group will be listed alphabetically.

Since the next element, plugin, is where most of the magic happens, this opening section will be ended here to allow a more in-depth look at what happens between the plugin tags.

Plugin Element

plugin

This is where the fun starts happening.

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