Guide:FOMOD/ModuleConfigXML: Difference between revisions

Latest revision as of 06:53, December 16, 2022

FOMOD Guide

ModuleConfig.xml Reference

by: Step Modifications and community | Forum Topic

NOTE

The headings below are only named as such to help sectionalize the different areas of the script for reference purposes.

Script Header and Page Container

The "header" section referenced here is the beginning elements of the ModuleConfig script, which consists of following elements:

config
moduleName
requiredInstallFiles (optional)

The "page container" is the installSteps element that individual pages are nested within.

config

Just like the info.xml script, the ModuleConfig.xml script must start with a specific line of code. This time, it's the config element. This holds a very specific set of attributes, which tell the XML parser how to handle the file. Unlike the info.xml script, this starting tag must also be closed and all other elements within the the script will be nested within the config element. To get started,

Navigate to the ModuleConfig.xml script and open it in a text editor
Ensure the programming language is set to XML
Ensure the encoding is set to UTF-16

Now it's time to include the config elements. Knowing what this element'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

The moduleName element holds the name of the module, which is placed between the opening and closing tags. This can be anything, but it's recommended to use the name of the mod which the FOMOD is being created for. This element is nested below the config' element; 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 SkyrimSE Guide</moduleName>
</config>

requiredInstallFiles

The requiredInstallFiles element's section is optional, meaning it does not need to be included within the ModuleConfig script. This element exists to install any required files without user intervention. These are normally files such as a ReadMe or files that the mod requires to function properly. The element only contains either a file element, a folder element, or a combination of both. For this Guide, it contains a single folder element:

<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="000 Required - Core Files" destination="" priority="0"/>
   </requiredInstallFiles>
</config>

File and Folder Elements

Within each file or folder elements are up to three attributes:

source
destination
priority

These attributes are always defined as attributeName="attributeValue"; the value is always within quotation marks.

Source

The source attribute defines the path to the file or folder being installed from the mod's folder structure. 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 "000 Required - Core Files" folder will be installed to the game's directory. When installing a single file, the path needs to be defined to the file's location within the folder structure and include the file name, itself. For example: source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds"

Destination

The destination attribute defines the destination of where the file or folder from the source attribute's value will be installed. When installing an entire folder, 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. When installing a specific file, unless that file will be installed within the Data directory itself, the destination should be the path to the folder where that file should be installed. See the example below:

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

Priority

The priority attribute defines the order in which files or folders from the entire script are installed. The lower the value, the lower the priority will be during file/folder installation. The starting value isn't important as long as the priorities are set properly. For example:

A file/folder with a priority value of 0 will be installed before any other files or folder
A file/folder with a priority value of 1 will overwrite any file/folder with a priority of 0, but before any other high values
A file/folder with a priority value of 2 will overwrite any file/folder with a priority of 1 or 0, but before any other high values
...and so go and so on

installSteps

The "page container" element is: installSteps. This element is similar to the config element in that it contains all the FOMOD "pages" within its opening and closing tags. The installSteps element contains one attribute, order, and should be defined as below. The order attribute with a value of Explicit ensures the pages of the pages are displayed in the order they are written into the script. If this attribute is not defined, the order of the pages will be alphabetical. This is usually not desired behavior so including the attribute will allow users to be guided through the installer in a specific order.

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

