Difference between revisions of "Help:Function syntax"
m
moved Function syntax to Help:Function syntax: it's a help page, belongs in the Help namespace.
imported>DragoonWraith (why didn't we create this page YEARS ago?) |
imported>DragoonWraith m (moved Function syntax to Help:Function syntax: it's a help page, belongs in the Help namespace.) |
||
| (10 intermediate revisions by the same user not shown) | |||
| Line 11: | Line 11: | ||
(return value:return type) referenceType.FunctionName arg1:type ''arg2:type'' | (return value:return type) referenceType.FunctionName arg1:type ''arg2:type'' | ||
(return value:return type) referenceType.Alias arg1:type ''arg2:type'' | |||
=== Return Value === | === Return Value === | ||
The first part of this format details what the function returns; this value may be stored in an appropriate [[:Category:Variables|variable]] or used as a condition in an <tt>if</tt> statement or similar. If the function does not return any value, <tt>(void)</tt> is used; otherwise, the return value is split into two halves, separated by a colon (<tt>:</tt>). 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: | The first part of this format details what the function returns; this value may be stored in an appropriate [[:Category:Variables|variable]] or used as a condition in an <tt>if</tt> statement or similar. If the function does not return any value, <tt>(nothing)</tt> or <tt>(void)</tt> is used; otherwise, the return value is split into two halves, separated by a colon (<tt>:</tt>). 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: | ||
* <tt>short</tt> for integers | * <tt>short</tt> for integers. | ||
* <tt>float</tt> for numbers that may include decimals | * <tt>float</tt> for numbers that may include decimals. | ||
* <tt>string</tt> for text | * <tt>string</tt> for text — note that Oblivion did not originally return strings, having no <tt>string</tt> variable type, but several functions use arguments of this type (see below). [[:Category:Oblivion Script Extender|OBSE]] adds a <tt>string</tt> variable type as well as functions that return strings. | ||
* <tt>bool</tt> for true/false values | * <tt>bool</tt> for true/false values — note that Oblivion does not support specific <tt>bool</tt> type variables, but rather just uses any numerical type (usually a <tt>short</tt>) for these: if the value is <tt>true</tt>, the number will be non-zero (usually but not necessarily <tt>1</tt>), while if the value is <tt>false</tt>, the number will be zero. | ||
* <tt>ref</tt> for formIDs | * <tt>ref</tt> for formIDs — these are stored in a [[Reference Variables|<tt>ref</tt> variable]]. | ||
In addition, [[:Category:Oblivion Script Extender|OBSE]] adds some other types. | In addition, [[:Category:Oblivion Script Extender|OBSE]] adds some other types. | ||
| Line 27: | Line 28: | ||
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 <tt>reference.</tt> 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 <tt>reference.</tt> 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). | 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 <tt>reference.</tt> 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 <tt>reference.</tt> 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 <tt>''baseObject:ref''</tt> is the last argument (see [[#Arguments|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 === | === Function Name and Aliases === | ||
| Line 39: | Line 46: | ||
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. | 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! | |||
== See Also == | |||
This section lists similar functions which may be relevant to someone using the given function. | |||
== Categories == | |||
Each function is categorized into one or more categories. These can allow you to find functions that deal with similar objects (such as actors or quest stages), limit the lists of functions that you're looking at to certain versions of the CS or with or without OBSE, etc. The categories at the bottom of the page can be extremely helpful in navigating the Wiki! | |||
[[Category:Scripting]] | [[Category:Scripting]] | ||