Using special characters in your installer's description text
To force carriage returns in the description text for any installer options (known as a plugin in the XML code), you need to use Character Escaping, as explained in this very technical W3C web page on Canonical XML specifications. Although the Info.xml document of FOMOD installers sets the character encoding to UTF-16, most of the character definitions on that web page should still work. To produce a carriage return, use the characters & # x D ; (without the spaces) between the <description> / </description> tags.
Since the character escape codes don't display correctly in the Nexus comments, please see this example FOMOD description text on pastebin as an example of how to use the carriage return code.
A few more things to note about the description text:
+ You don't actually need to use the <![CDATA[]]> code around your description text. + There are some characters ( & < > " ) you CAN'T use in plain text for the description - they will cause an error. Use a character escape code instead. See my pastebin text link above for a short list of the equivalent codes to use. + If the TAB key is used to indent text in the description, it will result in problems with the formatting. Make sure all text between the <description> / </description> tags is flush left justified when viewed in a text editor. + You can use the character escape code for TAB but it indents the text too far. I suggest just adding spaces before the line of text to indent it.
EDIT: It's important to note the "illegal" plain text characters mentioned above should also not be used anywhere between quote marks in the XML code.
Specifically, don't use those characters in the names of installSteps, groups, plugins, flag names, folder or file source/destination names, etc. I have used the + character without problems, but I'd recommend not using for folder/file names, because it can cause problems for Wrye Bash users trying to install according to numbered install directory names.
Setting the source / destination for files to be installed
Really the easiest way to set up which files get installed for any option picked in the installer is to use a folder system, and in the ModuleConfig.xml, between the <files> & </files> tags, use a folder source tag, like this: <files> <folder source="Name of Folder in installer archive" destination="" /> </files> Doing it this way will copy whatever is in the folder straight to your /data directory.
So, for example, I could have a folder named "000 Main BSA and Assets", and inside you see: MyMod.bsa /sounds
Inside /sounds could be nested folders with replacements for vanilla Skyrim sounds. All of that would be copied exactly in the same folder structure into your /data folder.
Certainly you can use the destination= feature to have the installer place files in a folder other than the root /data directory, but that just makes things potentially over-complicated.
Requirements in the code for installer options (plugins)
Every plugin must contain either a set of <files> & <files/> or <conditionFlags> & <conditionFlags/> tags.
If you don't have at least ONE of them, then the FOMOD installer will give an error in NMM or MO's external FOMOD installer.
Note that you don't actually have to define any files / folders to install or name any conditional flags - which is useful if you just want to present an installer screen with "thank you" or "notification" message. Also note that the <image name=""/> flag is not required for each plugin.
Thank you very much for releasing this guide. I had questions about the fomod XMLs because I really dislike the auto patch feature where it will not allow you to pick your own patches if the proper mods aren't ticked in your load order. I figured it out changed the XML and can now pick and choose my own patches.
gandaganza - just because you're so awesome, I've shared a couple of things with you and everyone else:
1. An example Skyrim mod FOMOD installer package, which I've put in the Optional Downloads section.
It is set up with two installer windows steps, the first one giving options to install a main plugin in four variations (Skyrim only, Skyrim + DG, Skyrim + DB, and Skyrim + DG + DB). All four options are set to grab files from a common BSA & assets folder. Then the second window has two sections of options, one with an example of a "choose one weather mod patch" (or none) option, and then a compatibility patch section with toggle boxes. Everything has example description text, and very basic images. Also, the XML code of this example installer shows how multiple flags can be used for each option in order to perform conditional file installs in the last section of the XML based on flag dependency logic.
This example is a .7z archive that works fully if installed in either NMM and Mod Organizer (and it's also Wrye install-friendly), with all folders included containing dummy files so you can play around with things and do installation tests. Note, however, that it does not install any playable files.
2. A draft FOMOD visual tutorial document that I had started about a year ago to help LoRd KoRn learn how to work with the FOMOD installer I made for his Audio Overhaul for Skyrim mod. Unfortunately, he is so busy that he couldn't really make use of it, so I never finished it. Perhaps it would be something useful for me to work on again? I'll let you tell me if you think that's a good idea, after looking at it. Grab a PDF of it from here - and on this one, please don't post it anywhere, as it's unfinished.
It really surprises me that people would have trouble finding this seminal document, just because its mod page is in the Fallout New Vegas section of Nexus.
If you really find the document useful, as I did when I found it some time ago, you should head over to the original mod page from nyrb, download it (again), and endorse.
No time now, but I'll be coming back here soon to add some notes and information that aren't covered in the PDF.
Thanks gandaganza for highlighting this information, and again thanks to nyrb and kaburke as the creators.
Not everyone is as versed in modding as you keith :p Something as minor as being labeled "FOMOD script" instead of "installer instructions" will scare people away :/
Please do! Just don't make me feel guilty about not updating my installers with more efficient code xD
And thanks for the original mod page! For some reason google would not show it to me! I'll add that to the description!
Er... Well.. To be fair... I searched for a FOMOD guide/tutorial and never found this because I honestly wouldn't have thought to search FONV stuff when I only mod Skyrim. XD
14 comments
- Apparently flags can only be set once.
To force carriage returns in the description text for any installer options (known as a plugin in the XML code), you need to use Character Escaping, as explained in this very technical W3C web page on Canonical XML specifications. Although the Info.xml document of FOMOD installers sets the character encoding to UTF-16, most of the character definitions on that web page should still work. To produce a carriage return, use the characters & # x D ;
(without the spaces) between the <description> / </description> tags.
Since the character escape codes don't display correctly in the Nexus comments, please see this example FOMOD description text on pastebin as an example of how to use the carriage return code.
A few more things to note about the description text:
+ You don't actually need to use the <![CDATA[]]> code around your description text.
+ There are some characters ( & < > " ) you CAN'T use in plain text for the description - they will cause an error. Use a character escape code instead. See my pastebin text link above for a short list of the equivalent codes to use.
+ If the TAB key is used to indent text in the description, it will result in problems with the formatting. Make sure all text between the <description> / </description> tags is flush left justified when viewed in a text editor.
+ You can use the character escape code for TAB but it indents the text too far. I suggest just adding spaces before the line of text to indent it.
EDIT: It's important to note the "illegal" plain text characters mentioned above should also not be used anywhere between quote marks in the XML code.
Specifically, don't use those characters in the names of installSteps, groups, plugins, flag names, folder or file source/destination names, etc. I have used the + character without problems, but I'd recommend not using for folder/file names, because it can cause problems for Wrye Bash users trying to install according to numbered install directory names.
Really the easiest way to set up which files get installed for any option picked in the installer is to use a folder system, and in the ModuleConfig.xml, between the <files> & </files> tags, use a folder source tag, like this:
<files><folder source="Name of Folder in installer archive" destination="" />
</files>
Doing it this way will copy whatever is in the folder straight to your /data directory.
So, for example, I could have a folder named "000 Main BSA and Assets", and inside you see:
MyMod.bsa
/sounds
Inside /sounds could be nested folders with replacements for vanilla Skyrim sounds. All of that would be copied exactly in the same folder structure into your /data folder.
Certainly you can use the destination= feature to have the installer place files in a folder other than the root /data directory, but that just makes things potentially over-complicated.
Every plugin must contain either a set of <files> & <files/> or <conditionFlags> & <conditionFlags/> tags.
If you don't have at least ONE of them, then the FOMOD installer will give an error in NMM or MO's external FOMOD installer.
Note that you don't actually have to define any files / folders to install or name any conditional flags - which is useful if you just want to present an installer screen with "thank you" or "notification" message. Also note that the <image name=""/> flag is not required for each plugin.
Endorsed and kudos, thank you!
It may be an okay example after some refining.
As for the conditions I chose not to nest them and the order is all screwed up.
If you have a better way of doing thing then please inform me.
1. An example Skyrim mod FOMOD installer package, which I've put in the Optional Downloads section.
It is set up with two installer windows steps, the first one giving options to install a main plugin in four variations (Skyrim only, Skyrim + DG, Skyrim + DB, and Skyrim + DG + DB). All four options are set to grab files from a common BSA & assets folder. Then the second window has two sections of options, one with an example of a "choose one weather mod patch" (or none) option, and then a compatibility patch section with toggle boxes. Everything has example description text, and very basic images. Also, the XML code of this example installer shows how multiple flags can be used for each option in order to perform conditional file installs in the last section of the XML based on flag dependency logic.
This example is a .7z archive that works fully if installed in either NMM and Mod Organizer (and it's also Wrye install-friendly), with all folders included containing dummy files so you can play around with things and do installation tests. Note, however, that it does not install any playable files.
2. A draft FOMOD visual tutorial document that I had started about a year ago to help LoRd KoRn learn how to work with the FOMOD installer I made for his Audio Overhaul for Skyrim mod. Unfortunately, he is so busy that he couldn't really make use of it, so I never finished it. Perhaps it would be something useful for me to work on again? I'll let you tell me if you think that's a good idea, after looking at it. Grab a PDF of it from here - and on this one, please don't post it anywhere, as it's unfinished.
I hope that all helps.... ;)
If you really find the document useful, as I did when I found it some time ago, you should head over to the original mod page from nyrb, download it (again), and endorse.
No time now, but I'll be coming back here soon to add some notes and information that aren't covered in the PDF.
Thanks gandaganza for highlighting this information, and again thanks to nyrb and kaburke as the creators.
Please do! Just don't make me feel guilty about not updating my installers with more efficient code xD
And thanks for the original mod page! For some reason google would not show it to me! I'll add that to the description!
In fact, everyone I asked for info on the subject directed me to the NMM Installer Tutorial - FOMOD - FOMM by XunAmarox as though it was the definitive source for such information.
As such, this was incredibly novel stuff to me. That being said, the original page is definitely getting my endorse as well.
Thanks for this