In this function list, arguments contained in < > are required, and [ ] are optional.
If <function> [...]
IfNot <function> [...]
Else
EndIf
These functions are used to selectively skip lines of script. The If or IfNot functions must be followed by another function. Using Else is equivalent to enclosing the piece after the Else in an IfNot EndIf block. Use EndIf to end the block
The available functions after if are:
If DialogYesNo <Message> [Title]
This displays a dialog box displaying the message you give. An If block will be executed if the user clicks yes.
Example
If DialogYesNo "Choose yes or no" Question
Message "You clicked yes"
Else
Message "You clicked no"
EndIf
If DataFileExists <FileName>
This checks if a data file already exists in the data files directory. The FileName must be relative to the 'oblivion\data files\' directory.
If VersionGreaterThan <version>
If VersionLessThan <version>
This checks a version number against the current obmm version. Use these if you mod must be installed by a version of obmm newer than a specific version. VersionGreaterThan is actually greater or equal to - it returns true if the version you enter is the current version of obmm. The version must be given by 3 bytes seperated by periods, where the bytes represent major version, minor version and revision.
Example
If VersionLessThan 0.6.0
Message "This mod must be installed by obmm 0.6.0 or later"
FatalError
EndIf
If ScriptExtenderPresent
If ScriptExtenderNewerThan <version>
Use these if your mod requires Oblivion Script Extender. ScriptExtenderPresent will return true if obse_loader.exe exists in the players oblivion directory. ScriptExtenderNewerThan will check the version number of obse_loader.exe against a number supplied in your script, and will return true if it has an equal or greater version number to the one you supplied. The format of the version number is 'Major.Minor.Revision.Build' (e.g. '0.0.0.4')
obse version sheme changed at version 9; previously it only used the build number (e.g. 0.0.0.4 for v0004) but newer versions use the revision number. (e.g. 0.0.11.0 for v0011)
Example
IfNot ScriptExtenderNewerThan 0.0.0.4
Message "Part of this mod requires Oblivion Script Extender v0004 or higher and has been disabled." "Warning"
DontInstallPlugin "MyMod (obse extras).esp"
EndIf
If GraphicsExtenderPresent
If GraphicsExtenderNewerThan <version>
These work in exactly the same way as the ScriptExtender... functions, but check for oblivion graphics extender instead. (The file tested is data\obse\plugins\obge.dll)
If OblivionNewerThan <version>
The same is ScriptExtenderNewerThan, but checks oblivion's file version instead. Use '1.1.0.0' to check if the v1.1 official patch chas been installed.
If Equal <arg1> <arg2>
If GreaterThan <arg1> <arg2>
If GreaterEqual <arg1> <arg2>
If fGreaterThan <arg1> <arg2>
If fGreaterEqual <arg1> <arg2>
Returns true if the specified condition is met. For GreaterThan/GreaterEqual arg1 and arg2 must be castable to integers, and for FGreaterThan and FGreaterEqual they must be castable to floats.
Example
ReadRendererInfo package "Shader Package"
If GreaterThan %package% 4
IfNot Equal %package% 8
Message "The only supported shader package above 4 is 8." "Error"
FatalError
EndIf
EndIf
Select... <args>
Case <option>
Default
Break
EndSelect
Use these functions to choose from a set of multiple options. First use one of the Select functions, thent use a set of Case options to catch the result. The argument to the Case statment is implicitly assumed to be a string, so no ""'s are required even if it contains spaces. If obmm reaches a 'Default' statement before it reaches the Case that it is looking for, the set of lines underneath Default will be executed instead of the Case. A Break statement will immediately send control to the appropriate EndSelect statement.
obmm Selects work in the same was as C/C++ switchs - i.e. unless you explicitly add a Break statement, control will fall through to the next case statement.
Select <Title> <Option1> [Option2] [...]
SelectMany <Title> <Option1> [Option2] [...]
SelectWithPreview <Title> <Option1> <ImagePath1> [Option2] [ImagePath2] [...]
SelectManyWithPreview <Title> <Option1> <ImagePath1> [Option2] [ImagePath2] [...]
SelectWithDescriptions <Title> <Option1> <Description1> [Option2] [Description2] [...]
SelectManyWithDescriptions <Title> <Option1> <Description1> [Option2] [Description2] [...]
SelectWithDescriptionsAndPreviews <Title> <Option1> <ImagePath1> <Description1> [Option2] [ImagePath2] [Description2] [...]
SelectManyWithDescriptionsAndPreviews <Title> <Option1> <ImagePath1> <Description1> [Option2] [ImagePath2] [Description2] [...]
Select forces the user to choose exactly one option. SelectMany allows the selection of anything between 0 and every option. The case block of every selected option will be executed, even if obmm hits a Break in a previous case block.
By default, the first option is selected for Select, and no options are selected for SelectMany. You can place a '|' in front of options to change the defaults. Do not place the | in the Case statment.
SelectWithPreview and SelectManyWithPreview allows you to attach images to each option, which the user can then preview before choosing the option. The image paths for the preview functions must be relative paths pointing at files included in the omod. Remember to use DontInstallDataFile on the preview images, unless you want the images to be installed along with the rest of the omod. If you don't want an image to be available for an option, use 'None' for the image path.
SelectWithDescriptions and SelectManyWithDescriptions allow you to supply plain text descriptions of each option.
Example
Select "Choose an option", "option 1", "|option 2", "option 3", "option 4", "option5" ;option 2 will be selected by default
Case option 1
Message "You selected option 1"
;No 'Break' here, so the script will continue and execute anything below the 'Case option 2' line as well.
Case option 2
Message "You selected either option 1 or 2"
Break
Case option 3
Message "You selected option 3
Break
Default
Message "You selected either option 4 or 5"
Break ;Break not really required before an EndSelect, but it keeps things looking neat.
EndSelect
SelectVar <Variable>
SelectString <String>
Instead of allowing the user to choose an option, these test the value of the supplied argument instead. SelectVar implicitly assumes that the argument that you supply it is a variable, so you do not need the enclosing %%'s. SelectString makes no such assumption.
Note that 'SelectVar bingle' and 'SelectString %bingle%' are functionally identical.
Example
ReadRendererInfo package "Shader Package"
SelectVar package
Case 8
Case 9
Case 10
Break
Default
Message "You must be using shader package 8, 9 or 10" "Error"
FatalError
EndSelect
For <function> <variable> [...]
Continue
Exit
EndFor
These functions allow you to perform loops. As with the If function, there are various types of loops you can use. In each case, the variable you specify is set to a different value each loop, and then is undefined when the loop exits. When specifing the variable name, do not surround the name with %%'s. Continue causes the script to jump to the next EndFor, (and hence back to the start of the loop, if required) and Exit causes the script to jump to the line after the EndFor.
For Count <Variable> <Start> <End> [Step]
Counts up from 'start' to 'end', incrementing the variable by 'step' each time. If step is not specified, it is assumed to be 1.
Example
For Count var1 0 10 2
If Equal %var1% 6
Continue
EndIf
Message %var1%
EndFor
;Will output 0, 2, 4, 8, 10 in seperate message boxes
For Each DataFolder <variable> <FolderPath> [RecurseSubfolders] [SearchString]
For Each DataFile <variable> <FolderPath> [RecurseSubfolders] [SearchString]
For Each PluginFolder <variable> <FolderPath> [RecurseSubfolders] [SearchString]
For Each Plugin <variable> <FolderPath> [RecurseSubfolders] [SearchString]
Use these to loop through the contents of sepcific folders of the omod. Remember that the esps/esms are completely seperate from other data files, and the folder structure of one is not visable to the other.
RecurseSubfolders must be 'True' or 'False'. If not specified, False is assumed.
The searchstring behaves in the same way as windows explorers searching. Wildcards are allowed. If not specified, ' * ' is assumed. (i.e. all files will be matched)
Goto <label>
Label <label>
Use these functions to jump from one point to another point later in the script. They can be used to jump out of control structures, but may behave unreliably if used to jump into one. You cannot jump to a point earlier in a script with these.
Return
Use this to stop a script. Once a Return instruction is reached, no further lines of script will be executed.
Message <Message> [Title]
DisplayImage <Image File Path> [Title]
DisplayText <Text File Path> [Title]
These are used to display information to the user. Message displays a simple message box, DisplayImage displays an image and DisplayText displays a plain text or rich text file. The paths supplied to DisplayImage or DisplayText must be files which are included in the omod as data files. If the only purpose of the file is to be displayed in the script, remember to use DontInstallDataFile to stop obmm from installing it.
LoadBefore <Plugin1> <Plugin2>
LoadAfter <Plugin1> <Plugin2>
This command tells obmm that plugin1 must load before plugin2. Plugin1 must be part of this mod, but plugin2 can be from any mod. The argument is the entire filename of the mod, including the extension.
Example
If DataFileExists Bloodmoon.esm
LoadAfter MyMod_BloodmoonPatch.esp MyMod.esp
Else
DontInstallPlugin MyMod_BloodmoonPatch.esp
EndIf
UncheckESP <plugin>
Normally, any plugin extracted from an omod is automatically activated. You can use this function to prevent a specific plugin from being activated.
SetDeactivationWarning <plugin> <warning>
Normally, when you try and uncheck a plugin from the data files selecter, if the plugin belongs to an omod you are given a warning. You can use this function to either disable the warning, or to completely prevent the user from disabling the esp. Warning must be on of 'Allow', 'Disallow' or 'WarnAgainst'
ConflictsWith <ModName> [Comment] [Level]
ConflictsWith <ModName> <MinMajorVersion> <MinMinorVersion> <MaxMajorVersion> <MaxMinorVersion> [Comment] [Level]
ConflictsWithRegex <ModName> [Comment] [Level]
ConflictsWithRegex <ModName> <MinMajorVersion> <MinMinorVersion> <MaxMajorVersion> <MaxMinorVersion> [Comment] [Level]
DependsOn <ModName> [Comment]
DependsOn <ModName> <MinMajorVersion> <MinMinorVersion> <MaxMajorVersion> <MaxMinorVersion> [Comment]
DependsOnRegex <ModName> [Comment]
DependsOnRegex <ModName> <MinMajorVersion> <MinMinorVersion> <MaxMajorVersion> <MaxMinorVersion> [Comment]
The mod name is the actual name of the omod, and not the file name. You can see the mods name by hovering the mouse over it. The regex version of these functions perform regular expression matching.
You can also optionally supply a minimum and maximum version number. If you don't, any version of the mod will be matched. If you only want to give a minimum or maximum version to check against, and not both, then specify '0 0' as the version you don't want to use.
The comment will be displayed in the conflict report.
The level argument to ConflictsWith sets the severity of the conflict, and can be one of 'Minor', 'Major' or 'Unusable'.
Example
ConflictsWith "Vampire Embrace" 0 0 2 3 "This mod is incompatible with version of vampire embrace below 2.3" Unusable
DependsOn "Vampire Hunger" "No particular reason"
DependsOnPartial "foo*"
DontInstallPlugin <FileName>
DontInstallDataFile <FileName>
InstallPlugin <FileName>
InstallDataFile <FileName>
These functions can be used to modify the files installed by obmm. The file name must contain the full file name, including the relative path from the data files folder. A file which has been
DontInstallDataFolder <FolderName> [RecurseSubfolders]
InstallDataFolder <FolderName> [RecurseSubfolders]
This is the same as using DontInstallDataFile/InstallDataFile on every file in the specified folder. By default, subfolders are not effected. Use 'True' as the second argument to modify subfolder too. If you want to stop installation of most files in a folder, you can use this function and then use InstallPlugin on any files you want to keep. If you want to block installation of every sub folder apart from one, use DontInstallDataFolder on the root folder followed by InstallDataFolder on the subfolder you want to keep.
DontInstallAnyPlugins
DontInstallAnyDataFiles
InstallAllPlugins
InstallAllDataFiles
Normally, obmm installs every file except those specified in DontInstall... instructions. The DontInstallAny... instructions reverse that behaviour, so obmm doesn't install anything unless it's specifically specified in Install... instructions. If you call DontInstallAny..., you can cancel it later in the script by calling InstallAll...
Note that calling InstallAll... doesn't cancel any previous DontInstall... calls; it only cancels DontInstallAny... calls. Likewise, calling DontInstallAnyPlugins after calling InstallPlugin "bingle.esp" will still result in bingle.esp being installed.
Example
IfNot DialogYesNo "Do you want to overwrite the default textures?"
DontInstallAnyDataFiles
EndIf
CopyDataFile <CopyFrom> <CopyTo>
CopyPlugin <CopyFrom> <CopyTo>
This lets you rename or copy data files on the fly via script. It's a powerful function, but it wreaks havoc with my conflict detection... The first argument is the file you are copying. This must be a path relative to the oblivion\data directory. It must point at a file you have included with your mod. It doesn't matter if you have used DontInstallDataFile to prevent its installation; you can still copy it. The second file is where you are copying it to. This is also a path relative to the oblivion\data directory. It doesn't have to be a file originally included in your mod.
Note that behaviour of this function has changed slightly between 0.7.x and 0.8. Previous to 0.8 you had to use DontInstallDataFile if you were copying a file over one which already existed. In 0.8, this is no longer needed. Existing scripts are not effected, because any DontInstallDataFile functions used on copied files will be ignored.
Example
DontInstallDataFile "textures\\highrestexture.dds"
If DialogYesNo "Do you want to use high res textures?"
CopyDataFile "textures\\highrestexture.dds" "textures\\mymodel\\sometexture.dds"
EndIf
CopyDataFolder <CopyFrom> <CopyTo> [RecurseSubfolders]
This calls CopyDataFile on every file in the specified directory. If you specify True for the third parameter, the ocntents of any subfolders will be copied too. Any required folder structure will be created automatically.
PatchDataFile <NewFile> <FileToPatch> [Create]
PatchPlugin <NewFile> <FileToPatch> [Create]
Use these to patch files which already exist in the data files directory without throwing up conflict warnings. Create may be 'True' or 'False'. If True, the file will be created if it doesn't already exist. If False, the file to patch must already exist or the function will fail. If not specified, it defaults to False. (Since newly created files will end up unparented, I suggest leaving it at False and using CopyDataFile/Plugin instead for creating new files.)
These functions are unique, because they take effect even if omod activation fails. They are intended for use in patch omods that patch existing mods without ever being activated themselves, so it is safe to use FatalError to prevent the mod from appearing activated. Even if you do allow the mod to activate, files copied with these functions will not be linked to the patch omod, but will instead still be linked to their original omod. If the file didn't originally exist, it will be unparented.
In order to avoid conflict warnings given before the script is run, the replacement file should have a different name to the original.
No backups are made of the original files. Once patched, it would be necessary to deactivate and reactivate the original omod to restore the original files.
You cannot use this function to replace files which are not parented to an omod. (e.g. using PatchPlugin to try and replace Oblivion.esm would fail)
Example
DependsOn "An old plugin"
PatchPlugin "v2.0\anoldmod.esp" "anoldmod.esp" False
PatchDataFile "v2.0\meshes\anoldmod\FixedMesh.nif" "meshes\anoldmod\ACorruptMesh.nif" True
Message "Patch complete"
FatalError
RegisterBSA <FileName>
UnregisterBSA <FileName>
Use the RegisterBSA function to register a bsa file in oblivion.ini. The UnregisterBSA function can be used to cancel a RegisterBSA function, but cannot unregister an already registered BSA. The file name is the full file name of the bsa file to register, including the extension and relative path from the data files folder.
An archive registered with the RegisterBSA function will automatically be unregistered when the mod is removed. If more than one mod registers the same BSA file, the file will not be unregistered until all mods using it are uninstalled.
EditINI <section> <key> <new value>
This function can be used to make edits to oblivion.ini which will be automatically removed when your mod is deactivated. The section name must include the square brackets.
Example
EditINI [display] bDoSpecularPass 0
EditShader <ShaderPackage> <ShaderName> <BinaryObjectPath>
This function will edit individual shaders inside oblivions shader packages. You must include the compiled shader you wish to insert with your mod as a .pso or .vso file. The shader package is a number currently between 1 and 19 to specify which shader package you wish to edit. The second is the name of the shader you wish to edit, and the third is the path inside your omod to the binary file you wish to insert.
obmm will prevent multiple mods from editing the same shader, and will automatically remove the changes when you deactivate the omod.
Example
DontInstallDataFile shaders\GreenEye.pso
For Count package 1 19
EditShader %package% nighteye000.pso shaders\GreenEye.pso
EndFor
FatalError
This instruction completely cancels installation of the mod. No files will be installed, and no changes will be made to oblivion.ini, even if you have previously called functions such as RegisterBSA. No further lines of script will be executed.
Example
IfNot DataFileExists Bloodmoon.esm
Message "This mod requires bloodmoon to be installed" "Fatal error"
FatalError
EndIf
SetGMST <file> <editor id> <new value>
This function edits a gmst in an esp to the value you select. You can only edit esps/esms which were added by your mod. Remember that changing a gmst in a plugin will have undetermined effects on games already in progress which are already using that plugin. (i.e. Deactivating and reactivating an omod in order to change a gmst in one of the esps it controls will have unexpected side effects.) To edit a GMST, it must already exist in the plugin. This function will not create a new gmst record. Editing a string variable in a large esp is slow.
SetGlobal <file> <editor id> <new value>
This function edits a global variable in an esp or esm. You can only edit esps/esms which were added by your mod. This command will have similar side effects to EditGMST if used to change a plugin which is already in use. As with EditGMST, the global variable must already exist in the mod. This utility will not automatically add new records. If you ever get a choice between changing a GMST or a global, always take the global. GMSTs may be strings, so obmm needs to rewrite the entire esp. Globals are always the same size, so obmm can modify them far more quickly.
SetPluginByte <file> <offset> <new value>
SetPluginShort <file> <offset> <new value>
SetPluginInt <file> <offset> <new value>
SetPluginLong <file> <offset> <new value>
SetPluginFloat <file> <offset> <new value>
These functions modify the data at an arbitrary offset in an esp or esm. You can only edit esps/esms which were added by your mod.
These functions could be used to do things like modify weapon stats based on a user selected difficulty level, or changing the script on an item depending on what mods are already installed.
SetVar <variable> <value>
Sets a script variable to the given value.
Example
SetVar var1 bingle
Message %var1%
;Displays a messagebox containing 'bingle'
GetFolderName <variable> <path>
GetFileName <variable> <path>
GetFileNameWithoutExtension <variable> <path>
CombinePaths <variable> <path1> <path2>
Use these functions for manipulating paths. They'd normally be used for manipulating the output from the 'For Each ...' functions.
Substring <variable> <string> <startfrom> [length]
RemoveString <variable> <string> <startfrom> [length]
StringLength <variable> <string>
Use these functions for more general string manipulation.
Example
SetVar str "1 2 3 4"
Substring str "%str%" 2
Message "%str%" ;Will print "2 3 4"
RemoveString str "%str%" 2 2
Message "%str%" ;Will print "2 4"
StringLength str "%str%"
Message "%str%" ;Will print "3"
iSet <variable> <expression>
fSet <variable> <expression>
Allows you to perform some basic maths operations. Supported operators are +, -, *, /, ^, %, 'mod'. (mod and % do the same thing, ^ raises the left argument to the power of the right) Every operator must be surrounded by spaces. iSet forces all intermediate steps as well as the final result to integers, fSet uses 8 byte floats for intermediate steps and returns a 4 byte float as the result. To use negative numbers, skip the space between a '-' and a number. Specify exponents by adding an E to the end of the number.
iSet also supports 'or', 'xor', 'and' binary operators and the 'not' unary operator.
fSet also supports 'sin', 'cos', 'tan', 'sinh', 'cosh', 'tanh', 'exp', 'log', 'ln' unary operators. (Trig functions use radians)
Operator precidence is brackets, unary operators, and, or, xor, mod, %, ^, /, *, +, -
Example
iSet result -1 + ( 5 mod 3 ) + ( 6 - 3 )
Message "%result%" ;Will print "4"
fSet result 1E+10 / 10
Message "%result%" ;Will print 1E+9
InputString <variable> [Title] [Initial]
Displays the text editor and requests input from the player. If the text editor is closed without saving, the variable is set to an empty string otherwise it is set to the contents of the text editor.
If title or Initial aren't specified, they are assumed to be empty strings.
ReadINI <variable> <section> <value>
ReadRendererInfo <variable> <value>
Use these to read a specific value from oblivion.ini or rendererinfo.txt into a variable. Use this to check which shader package is being used, what the resolution is set to and so on.
Example
ReadRendererInfo package "Shader Package"
SelectVar package
Case 8
Break
Default
Message "You must be using shader package 8" "Error"
FatalError
EndSelect
EditXMLLine <file> <line number> <new line>
EditXMLReplace <file> <text to find> <text to replace>
Use these to edit XML files contained within your omod. You cannot edit XML files from other mods with these functions.
EditXMLLine replaces an entire line within an xml file. EditXMLReplace will replace all intances of the specified text with the other.
ExecLines <lines>
Runs a string as if it were part of the script. Can be used with variables and loops to dynamically construct option menus.
You cannot use loops inside an ExecLines function, but Ifs and Selects are fine.
Example
SetVar select "SelectManyWithPreview \"Choose which optional texture replacers you'd like to install\" "
SetVar cases ""
For Each DataFolder fName "extras" False
SetVar select "%select% \"%fName%\" \"%fName%/preview.jpg\" "
SetVar cases "%cases%Case fName%NewLine%CopyDataFolder \"fName\" \"Textures\" True%NewLine%Break%NewLine%"
EndFor
ExecLines %select%%NewLine%%cases%%NewLine%EndSelect
AllowRunOnLines
Run-on line support was added to obmm 0.9.26, but to preserve backwards compatability with older scripts this function must be called before it is enabled.
Example
Message foo \
bar
;This will display two message boxes. The first will have the text 'foo' and the title '\', the second will be an error stating that bar is not a recognised function.
AllowRunOnLines
Message foo \
bar
;This will display one message box with the text 'foo' and the title 'bar'.
