Help:Function syntax

A major part of this Wiki is documenting the use and details of the myriad functions used by Oblivion Script. In order to do so, there is a separate page for every function, and these pages (mostly) follow a standardized scheme, described here.

Source

Many function pages start by stating where the script function comes from; this is done to differentiate between functions that were added in later versions of the Construction Set, as well as the functions from the Oblivion Script Extender. If a page does not mention its source, the function is almost certainly from the original version of the CS, and therefore available to all modders. Note that if a function is from some other source and does not mention it, this is an error; you can help to improve the Wiki by adding a mention of this fact.

Syntax

The most important part of the page in many cases, the Syntax section shows the proper form that a function is to be used in a script. This follows a standardized format in most cases:

(return value:return type) referenceType.FunctionName arg1:type arg2:type
(return value:return type) referenceType.Alias arg1:type arg2:type

Return Value

The first part of this format details what the function returns; this value may be stored in an appropriate variable or used as a condition in an if statement or similar. If the function does not return any value, (void) is used; otherwise, the return value is split into two halves, separated by a colon (:). The first half is what the value signifies (often a game statistic, sometimes other things), while the second half is the type of the value:

short for integers
float for numbers that may include decimals
string for text (Oblivion did not originally return strings, having no string variable type, but several functions use arguments of this type. OBSE adds a string type as well as functions that return strings.
bool for true/false values — note that Oblivion does not support specific bool variables, but rather just uses any numerical type (usually a short) for these: if the value is true, the number will be non-zero (usually but not necessarily 1), while if the value is false, the number will be zero.
ref for formIDs (stored in a ref variable)

In addition, OBSE adds some other types.

Reference

Next comes the reference. section. This is not found in all function pages, only those that may be used with the dot syntax to set the function to be run on the specified reference.

This section is italicized if the reference is optional. However, this indicates whether or not the function requires a reference, which is not the same as whether or not you must use the reference. syntax. This is because many scripts (such as Object scripts in certain cases, or all Magic scripts) have a default reference which is used if none is supplied through the reference. syntax. However, if a function requires a reference (it is not italicized in the syntax description), then you must always use one in a Quest script (as they do not have default references). If it is italicized, then it is completely optional and you need not include it even in a Quest script (though you may need to in order to get it to do what you want).

Reference or Object

Of special interest is a rather-common scheme used by OBSE:

(return) reference.FunctionName ... baseObject:ref

where the baseObject:ref is the last argument (see Arguments, below). In this case, the function takes either a reference or a base object; if you use a reference, the function will find and operate on the reference's base object, but otherwise it will just change the base object. Functions that change the base object will change every reference to that object. See also Modding Terminology.

Function Name and Aliases

This is followed by the function's name. This is not case-sensitive; functions on the Wiki generally use CamelCase to make it easier to read, but the CS does not have any requirements. It is important to make sure that you have spelled the function correctly.

Note that sometimes a function's syntax section has two entries, one after the other, with the same return value and arguments: the second one is the function's "alias". An alias is alternative, often shorter form of the function; for example, SetActorValue and SetAV are the exact same function, just aliases of one another. SetAV is shorter to type; SetActorValue is easier to remember and read — which you would like to use is your own preference.

Arguments

Finally, following that are the function's "arguments" — the values actually given to the function that it uses to produce its result. These use the same format as the return value: the argument's purpose followed by the argument's type, separated by a colon. Arguments may either be literals (e.g. the number 4) or variables (e.g. the short variable shortVar). The order of the arguments and their types are very important: if you use the wrong order or try to pass arguments of the wrong types, the script may not compile or will cause errors if it does.

If the argument is italicized, then it is optional: you may omit it if you like. Note that in order to use a given optional argument, you must also use all of the preceding arguments, as well. You cannot "skip" optional arguments, you can only stop and omit all following arguments, or continue and give each argument in the described order.

Summary

This section describes what the function does, in some cases in great detail. At the very least, a function should describe exactly what each of the function's arguments do (including the default values of any optional arguments), what you can expect the return value to be in various situations, and any side-effects that running the function may cause (such as changing in-game statistics, moving objects, etc.).

Example

The next part of a function's description may be an example, a small snippet of code showing the function being used in a real or at least realistic setting, rather than the pseudo-code of the syntax description. This example can range from the quite complex to being completely absent, depending on the complexity of using the function in question. A few functions actually have entire, separate tutorials dedicated to the nuances of their use!

Notes

This section lists details, warnings, and caveats to using the function. These are often very important, so make sure you read them!