installStep (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. There are more elements other than the ones listed below; however, these are considered advanced and are discussed in the Advanced Scripting Reference.

The installStep' element is the initial element that defines a new page. This element is a container, nesting all other page elements within its opening and closing tags. There is only one attribute: name. The name attribute defines the page name for the mod manager GUI.

NOTE:

Remember, if order="Explicit" attribute isn't defined in the installSteps element, then pages will be listed in alphabetical order using the value from these name attributes.

optionalFileGroups

The optionalFileGroups element is a simply a container element that houses the rest of the page elements between its opening and closing tags.

group

The group element defines a new grouping of plugin elements and is a container element. One group element is required per page, however, multiple groups can exist on a single page. The group element has two attributes: name and type

The name attribute assigns a name to the corresponding group.
The type attribute defines the type of user selection for the corresponding group. The available types are:

Type Name	Displays	Description
SelectAll	checkbox	Requires users to select all listed options and will automatically have these options selected. Some mod managers correctly prevent users from deselecting these options. Others incorrectly allow it and may or may not produce a warning from doing so. SelectAll is the least used type and is typically only used in combination with conditions and flags, which are discussed in the Advanced Scripting Reference. Use this whenever all options in a group must be selected.
SelectAny	checkbox	Allows users to freely select/unselect any of the listed options. If a group only has a single option, this type must be used.
SelectAtLeastOne	checkbox	This type works just like SelectAny; however, at least one option is required to be selected. 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 within a group.
SelectExactlyOne	radio buttons	Allows users to select only one option from the list. Use this type when only one option should be selected from the group and at least one option is required.
SelectAtMostOne	radio buttons	This type works just like SelectExactlyOne, however, SelectAtMostOne adds a None option for users to select. Use this type when only one option should be selected from a group, but also when none of the options are required.

plugins

Like the optionalFileGroups element, the plugins element is a container for the plugin elements. The optionalFileGroups element has one attribute: order. This attribute does the same as it does in the installSteps element, explained earlier. When used, the order="Explicit" attribute will maintain the list of plugins elements in the order they are written in the script. If this attribute is omitted, the plugins within that group will be listed alphabetically.

plugin

plugin: This is where the fun starts happening.

description

image

typeDescriptor

files

files and folders

@@ Line 31: / Line 31: @@
 </syntaxhighlight>
-===requiredInstallFiles Element===
+===requiredInstallFiles===
-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 [[Dynamic Distant Objects LOD|DynDOLOD]] to function properly with a STEP Guide installation.
+The ''requiredInstallFiles'' element's section is optional, meaning it does not need to be included within the ''ModuleConfig'' script. This element exists to install any required files without user intervention. These are normally files such as a ReadMe or files that the mod requires to function properly. The element only contains either a ''file'' element, a ''folder'' element, or a combination of both. For this Guide, it contains a single ''folder'' element:
-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:
 <syntaxhighlight lang="xml">
 <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"/>
+       <folder source="000 Required - Core Files" destination="" priority="0"/>
     </requiredInstallFiles>
 </config>
 </syntaxhighlight>
-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.
+====File and Folder Elements====
+Within each ''file'' or ''folder'' elements are up to three attributes:
+* ''source''
+* ''destination''
+* ''priority''
+These attributes are always defined as <code>attributeName="attributeValue"</code>; the value is always within 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=====
-<pre>source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds"</pre>
+The '''''source''''' attribute defines the path to the file or folder being installed from the mod's folder structure. 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 "''000 Required - Core Files''" folder will be installed to the game's directory. When installing a single file, the path needs to be defined to the file's location within the folder structure and include the file name, itself. For example:
+<code>source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds"</code>
-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.
+=====Destination=====
-<syntaxhighlight lang="xml">
+The '''''destination''''' attribute defines the destination of where the file or folder from the ''source'' attribute's value will be installed. When installing an entire folder, 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. When installing a specific file, unless that file will be installed within the ''Data'' directory itself, the ''destination'' should be the path to the folder where that file should be installed. See the example below:
-   <requiredInstallFiles>
+<syntaxhighlight lang="xml"><requiredInstallFiles>
-      <folder source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds" destination="textures\terrain\tamriel\trees\" priority="1"/>
+   <folder source="00 Required\textures\terrain\tamriel\trees\tamrieltreelod.dds" destination="textures\terrain\tamriel\trees\" priority="1"/>
-   </requiredInstallFiles>
+</requiredInstallFiles>
 </syntaxhighlight>
-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.
+=====Priority=====
+The '''''priority''''' attribute defines the order in which files or folders from the entire script are installed. The lower the value, the lower the priority will be during file/folder installation. The starting value isn't important as long as the priorities are set properly. For example:
+* A file/folder with a priority value of '''0''' will be installed before any other files or folder
+* A file/folder with a priority value of '''1''' will overwrite any file/folder with a priority of '''0''', but before any other high values
+* A file/folder with a priority value of '''2''' will overwrite any file/folder with a priority of '''1''' or '''0''', but before any other high values
+* ...and so go and so on
-===installSteps Element===
+===installSteps===
-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.
+The "page container" element is:  '''''installSteps'''''. This element is similar to the ''config'' element in that it contains all the FOMOD "pages" within its opening and closing tags. The ''installSteps'' element contains one attribute, '''order''', and should be defined as below. The ''order'' attribute with a value of '''Explicit''' ensures the pages of the pages are displayed in the order they are written into the script. If this attribute is not defined, the order of the pages will be alphabetical. This is usually not desired behavior so including the attribute will allow users to be guided through the installer in a specific order.
 <syntaxhighlight lang="xml">
@@ Line 71: / Line 80: @@
 </config>
 </syntaxhighlight>
+<br>
-==FOMOD Pages==
+==installStep (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.
+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. There are more elements other than the ones listed below; however, these are considered advanced and are discussed in the Advanced Scripting Reference.
-;installStep
+The '''''installStep'''''' element is the initial element that defines a new page. This element is a container, nesting all other page elements within its opening and closing tags. There is only one attribute: '''name'''. The ''name'' attribute defines the page name for the mod manager GUI.
-: 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 <code>order="Explicit"</code> 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.
+: {{AlertSmall|type=notice|text=Remember, if <code>order="Explicit"</code> attribute isn't defined in the ''installSteps'' element, then pages will be listed in alphabetical order using the value from these '''name''' attributes.}}
-;optionalFileGroups
+===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.
+The '''''optionalFileGroups''' element is a simply a container element that houses the rest of the page elements between its opening and closing tags.
-;group
+===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:
+The '''''group''''' element defines a new grouping of ''plugin'' elements and is a container element. One ''group'' element is required per page, however, multiple groups can exist on a single page. The ''group'' element has two attributes: ''name'' and ''type''
-::;SelectAny
+* The '''name''' attribute assigns a name to the corresponding group.
-::: 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.
+* The '''type''' attribute defines the type of user selection for the corresponding group. The available types are:
-::;SelectExactlyOne
+:: {| class="wikitable" style="text-align:left;"
-::: 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.
+! Type Name
-::;SelectAtMostOne
+! Displays
-::: 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.
+! Requires User Selection
-::;SelectAtLeastOne
+! Description
-::: 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
+| 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.
+| checkbox
+| style="text-align:center;" | {{icon|yes}}
+|  Requires users to select all listed options and will automatically have these options selected. Some mod managers correctly prevent users from deselecting these options. Others incorrectly allow it and may or may not produce a warning from doing so. ''SelectAll'' is the least used type and is typically only used in combination with conditions and flags, which are discussed in the Advanced Scripting Reference. Use this whenever all options in a group must be selected.
+|-
+| SelectAny
+| checkbox
+| style="text-align:center;" | {{icon|no}}
+| Allows users to freely select/unselect any of the listed options. If a group only has a single option, this type must be used.
+|-
+| SelectAtLeastOne
+| checkbox
+| style="text-align:center;" | {{icon|yes}}
+| This type works just like ''SelectAny''; however, at least one option is required to be selected. 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 within a group.
+|-
+| SelectExactlyOne
+| radio buttons
+| style="text-align:center;" | {{icon|yes}}
+| Allows users to select only one option from the list. Use this type when only one option should be selected from the group ''and'' at least one option is required.
+|-
+| SelectAtMostOne
+| radio buttons
+| style="text-align:center;" | {{icon|yes}}
+| This type works just like ''SelectExactlyOne'', however, '''SelectAtMostOne''' adds a '''None''' option for users to select. Use this type when only one option should be selected from a group, but also when none of the options are required.
+|}
-;plugins
+===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 <code>order="Explicit"</code> 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.
+Like the ''optionalFileGroups'' element, the '''plugins''' element is a container for the ''plugin'' elements. The ''optionalFileGroups'' element has one attribute: '''order'''. This attribute does the same as it does in the ''installSteps'' element, explained earlier. When used, the <code>order="Explicit"</code> attribute will maintain the list of plugins elements in the order they are written in the script. 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==
-=== Plugin Element ===
 ;plugin
 : This is where the fun starts happening.
+===description===
+===image===
+===typeDescriptor===
+===files===
+====files and folders====