Scripting Tutorial Using Functions

Using Functions

Functions are an integral part of the new scripting language. We are able to use them as well as create them, and this can go a long way when it comes to writing scripts that are easy to read as well as fast to write.
Functions are very handy. They help to prevent having to copy/paste the same (or very similar) piece of script in many places. It also helps organize your logic. If you write a function, it should essentially do a single, useful action. The function name should also give some hint as to what it does.

Declaring Functions

Local Functions

You can declare functions locally. That means that these functions live inside of one particular script, and can only be run if you have a specific script to run the function in.

 ;inside some script...
 float value = 3.0
 
 Function ModifyValue(float valueModifier)
    value = (value + 2.0) * valueModifier
 EndFunction
 
 Event OnActivate(ObjectReference actionRef)
    ModifyValue(5.0)
 EndEvent

There are a few things going on here:

• Function - this is called to start a function declaration
• ModifyValue - this is the name of the function that you're making
• float valueModifier - here you are declaring a parameter. In this case, it means that you can pass a float in as a parameter for the function. Inside the function, you can use the variable "valueModifier" and that will be whatever number that gets passed into the function.
• value = (value + 2.0) * valueModifier - this is some logic inside the function. You could put any logic in here that you want. As you see, I'm using "valueModifier" like it's a variable. We don't know what the value of this variable is, however, as anything could be passed in.
• EndFunction - This ends the function declaration.

With a local function, you would have to actually have a scripted object in the world in order to use the function. This particular script has a variable called "value" in it, and if you're inside the script you can call ModifyValue() to change "value" to a different number. A different script can also call ModifyValue() on this script as well, and it would actually change the number stored in "value". A different script could use this script's function.

In this example, "value" would get set to 25.0 when you activate the scripted object for the first time.

Global Functions

If you want to make some basic functions that everyone can use, and you don't want to have to have a scripted object in the world in order to use the function, you could make a Global Function. This function can be found in Custom.psc:

 ;This function returns the Nth objectReference in a linked ref chain.
 ;The root link in the chain is 1
 objectReference Function goToLink(int linkNum, objectReference startRef ) global
     int linkIndex = 1
     while(linkNum != linkIndex ) 
         linkIndex = linkIndex + 1
         objectReference nextRef = startRef.getLinkedRef()
         if nextRef     ;make sure that nextRef isn't "None" (i.e. the ref actually has a linked ref)
             startRef = nextRef
         else
             debug.trace( "Tried to access None link in custom.GoToLink()" )
         endif
     endWhile
     return startRef
 endFunction

So there are some more things going on here. This function starts at a ref in the world (the startRef parameter) and then counts through a chain of linked refs. How many linked refs should it cycle through before the function is done? Whatever value gets passed into the "linkNum" variable, it will try to count through that many linked refs. Then it will say that it's done, and will spit out that reference of the linkedRef chain. If you were to use this function, you could write something like this:

 objectReference LinkInChain    ;makes a new objectReference (like a ref in the old scripting language) called LinkInChain
 
 LinkInChain = goToLink( 3, someRefInTheWorld)

This will start at some reference in the world (set up somewhere else in the script as to exactly what ref that is) and go to the third linked ref in the chain. Then you can set whatever reference the function found, and it places that in the LinkInChain variable.
You'll notice that the function declaration starts with "objectReference Function" instead of just "Function." This is because we want the function to return an objectReference so that we can know what the function found and place it in a variable.

Native Functions

Native functions are defined in code. In the old scripting language, every function was defined in code so there wasn't a need for distinction.
Here is an example of a native function being declared in the Debug.psc script:

 ; Outputs the string to the VS debugger
 Function Trace(string asTextToPrint) native global

Now, there are some keywords in here that we should go over.