Mod:Creation Kit/Threading Notes (Papyrus)

Papyrus is a threaded scripting language. In essence, this means that the game can run multiple scripts in parallel. This allows the Creation Engine to manage script processing more effectively. Papyrus scripters should have at least a cursory understanding of the ramifications this creates for them.

This article attempts to explain threads in layman's terms, in the context of scripting for Papyrus.

Threading
The basic gist is this: Only one thing at a time can be doing anything with a script. If multiple things (threads) try to manipulate the script at the same time, a "queue" forms of all the threads which essentially wait in line for the script to stop doing something, then it lets the next thread in line in.

If the script calls another function in an external script, or calls a "latent" function (a function that does something on it's own before returning), it lets in the next thing from the cue while the other thread is off doing that other thing. Then while the new thread is occupying the script, when the previous thread that was off doing it's thing wants to come back and continue processing, now it has to wait in line until the new thread is done with the script (or it calls a latent function or function on another script)

Example
ObjectA has script with a function called.

ObjectB calls  at the exact same time ObjectC calls

First ObjectB finishes running ObjectA's  and then ObjectC runs it.

Then first ObjectB calls, and while ObjectA is busy calling   for ObjectB, ObjectC waits in line, not yet processing ObjectA's.

But as soon as ObjectB's thread calls  because it has called a function on a different script/object, ObjectA waves in ObjectC who was waiting patiently to call.

Now while ObjectC's thread is processing , ObjectB's thread is done with   on ObjectD, but before it runs   it now must wait in line until ObjectC's done with   and itself moves out to ObjectD's. As soon as ObjectC's thread heads out to  in ObjectD, ObjectA waves in ObjectB's thread who is returning from ObjectD's   and will now be allowed to continue on with  ... and so on...

Scriptname ScriptA extends ObjectReference {Attached to object A}

ScriptD Property ObjectD Auto Const Mandatory

Function DoSomething SomeThing1 ;another function in ObjectA ObjectD.DoSomethingElse ;a function in a script on ObjectD Something2 ;Another function in ObjectA EndFunction

Function SomeThing1 ; some things EndFunction

Function SomeThing2 ; some things EndFunction Scriptname ScriptB extends ObjectReference {Attached to object B}

ScriptA Property ObjectA Auto Const Mandatory

Event OnActivate(ObjectReference akActionRef) ObjectA.DoSomething EndEvent Scriptname ScriptC extends ObjectReference {Attached to object C}

ScriptA Property ObjectA Auto Const Mandatory

Event OnActivate(ObjectReference akActionRef) ObjectA.DoSomething EndEvent Scriptname ScriptD extends ObjectReference {Attached to object D}

ScriptA Property ObjectA Auto Const Mandatory

Event OnActivate(ObjectReference akActionRef) ObjectA.DoSomething EndEvent

Function DoSomethingElse ; something else EndFunction

A Basic Example
In the image below, the player is activating a lever. Because this a nice and cooperative player, he's only activated it once. The game sends Papyrus a notification of the activate event. Because our script contains an onActivate Event, the game creates a "Thread", which you can think of as a set of instructions copied from our script. The game queues this thread up, and will process it momentarily.

Very soon - probably on the next frame - the game processes the thread. Let's pretend that the contents of our onActivate event look like this:

EVENT onActivate wait(5.0) player.additem(gold001, 10) endEVENT
 * Note - this is a non-functional snippet

The player activates the switch, which notifies Papyrus to create a thread containing those instructions - After five seconds, ten gold pieces are added to the player inventory. All is well. What happens with a less cooperative player, though?

Here the player has activated the lever several times in a short period of time. That's valid input, and our script is about to receive it. In comes the first activate event - thread is created and begins processing. Here comes the second activation - and another thread is created shortly after the first. This continues as long as the player spams activations on the lever.

The trouble comes with the time-sensitive nature of our script and threads in general. Thread #1 knows nothing about Thread #2 and so on, so each one will wait for five seconds, then add gold to the player.

This can get messy fast. We need a way to keep things organized.

The above example represents the script as we'd want to re-write it - blocking further activations after the first. There are several ways to get this result. This example will be solved using States.

States are very useful for creating a script that reacts to events differently based on different circumstances. The pseudo-script example below shows an example. STATE readyState EVENT onActivate gotoState("emptySTATE") wait(5.0) player.additem(gold001, 10) ; want to allow subsequent activatiosn after the 5 sec delay? add a "gotoState("readyState") here.   endEVENT endSTATE
 * Note - this is a non-functional snippet

STATE emptySTATE ; This state contains no events ; Note that other scripts attached to this reference will still process their activate events endSTATE

Note about tracing "GoToState"
In the previous example, take note of where goToState is called. Why? Because setValue is in an external script, it creates an opportunity for another thread to start processing your script before you go to the state you expect it to be in. Therefore, go to your desired state first. Your thread will complete the instructions below the gotoState call just fine, and future threads will treat the script as being in the state - "XYZ" in the example below - when they encounter it.

In other words - Don't do this: gigawatts.setValue(1.21) GoToState("XYZ") Instead, do this: GoToState("XYZ") gigawatts.setValue(1.21)

Another example
From an email to User:JBurgessasking if calling IncrementMyProperty from an external script multiple times in a row was "thread safe."

...assuming that all functions and the property itself are in the same script.

Function IncrementMyProperty myProperty += 1 endFunction

100% “thread safe”. myProperty will correctly increment. Right now it resolves to two function calls and as far as you should ever know, will always resolve that way.

Function IncrementMyProperty myProperty += 1 if myProperty == 5 ;do something endif endFunction

myProperty is guaranteed to be 5 when “do something” executes. If “do something” goes latent, or calls a function outside your script or its parents, myProperty may change.

Function IncrementMyProperty myProperty += 1 if myProperty == 5 myQuest.setStage(10) endif endFunction

;Elsewhere In MyQuest’s stage 10 fragment: If myProperty == 5 ;do something endif

SetStage is Latent, therefore myPropery may change, even if you just use “SetStage(10)” and your script extends Quest and is attached to the quest.

In the case of the fragment – it is entirely likely that myProperty will no longer equal 5 by the time the fragment runs. Remember: you called setStage, NOT a function. Fragments execute “some time in the future” (which happens to be very soon in most cases). This is one case where a function call is much more useful than a fragment.

Please note: If myProperty is NOT in your local script, then “myProperty += 1” may not increment. This is because it resolves to “myProperty.set(myProperty.get + 1)”, and myProperty’s value may change between the get and set calls since it isn’t on your own script. [Editor's note: Which is why you would write a IncrementMyProperty function in that other script -- JPD ]

-User:JBurgess