Zumbs' Blog

The truth may be out there, but lies are inside your head

FOMM and FOMODs for Dummies 3: Basic FOMOD Scripting I

Posted by Zumbs on November 8, 2009

FOMM and FOMODs for Dummies

  1. Installing Mods
  2. Making FOMODS
  3. Basic FOMOD Scripting I
  4. Basic FOMOD Scripting II
  5. Working with Forms I
  6. Working with Forms II
  7. Load Order Magicks

In the previous tutorial, we investigated how to make and work with fomod files. This two part tutorial will show how to make a basic install script. This part focus on how to validate the user’s installation of Fallout 3.

The FOMOD format allows some quite sophisticated install scripts, which can be a great help for mod users (and reduce the number of people complaining that they could not get it to work), and can assist in testing your mod under different configurations.

The scripts must be written in the programming language C#, and can draw on functions from the .NET library. C# is very similar to Java (not JavaScript) and somewhat similar to C++. For the scripts discussed in this tutorial, you will not need to know much about C# or .NET, but if you plan on using some of the more advanced features of the FOMOD install scripts, you may want to check out a few basic tutorials on C#.

The install scripts are placed in the scripts.cs file in the fomod folder, and can be opened and edited by pressing the Edit Script or Create Script button in the Package Manager:
package-manager-create-script

This opens the Script Editor:
script-editor

Aside from the code window, note how the toolbar allow you to save the file and check the syntax. Be sure to check the syntax regularly! If an error is found, the line number and an error message will be shown. Also note that even if the syntax is correct, the script may not do what you intended it to do, so be sure to test your code regularly!

When the user presses the Activate button in the Package Manager, the OnActivate function is run. When this function is done, it returns a value (true or false) to FOMM to indicate if the install were successful or not. Please note that files installed by an unsuccessful install are not automatically removed by the Package Manager.

Checking FOSE version

Your mod may use functionality introduced in a certain FOSE version. In this case, it would be a good idea to check if FOSE is present and have the correct version. If the following script is added to the first line of the OnActivate function, it detects if FOSE is installed with the correct version (1.1b9). If this is the case, installation can proceed, and if not, the installation is stopped and the user is prompted to get the latest version.

Version requiredFose = new Version(0, 1, 1, 9);
if (GetFoseVersion() < requiredFose)
{
    MessageBox("This mod requires FOSE v " + requiredFose + " or higher. You have " + GetFoseVersion() 
        + ". Please update from http://silverlock.org");
    return false;
}

Checking patch version

In some cases your mod works best with a certain version of the game. For instance, in unpatched version of Fallout 3, uninstalling a mod that added a perk to the player would cause a crash on load. This can be done like this:

Version requiredGameVersion = new Version(1, 6);
if (GetFalloutVersion() < requiredGameVersion)
{
    MessageBox("You are using an unpatched version of the game that cause a"
        + " crash on load after uninstalling this mod, unless you remove the perk first. Please patch your game.", "Error");
}

You may also want to allow the user to cancel the installation at this point, which can be performed by this script:

Version requiredGameVersion = new Version(1, 6);
if (GetFalloutVersion() < requiredGameVersion)
{
    DialogResult res = MessageBox("You are using an unpatched version of the game that cause a"
        + " crash on load after uninstalling this mod, unless you remove the perk first. Please patch your game.", 
        "Error", MessageBoxButtons.OKCancel);
    if (res == DialogResult.Cancel)
    {
        return false;
    }
}

Usage of DialogResult requires that you add the line below to the top of the script file:

using System.Windows.Forms;

Editing the .ini

A number of mods need to edit the ini. An example is DarNified UI, where the fonts used by the UI are changed. Many mods rely on having the ini setting bInvalidateOlderFiles set to 1. This can be handled by this piece of code:

if (GetFalloutIniInt("Archive", "bInvalidateOlderFiles") == 0) {
   EditFalloutINI("Archive", "bInvalidateOlderFiles", "1", true);
}

Note how an ini setting is found: The first argument is the ini group (“Archive”), the second is the ini setting itself (“bInvalidateOlderFiles”), and the third is the new value, all in quotation marks. The last argument to EditFalloutINI is an instruction to FOMM telling it to remember the original setting, so it can be restored when the mod is uninstalled. Usually, it is good practice to ask the users permission to change ini settings before doing so.

Pulling it together

The with the options above, our script is now

using System;
using System.Windows.Forms;
using fomm.Scripting;

class Script : BaseScript {
	public static bool OnActivate() {
	    Version requiredFose = new Version(0, 1, 1, 9);
	    if (GetFoseVersion() < requiredFose)
	    {
	        MessageBox("This mod requires FOSE v " + requiredFose + " or higher. You have " 
                    + GetFoseVersion() + ". Please update from http://silverlock.org");
	        return false;
	    }
	    Version requiredGameVersion = new Version(1, 6);
	    if (GetFalloutVersion() < requiredGameVersion)
	    {
	        DialogResult res = MessageBox("You are using an unpatched version of the game that cause a"
                    + " crash on load after uninstalling this mod, unless you remove the perk first. Please patch your game.", 
                    "Error", MessageBoxButtons.OKCancel);
	        if (res == DialogResult.Cancel)
	        {
	            return false;
	        }
	    }
	    DialogResult iniEdit = MessageBox("Do you wish to modify the ini?", "Ini change", MessageBoxButtons.YesNo);
	    if (iniEdit == DialogResult.Yes)
	    {
	        if (GetFalloutIniInt("Archive", "bInvalidateOlderFiles") == 0) {
	           EditFalloutINI("Archive", "bInvalidateOlderFiles", "1", true);
	        }
	    }
	    
        //Install all files from the fomod and activate any esps
        PerformBasicInstall();
		return true;
	}
}

Message boxes are an easy method for the mod author to communicate with the mod user. However, they also have a number of drawbacks, particularly if you wish to give the mod user a number of install options. This difficulty can be overcome by using forms, which is the topic for an upcomming tutorial. First, however, we will look at how to customize install scripts.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: