User:Haama/FAR

A Functional Activator Script is a type of global script that uses Activate to mimic common programming functions. Like functions, they can:

1. Be called from another script at any time
2. Will happen immediately, before the next line of code is processed
3. Can be nested (though note the limitation below)
4. Take input parameters and can return output parameters
5. Make your code easier to read and write
6. Centralize sections of your code

Background

Most of the time, when you "start" up a script in Oblivion it won't run until later that frame or the next frame (i.e., AddItem, StartQuest). However, the Activate function will run a script instantly, before the next line of code... explain the line of code bit... explain the independent variables bit... maybe mention result scripts...

Setup

give each step concisely... maybe give a technical reason for each... break down how the player will use the functions - that Activate is the call, the script the code and the reference the name

...

Heartbeat

use ToggleMenu as the example

---

Why you would want to use FASs

...

Background

FASs rely on some particular oddities of Activate to mimic function behavior... so yes they are a hack and their parallels with functions may not be readily obvious (especailly in terms of setup)

---

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. 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

to call

UInt32 CreateString(const char* strVal, void* owningScript)
{
	Script* script = (Script*)owningScript;
	if (script)
		return g_StringMap.Add(script->GetModIndex(), strVal);
	else
		return 0;
}

In Oblivion, we would use this line

CreateString.Activate AnotherRef(SeeBelow), 1

to call this script

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

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.

1. Before you make any Functional Activator you'll want to create an empty cell. You'll use this cell to hold all of the activators.
2. Each Functional Activators require 3 parts: the script, the base activator, and the persistent reference activator. The script is the fundamental definition of the Functional Activator and is discussed

1. The script needs an onActivate block and will generally look like

scn ScriptNameFAS ;FAS for Functional Activator Script, not necessary but helpful to keep scripts organized

begin onActivate
;function code
end

2. 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.