User:TechAngel85/Sandbox2

From STEP Modding Wiki

Contents

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 for users to learn how FOMODs are written besides looking at another 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. The order the information is presentation is not done well for new users and it feels like there is no continuity to the guide. It also only gives users a basic layout of the moduleConfig.xml file without going into enough detail for users to learn how to make more complex FOMODs so they can fully utilize a FOMOD's 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. The information will be presented in an order which makes sense and promotes learning, while being more detailed to explain the code and how to use it. It is recommended to become familiar with the terms associated with XML since this guide will be using them extensively.

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 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".
Info-Logo.png      Notice:For steps 3 through 5 to work properly, users must have extensions enabled for files. Most power users or authors will already have this done. If it's not done, please do so by following this guide for Windows 7/Vista and this guide for Windows 8+.

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.
Info-Logo.png      Notice:When using the BAIN format, the folder named "00 Name" is almost always files which are required by the mod regardless of other options. Many authors will also name this folder, "00 Core". Also, since no Wizard will be created at this time, it is best to use descriptive names for the folders. This way WB users will be able to decipher what the options are.

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>
Info-Logo.png      Notice:It's important to know that XML tags are case sensitive! When writing FOMODs, the case of the tags must match the way they are shown within this Guide. <optionalfilegroups> is NOT the same as <optionalFileGroups> in XML scripting!

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.
Info-Logo.png      Notice:XML documents should always be written and saved with UTF-8 encoding or issues will arise. You will notice the below encoding in the XML declaration is UTF-16. This reason for this is unknown at the time of this writing.

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 mod page are most often used and mod managers will display this as a clickable link to the user.
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.
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.

Info-Logo.png Notice: 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 the purpose of this guide.


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-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 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="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://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="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://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.

Dependencies

Troubleshooting

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



NOTES

Nothing as of yet...