Mod:Creation Kit/Custom Papyrus Events

Custom events allow any script in the game to send an event which any number of scripts can then receive. The receivers have to register with the sender, but the sender doesn't have to know about the receivers or manage them in any way. One way this could be used would be having an actor register to receive an event from a controlling script whenever it enters a location, and unregister when they leave. Then the controller script could send the event, and all actors in that location that register would get it without having to maintain any complicated list or setting up a bunch of aliases.

=How to Register= Registration is easy, just use the RegisterForCustomEvent function. Pass it the object you want to receive events from, and the name of the event you want to receive. Then, until you unregister (or are unregistered by the game) your specially-defined custom event will be triggered whenever source sends the event. Note that you must pass the event name to the function as a raw string, and cannot pass it a variable.

Examples
=How to Unregister= To stop receiving events, use the UnregisterForCustomEvent function. You will then no longer receive the specified event from the specified source object. You will be unregistered automatically if you are on an active magic effect which is removed, or are on a quest or alias when the quest restarts. Like the register call, you must pass the event name to the function as a raw string, and cannot pass it a variable.

Examples
=How to Handle the Event= To handle the event, you'll need to define the event in your script in a special form. The event you define must have a name that consists of the script that the event comes from, followed by a dot, then followed by the name of the event itself. The two parameters the event receives are one of the same type as the script the event comes from, which will contain the event's sender, and a var array which will contain any parameters.

Note that the type used in the event name and in the first parameter of the event must contain the custom event definition.

In most cases, the compiler should catch any errors in the definition and give you a bit of advice on fixing the issue.

Examples
=How to Define a Custom Event= In order for your script to send a custom event, it must define it. This is done similarly to a variable, but using "CustomEvent" rather then the variable type. You cannot name an event the same name as another function or event in your script or your parent script.

Examples
=How to Send a Custom Event= To send a custom event, use the SendCustomEvent function. The two parameters are the raw string of the event to send (you cannot pass it a string variable) and an optional array of parameters. The compiler will make sure the event is defined in your own script, or in a parent script. The function will then return immediately and not wait for any scripts handling the event (if any) to finish. The sender given to the scripts that are listening is the object the SendCustomEvent function is called on, even if it's called from another script.

Examples
=Additional Notes=
 * You cannot call the custom events directly in script. If you want the functionality to be shared, you should probably look at encapsulating the functionality in a separate function, which the custom event then calls.

=See Also=
 * RegisterForCustomEvent - ScriptObject
 * SendCustomEvent - ScriptObject
 * UnregisterForCustomEvent - ScriptObject
 * Events Reference