Class PapyrusScriptDispatcher

Namespace

SkyrimForge.Papyrus

Assembly

SkyrimForge.Game.dll

One script's name, bound so that a caller writes it once rather than at every call.

public sealed class PapyrusScriptDispatcher

Inheritance

object

PapyrusScriptDispatcher

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

A call that names a script or a function the Papyrus virtual machine cannot resolve dispatches nothing, and its task faults with InvalidOperationException. Construct one for a script with no generated binding: new PapyrusScriptDispatcher("MyQuestScript"). A string or an array read as a result or a property is never null. Papyrus has no None string, and a None array reads as one with no entries. Every task here completes from work queued on ITaskQueue, under the terms that interface documents.

Constructors

PapyrusScriptDispatcher(string)

Creates a dispatcher for the script scriptName names.

public PapyrusScriptDispatcher(string scriptName)

Parameters

scriptName string

The name Scriptname declares, which a dispatch passes.

Exceptions

ArgumentNullException

scriptName is null.

ArgumentException

scriptName is empty.

Properties

ScriptName

The script these calls name.

public string ScriptName { get; }

Property Value

string

Methods

Bind(IForm)

Binds an instance of this script to a form, doing nothing where one is bound already, so it is safe to call before every use.

public void Bind(IForm receiver)

Parameters

receiver IForm

Remarks

A function called on a form with nothing bound faults its task, so call this first for a script that may not be bound. Call on the game's thread.

An instance bound here starts at the defaults its script declares. A Creation Kit record supplies the values of an attached script's properties as data the game passes to its own initialization, and a bind made here has no such record, so a plugin needing values a record would have supplied writes them itself. The virtual machine still raises OnInit on the new instance, within a frame of the bind and with nothing dispatched to it, so a script sets itself up there as an attached one does.

The game writes the binding into the save along with the values of the instance's properties, and a load restores both, in a new process as well. A call after a load therefore finds the same instance rather than making a second. The script has to stay installed for as long as those saves are played: a save written with an instance bound names that script, which the virtual machine reads from the compiled .pex.

Exceptions

ArgumentNullException

receiver is null.

InvalidOperationException

Nothing was bound.

CallAsync(IForm, string, PapyrusArguments?)

Calls a function whose return value is of no interest.

public Task CallAsync(IForm receiver, string functionName, PapyrusArguments? arguments = null)

Parameters

receiver IForm

functionName string

arguments PapyrusArguments

Returns

Task

Exceptions

InvalidOperationException

No Papyrus virtual machine exists, the script or the function does not exist, the arguments do not match the parameters the function declares, the Papyrus virtual machine has no handle for the form, the form has no instance of the script bound, which Bind(IForm) makes, or the Papyrus virtual machine returned false. Nothing is dispatched.

ArgumentNullException

receiver or functionName is null.

ArgumentException

functionName is empty.

CallAsync(string, PapyrusArguments?)

Calls a global function whose return value is of no interest.

public Task CallAsync(string functionName, PapyrusArguments? arguments = null)

Parameters

functionName string

arguments PapyrusArguments

Returns

Task

Exceptions

InvalidOperationException

No Papyrus virtual machine exists, the script or the function does not exist, the arguments do not match the parameters the function declares, or the Papyrus virtual machine returned false. Nothing is dispatched.

ArgumentNullException

functionName is null.

ArgumentException

functionName is empty.

CallAsync<TValue>(IForm, string, PapyrusArguments?)

Calls a function of this script on a form, reading the return value as TValue.

public Task<TValue?> CallAsync<TValue>(IForm receiver, string functionName, PapyrusArguments? arguments = null)

Parameters

receiver IForm

functionName string

arguments PapyrusArguments

Returns

Task<TValue>

A task with the return value. It faults where the value cannot be read as TValue, and is canceled where the call was destroyed without running.

Type Parameters

TValue

Exceptions

InvalidOperationException

No Papyrus virtual machine exists, the script or the function does not exist, the arguments do not match the parameters the function declares, the Papyrus virtual machine has no handle for the form, the form has no instance of the script bound, which Bind(IForm) makes, or the Papyrus virtual machine returned false. Nothing is dispatched.

ArgumentNullException

receiver or functionName is null.

ArgumentException

functionName is empty.

CallAsync<TValue>(string, PapyrusArguments?)

Calls a global (static) function of this script.

public Task<TValue?> CallAsync<TValue>(string functionName, PapyrusArguments? arguments = null)

Parameters

functionName string

arguments PapyrusArguments

Returns

Task<TValue>

A task with the return value. It faults where the value cannot be read as TValue, and is canceled where the call was destroyed without running.

Type Parameters

TValue

Exceptions

InvalidOperationException

No Papyrus virtual machine exists, the script or the function does not exist, the arguments do not match the parameters the function declares, or the Papyrus virtual machine returned false. Nothing is dispatched.

