Table of Contents

Interface IPapyrusFunctionRegistrar

Namespace
SkyrimForge.Papyrus
Assembly
SkyrimForge.Game.dll

Provides a C# implementation for a native Papyrus function, so scripts can call into a plugin.

public interface IPapyrusFunctionRegistrar
Extension Methods

Remarks

The script side is ordinary Papyrus and is not generated by this, as it is for a class marked PapyrusScriptAttribute. A plugin ships a compiled script declaring its functions as native:

Scriptname MyPlugin Hidden

int Function Add(int first, int second) global native

Register from OnDataLoaded, which arrives once the Papyrus virtual machine exists. Registering during Start(), when the virtual machine does not exist, throws InvalidOperationException.

Registering loads the script where the game has not, and throws InvalidOperationException where no script call would reach the function: the script does not exist, declares no function of the name, or declares the function with other types, in which case the message names both declarations. Papyrus would otherwise leave such a function unbound, and a call to it would return a default value without running the C#. Registering a function a second time, by this plugin or another, also throws, and the earlier registration stays bound.

Each call a script makes to a native registered here takes one frame.

Methods

RegisterInstance(string, FormType, PapyrusType, string, IReadOnlyCollection<PapyrusType>, Action<PapyrusCall>)

Registers an implementation for a native function a script declares without global, which a caller reaches through an instance of the script rather than through the class. The absence of global makes it one:

int Function Rename(string called) native

The receiver arrives as Self, and Bind(IForm) puts an instance on a form.

void RegisterInstance(string selfClassName, FormType selfType, PapyrusType returnType, string functionName, IReadOnlyCollection<PapyrusType> parameterTypes, Action<PapyrusCall> body)

Parameters

selfClassName string

Script class declaring the function. The receiver is an instance of it.

selfType FormType

The form type the receiver resolves as, the type the script extends rather than the script itself. The two name the same object in the two type systems it belongs to, the script class in Papyrus's and the form type in the game's. Self reads None where it does not resolve.

returnType PapyrusType

None for a function with no return value.

functionName string

Function name as the script declares it.

parameterTypes IReadOnlyCollection<PapyrusType>

Declared parameter types, in order. Eleven maximum, the game's limit. The receiver is not among them and does not count against it.

body Action<PapyrusCall>

Invoked with the receiver, the arguments, and the variable for the return value. An exception it throws is written to the log of the plugin that registered it.

Exceptions

ArgumentNullException

selfClassName, functionName, parameterTypes, or body is null.

ArgumentException

selfClassName or functionName is empty.

InvalidOperationException

The function was not registered, or no script call would reach it. The message names the reason.

RegisterLatentInstance(string, FormType, PapyrusType, string, IReadOnlyCollection<PapyrusType>, Func<PapyrusCall, PapyrusLatentCall, bool>)

RegisterLatentStatic(string, PapyrusType, string, IReadOnlyCollection<PapyrusType>, Func<PapyrusCall, PapyrusLatentCall, bool>) for a native declared without global, reached through an instance rather than through the class.

void RegisterLatentInstance(string selfClassName, FormType selfType, PapyrusType returnType, string functionName, IReadOnlyCollection<PapyrusType> parameterTypes, Func<PapyrusCall, PapyrusLatentCall, bool> body)

Parameters

selfClassName string

Script class declaring the function, and the class of the receiver.

selfType FormType

The form type the receiver resolves as, the type the script extends rather than the script itself.

returnType PapyrusType

The type the script receives once the value arrives, or None for one that only makes it wait.

functionName string

Function name as the script declares it.

parameterTypes IReadOnlyCollection<PapyrusType>

Declared parameter types, in order. Eleven maximum, the game's limit.

body Func<PapyrusCall, PapyrusLatentCall, bool>
True where the work started and the script should wait. False, and a body that throws, gives the script None and lets it continue.

Remarks

A script declares a latent native exactly as it declares any other, so this method is where the difference is decided. The body must return quickly, since the game is stopped while it runs. Its value goes through PapyrusLatentCall, and each Return of PapyrusCall throws, the return variable stating the started flag here. A save taken while a script waits loads with that script still stopped, nothing writing the waiting stack into the co-save. A PapyrusLatentCall the plugin retains across that load resumes it.

Exceptions

ArgumentNullException

selfClassName, functionName, parameterTypes, or body is null.

ArgumentException

selfClassName or functionName is empty, or returnType is an array.

InvalidOperationException

The function was not registered, or no script call would reach it. The message names the reason.

RegisterLatentStatic(string, PapyrusType, string, IReadOnlyCollection<PapyrusType>, Func<PapyrusCall, PapyrusLatentCall, bool>)

Registers a global native that stops the calling script until the plugin returns a value.

void RegisterLatentStatic(string className, PapyrusType returnType, string functionName, IReadOnlyCollection<PapyrusType> parameterTypes, Func<PapyrusCall, PapyrusLatentCall, bool> body)

Parameters

className string

Script class declaring the function.

returnType PapyrusType

The type the script receives once the value arrives, or None for one that only makes it wait.

functionName string

Function name as the script declares it.

parameterTypes IReadOnlyCollection<PapyrusType>

Declared parameter types, in order. Eleven maximum, the game's limit.

body Func<PapyrusCall, PapyrusLatentCall, bool>

True where the work started and the script should wait. False, and a body that throws, gives the script None and lets it continue.

Remarks

A script declares a latent native exactly as it declares any other, so this method is where the difference is decided. The body must return quickly, since the game is stopped while it runs. Its value goes through PapyrusLatentCall, and each Return of PapyrusCall throws, the return variable stating the started flag here. A save taken while a script waits loads with that script still stopped, nothing writing the waiting stack into the co-save. A PapyrusLatentCall the plugin retains across that load resumes it.

Exceptions

ArgumentNullException

className, functionName, parameterTypes, or body is null.

ArgumentException

className or functionName is empty, or returnType is an array.

InvalidOperationException

The function was not registered, or no script call would reach it. The message names the reason.

RegisterStatic(string, PapyrusType, string, IReadOnlyCollection<PapyrusType>, Action<PapyrusCall>)

Registers an implementation for a native function the script declares global, which a caller reaches through the class.

void RegisterStatic(string className, PapyrusType returnType, string functionName, IReadOnlyCollection<PapyrusType> parameterTypes, Action<PapyrusCall> body)

Parameters

className string

Script class declaring the function.

returnType PapyrusType

None for a function with no return value.

functionName string

Function name as the script declares it.

parameterTypes IReadOnlyCollection<PapyrusType>

Declared parameter types, in order. Eleven maximum, the game's limit.

body Action<PapyrusCall>

Invoked with the arguments and the variable for the return value. An exception it throws is written to the log of the plugin that registered it.

Exceptions

ArgumentNullException

className, functionName, parameterTypes, or body is null.

ArgumentException

className or functionName is empty.

InvalidOperationException

The function was not registered, or no script call would reach it. The message names the reason.