View source for User:Haama/FAR

A Functional Activator Script is a type of global script that uses [[Activate]] to mimic common programming [http://en.wikipedia.org/wiki/Function_(computer_science) functions]. Like functions, they can:
#Be called from another script at any time
#Will happen immediately, before the next line of code is processed
#Can be nested (though note the limitation below)
#Take input parameters and can return output parameters
#Make your code easier to read and write
#Centralize sections of your code

==Why you would want to use FASs==
...

==Background==


----

==Background==
FASs rely on some particular oddities of [[Activate]] to mimic function behavior.

'''Activate''' can be used to run another script instantly. This activated script would be the function: it runs separately from the calling script, it uses its own variables, etc.

While FASs behave like functions their set up is a bit different, but in the end roughly equivalent. In most programming languages, you would simply write the function code, give it a name, and call it with the function's name. However, you're not able to simply call a script in Oblivion.

Instead, '''Activate''' is used to call upon a [[Reference|reference]]. When you use the ''RunOnActivate'' flag of '''Activate''', it runs the reference's script. To draw the parallels with common programming functions, '''Activate''' is used to call the function. Whereas most functions would have the name as part of the code, here the reference is the name of the function and the script is the code.

To give an example, in C++ programming you would use this line
<pre></pre>
to call
<pre>UInt32 CreateString(const char* strVal, void* owningScript)
{
	Script* script = (Script*)owningScript;
	if (script)
		return g_StringMap.Add(script->GetModIndex(), strVal);
	else
		return 0;
}</pre>
In Oblivion, we would use this line
<pre>CreateString.Activate AnotherRef(SeeBelow), 1</pre>
to call this script
<pre>scn CreateStringFAS ;Notice it doesn't have the same name as the reference

begin onActivate
    set rScript to OwningScript
    if rScript
        set Output to ModIndex
    else
        set Output to 0
    endif
end</pre>





To draw the parallels with common programming functions
*'''Activate''' calls the function
*

The easy parallel here is that '''Activate''' calls the function, the reference is the function's name and the script is the function's code.

----

The script is really what defines the function, what it will do, and does the work. 

There are 2 important ideas to know about '''Activate''': it acts upon a reference object, and it can run that reference's script instantly.

there are 3 important parts here - the Activate call, the script, and the reference stuff (or hoops/hacks)

----
==In which Bethesda makes things harder (or you realize this is a bit of a hack)==
The script is really what defines the function, what it will do, and does the work. However, you're not able to simply call a script in Oblivion... like quests, added items have to use a function... here we use Activate, and so we need to have a reference to actually Activate...

Functional Activator Scripts rely on some particular oddities of the [[Activate]] function. When you use the '''onActivate''' flag of the '''Activate''' function, it will instantly run the Activated reference's script. 

You have to call a specific reference. there are a few steps you need to go through to set up each Functional Activator.
#Before you make any Functional Activator you'll want to create an [[Creating_a_New_Cell|empty cell]]. You'll use this cell to hold all of the activators.
#Each Functional Activators require 3 parts: the script, the [[Creating_a_New_Base_Object|base activator]], and the [[Creating_a_New_Persistent_Reference|persistent reference activator]]. The script is the fundamental definition of the Functional Activator and is discussed
<ol><li>The script needs an onActivate block and will generally look like</li>
<pre>scn ScriptNameFAS ;FAS for Functional Activator Script, not necessary but helpful to keep scripts organized

begin onActivate
;function code
end</pre>
<li>Base Activator - it can be any object, but activators
...
empty cell, disable, persistent
...
can be any object, but activators are best

----

General description

What they're useful for
*Centralize code
*Simplify code - can put complex if tests in separate FAR

Maybe go in order from least to most complex
*onActivate only
*Inputs/Outputs/Variables
*Heart-beat

Limitations
*Only 4 within each other
*Careful with Labels/loops
*Will take more processing due to more set/if statements, but those take 1000s to become a problem
*Probably not a good idea to trust between save/load

Preference over other script types (should really be on Global page)
*Compared to quest scripts
**Run instantly
***No need to handle timing issues and flags
***Quest scripts may be more reliable for long-term scripts
*Compared to result scripts
**Longer
**Can store variables, use ref variables in functions
**However, result scripts can have an infinite nest depth
*Compared to token
**Store the information
**Tokens better at keeping information for each actor, etc.