ArgumentNullException

functionName is null.

ArgumentException

functionName is empty.

CallGetterAsync<TValue>(IForm, string)

Runs a property's getter, the only route to a full property, whose get is a Papyrus function rather than a stored variable.

public Task<TValue?> CallGetterAsync<TValue>(IForm receiver, string propertyName)

Parameters

receiver IForm

propertyName string

Returns

Task<TValue>

Type Parameters

TValue

Remarks

Named Call because it is one, run a frame or two later, unlike reading an Auto property.

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The getter could not be called.

CallSetter(IForm, string, Action<Variable>)

Runs a property's setter, the only route to writing a full property, whose set is a Papyrus function rather than a stored variable.

public void CallSetter(IForm receiver, string propertyName, Action<Variable> setPropertyValue)

Parameters

receiver IForm

propertyName string

setPropertyValue Action<Variable>

Remarks

Nothing to await: a setter produces no value, so this returns once the write is accepted and it runs a frame or two later.

Exceptions

ArgumentNullException

receiver, propertyName, or setPropertyValue is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The setter could not be called.

CallSetterArray<T>(IForm, string, IReadOnlyCollection<T>?, Action<Variable, T>)

Runs a full property's setter with an array, allocated against the type the property declares. Null writes None.

public void CallSetterArray<T>(IForm receiver, string propertyName, IReadOnlyCollection<T>? values, Action<Variable, T> setEntry)

Parameters

receiver IForm

propertyName string

values IReadOnlyCollection<T>

setEntry Action<Variable, T>

Type Parameters

T

Exceptions

ArgumentNullException

receiver, propertyName, or setEntry is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The write could not be made, or the property is not an array.

CallSetterForm(IForm, string, IForm?)

Runs a full property's setter with a form, which CallSetter(IForm, string, Action<Variable>) cannot write. Null writes None.

public void CallSetterForm(IForm receiver, string propertyName, IForm? value)

Parameters

receiver IForm

propertyName string

value IForm

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The write could not be made, or the property is not a lone form.

CallSetterFormArray<TForm>(IForm, string, IReadOnlyCollection<TForm>?)

Runs a full property's setter with an array of forms. Null writes None.

public void CallSetterFormArray<TForm>(IForm receiver, string propertyName, IReadOnlyCollection<TForm>? forms) where TForm : IForm

Parameters

receiver IForm

propertyName string

forms IReadOnlyCollection<TForm>

Type Parameters

TForm

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The same as CallSetterArray<T>(IForm, string, IReadOnlyCollection<T>?, Action<Variable, T>).

GetProperty<TValue>(IForm, string)

Reads an Auto property of this script from a form, for one with no generated binding.

public TValue? GetProperty<TValue>(IForm receiver, string propertyName)

Parameters

receiver IForm

propertyName string

Returns

TValue

Type Parameters

TValue

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The property could not be read. A full property is read through CallGetterAsync<TValue>(IForm, string).

SetProperty(IForm, string, Action<Variable>)

Writes an Auto property of this script on a form. setPropertyValue receives the property's variable and writes the value.

public void SetProperty(IForm receiver, string propertyName, Action<Variable> setPropertyValue)

Parameters

receiver IForm

propertyName string

setPropertyValue Action<Variable>

Remarks

A full property is written through CallSetter(IForm, string, Action<Variable>). Call on the game's thread.

Exceptions

ArgumentNullException

receiver, propertyName, or setPropertyValue is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The property could not be written.

SetPropertyArray<T>(IForm, string, IReadOnlyCollection<T>?, Action<Variable, T>)

Writes an array into a property declared as one, allocating it and setting each entry through setEntry. Null writes None.

public void SetPropertyArray<T>(IForm receiver, string propertyName, IReadOnlyCollection<T>? values, Action<Variable, T> setEntry)

Parameters

receiver IForm

propertyName string

values IReadOnlyCollection<T>

setEntry Action<Variable, T>

Type Parameters

T

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

receiver, propertyName, or setEntry is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The property could not be written.

SetPropertyForm(IForm, string, IForm?)

Writes a form into a property declared as a form, which SetProperty(IForm, string, Action<Variable>) cannot write. Null writes None.

public void SetPropertyForm(IForm receiver, string propertyName, IForm? value)

Parameters

receiver IForm

propertyName string

value IForm

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The property could not be written.

SetPropertyFormArray<TForm>(IForm, string, IReadOnlyCollection<TForm>?)

Writes an array of forms into a property declared as one. Null writes None.

public void SetPropertyFormArray<TForm>(IForm receiver, string propertyName, IReadOnlyCollection<TForm>? forms) where TForm : IForm

Parameters

receiver IForm

propertyName string

forms IReadOnlyCollection<TForm>

Type Parameters

TForm

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

receiver or propertyName is null.

ArgumentException

propertyName is empty.

InvalidOperationException

The property could not be written.