Table of Contents

Class ObjectReferenceExtensions

Namespace
SkyrimForge.Game
Assembly
SkyrimForge.Game.dll

Provides extension members for IObjectReference.

public static class ObjectReferenceExtensions
Inheritance
ObjectReferenceExtensions
Inherited Members

Methods

ActivateRef<TReference, TActivator>(TReference, TActivator)

Activates the reference as activator, as ObjectReferenceScript.Activate does without the Papyrus VM.

public static bool ActivateRef<TReference, TActivator>(this TReference reference, TActivator activator) where TReference : notnull, IObjectReference where TActivator : notnull, IObjectReference

Parameters

reference TReference
activator TActivator

Returns

bool

Type Parameters

TReference
TActivator

Remarks

Call on the game's thread.

BlockActivation<TReference>(TReference, bool)

Blocks or unblocks activation of the reference, as Papyrus's BlockActivation does.

public static void BlockActivation<TReference>(this TReference reference, bool block = true) where TReference : notnull, IObjectReference

Parameters

reference TReference
block bool

Type Parameters

TReference

Remarks

Call on the game's thread.

CreateDetectionEvent<TReference, TOwner>(TReference, TOwner, int)

Creates a detection event at the reference for owner, as Papyrus's CreateDetectionEvent does.

public static void CreateDetectionEvent<TReference, TOwner>(this TReference reference, TOwner owner, int soundLevel = 0) where TReference : notnull, IObjectReference where TOwner : notnull, IActor

Parameters

reference TReference
owner TOwner
soundLevel int

Type Parameters

TReference
TOwner

Remarks

An owner without an AI process creates none. Call on the game's thread.

DisableAndDelete<TReference>(TReference)

Disables the reference and marks it deleted, as Papyrus's Disable and Delete do together.

public static void DisableAndDelete<TReference>(this TReference reference) where TReference : notnull, IObjectReference

Parameters

reference TReference

Type Parameters

TReference

Remarks

The form ID resolves until the game unloads the reference. A reference in an inventory stays in the inventory until removed from it. Call on the game's thread.

LayOnGround<TReference>(TReference, TES, NiPoint3, float, float)

Moves the reference to position, raised so the center of its bounds lies no lower than that position, and tilts it to the terrain across span, with the heading yaw given in degrees.

public static void LayOnGround<TReference>(this TReference reference, TES tes, NiPoint3 position, float yaw, float span) where TReference : notnull, IObjectReference

Parameters

reference TReference
tes TES
position NiPoint3
yaw float
span float

Type Parameters

TReference

Remarks

The height reads the render node once it has loaded and the base record's bounds before, so a second call after the node loads corrects it. The reference lies level on land that is not loaded. Call on the game's thread.

PlaceActor<TReference>(TReference, TESDataHandler, FormId<ActorBase>, NiPoint3, bool)

Creates an actor of the base with actorBaseId at position, as Papyrus's PlaceActorAtMe does at a marker there.

public static Actor PlaceActor<TReference>(this TReference reference, TESDataHandler dataHandler, FormId<ActorBase> actorBaseId, NiPoint3 position, bool persistent = false) where TReference : IObjectReference

Parameters

reference TReference
dataHandler TESDataHandler

The game's data handler.

actorBaseId FormId<ActorBase>

The actor base, which may be built on a template.

position NiPoint3

The position, in this reference's worldspace or, in an interior, its cell.

persistent bool

Whether the actor is persistent. The one Papyrus's PlaceActorAtMe creates is not.

Returns

Actor

The actor, with Actor's script bound. Its 3D loads afterwards where its cell is loaded, and WaitFor3DLoadAsync waits for it.

Type Parameters

TReference

Remarks

Call on the game's thread. Before the 3D loads, SetOutfit takes effect but EquipItem does not, so call EquipItem after WaitFor3DLoadAsync.

Exceptions

InvalidOperationException

No form has actorBaseId, the form is not an actor base, or the game created no marker or no actor.

PlaceNamed<TReference, TBase>(TReference, FormId<TBase>, string)

Creates a reference of the base object with baseObjectId, as the overload receiving the base object does.

public static ObjectReference PlaceNamed<TReference, TBase>(this TReference reference, FormId<TBase> baseObjectId, string name) where TReference : notnull, IObjectReference where TBase : struct, ITESBoundObject

Parameters

reference TReference
baseObjectId FormId<TBase>
name string

Returns

ObjectReference

Type Parameters

TReference
TBase

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

name is null.

ArgumentException

The base object is a leveled list, which Papyrus's PlaceAtMe resolves first.

InvalidOperationException

No form has baseObjectId, the form is not a TBase, or the game created no reference or did not name it.

PlaceNamed<TReference, TBase>(TReference, TBase, string)

Creates a reference of baseObject at this reference and names it name, as Papyrus's PlaceAtMe creates one.

public static ObjectReference PlaceNamed<TReference, TBase>(this TReference reference, TBase baseObject, string name) where TReference : notnull, IObjectReference where TBase : notnull, ITESBoundObject

Parameters

reference TReference
baseObject TBase
name string

Returns

ObjectReference

The reference, with ObjectReference's script bound. It is not persistent, where the one Place creates is.

Type Parameters

TReference
TBase

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

name is null.

ArgumentException

baseObject is a leveled list, which Papyrus's PlaceAtMe resolves first.

InvalidOperationException

The game created no reference or did not name it.

PlaceOnGround<TReference, TBase>(TReference, TES, TESDataHandler, FormId<TBase>, NiPoint3, float, float)

Creates a persistent reference of the base object with baseObjectId and lays it on the ground at position, with the heading yaw given in degrees, as LayOnGround does.

public static ObjectReference PlaceOnGround<TReference, TBase>(this TReference reference, TES tes, TESDataHandler dataHandler, FormId<TBase> baseObjectId, NiPoint3 position, float yaw, float span) where TReference : IObjectReference where TBase : struct, ITESBoundObject

Parameters

reference TReference
tes TES
dataHandler TESDataHandler
baseObjectId FormId<TBase>
position NiPoint3
yaw float
span float

Returns

ObjectReference

Type Parameters

TReference
TBase

Remarks

Call on the game's thread.

Exceptions

ArgumentException

The base object is a leveled list, which Papyrus's PlaceAtMe resolves first.

InvalidOperationException

No form has baseObjectId, the form is not a TBase, or the game created no reference.

PlacePackInAsync<TReference>(TReference, TES, TESDataHandler, IUtility, PackIn, NiPoint3, CancellationToken)

Disables the vegetation within DisabledVegetationRadius of origin, then lays each part of packIn on the ground at its offset from origin.

public static Task<IReadOnlyDictionary<PackInPart, ObjectReference>> PlacePackInAsync<TReference>(this TReference reference, TES tes, TESDataHandler dataHandler, IUtility utility, PackIn packIn, NiPoint3 origin, CancellationToken cancellationToken = default) where TReference : notnull, IObjectReference

Parameters

reference TReference
tes TES

The game's TES, through which the ground and the vegetation are read.

dataHandler TESDataHandler

The game's data handler.

utility IUtility

The service that waits one second before the parts are laid on the ground again.

packIn PackIn

The parts to place.

origin NiPoint3

The position the parts' offsets are measured from, in this reference's worldspace or, in an interior, its cell.

cancellationToken CancellationToken

Cancels the one-second wait before the parts are laid on the ground again. The parts are placed by then and remain, and the task ends canceled without returning them. A new game or a save load also cancels the wait.

Returns

Task<IReadOnlyDictionary<PackInPart, ObjectReference>>

The reference placed for each part, which excludes a part that MaximumTilt leaves out.

Type Parameters

TReference

Remarks

A part whose ground is not loaded is placed at the origin's height. The task completes a second later, once each part is laid on the ground again. FitsAt(TES, NiPoint3) tests whether every part is placed at an origin, and FindSite(TES, NiPoint3, float) searches for such an origin. Call on the game's thread.

Exceptions

ArgumentNullException

utility or packIn is null.

Place<TReference, TBase>(TReference, TESDataHandler, FormId<TBase>, NiPoint3, float)

Creates a persistent reference of the base object with baseObjectId, rotated yaw degrees about Z, as the overload receiving the base object does.

public static ObjectReference Place<TReference, TBase>(this TReference reference, TESDataHandler dataHandler, FormId<TBase> baseObjectId, NiPoint3 position, float yaw = 0) where TReference : IObjectReference where TBase : struct, ITESBoundObject

Parameters

reference TReference
dataHandler TESDataHandler
baseObjectId FormId<TBase>
position NiPoint3
yaw float

Returns

ObjectReference

Type Parameters

TReference
TBase

Remarks

Call on the game's thread.

Exceptions

ArgumentException

The base object is a leveled list, which Papyrus's PlaceAtMe resolves first.

InvalidOperationException

No form has baseObjectId, the form is not a TBase, or the game created no reference.

Place<TReference, TBase>(TReference, TESDataHandler, TBase, NiPoint3, float)

Creates a persistent reference of baseObject at position, rotated yaw degrees about Z.

public static ObjectReference Place<TReference, TBase>(this TReference reference, TESDataHandler dataHandler, TBase baseObject, NiPoint3 position, float yaw = 0) where TReference : notnull, IObjectReference where TBase : notnull, ITESBoundObject

Parameters

reference TReference
dataHandler TESDataHandler
baseObject TBase
position NiPoint3
yaw float

Returns

ObjectReference

The reference, with ObjectReference's script bound. Its 3D loads afterwards where its cell is loaded, and WaitFor3DLoadAsync waits for it.

Type Parameters

TReference
TBase

Remarks

position is in this reference's worldspace or, in an interior, its cell. Call on the game's thread.

Exceptions

ArgumentException

baseObject is a leveled list, which Papyrus's PlaceAtMe resolves first.

InvalidOperationException

The game created no reference.

PlayImpactEffect<TReference>(TReference, BGSImpactManager, ImpactDataSet, string, float, float, float, float, bool, bool)

Plays impactEffect at the reference, as Papyrus's PlayImpactEffect does.

public static bool PlayImpactEffect<TReference>(this TReference reference, BGSImpactManager impactManager, ImpactDataSet impactEffect, string nodeName = "", float pickDirectionX = 0, float pickDirectionY = 0, float pickDirectionZ = -1, float pickLength = 512, bool applyNodeRotation = false, bool useNodeLocalRotation = false) where TReference : notnull, IObjectReference

Parameters

reference TReference
impactManager BGSImpactManager

The game's impact manager.

impactEffect ImpactDataSet

The impact data set to play.

nodeName string

The node in the reference's 3D at which the effect plays.

pickDirectionX float

The X component of the direction of the ray the game casts to find a surface.

pickDirectionY float

The Y component of the direction of the ray the game casts to find a surface.

pickDirectionZ float

The Z component of the direction of the ray the game casts to find a surface.

pickLength float

The length of that ray.

applyNodeRotation bool

Whether the effect takes the node's rotation.

useNodeLocalRotation bool

Whether that rotation is the node's local rotation rather than its world rotation.

Returns

bool

Whether the game played the effect. False where the reference is in no cell or its cell has no physics world.

Type Parameters

TReference

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

nodeName is null.

PlaySoundFile<TReference>(TReference, TESDataHandler, BSAudioManager, string, float)

Plays the sound file at path from the reference, with a direction and fading with distance.

public static SoundInstance? PlaySoundFile<TReference>(this TReference reference, TESDataHandler dataHandler, BSAudioManager audioManager, string path, float range = 2000) where TReference : notnull, IObjectReference

Parameters

reference TReference
dataHandler TESDataHandler

The game's data handler.

audioManager BSAudioManager

The game's audio manager.

path string

The file's path under the game's Data folder, such as Sound\FX\MyMod\Chime.wav.

range float

The distance in game units past which the sound is silent. The game's sound output model whose range is nearest is used.

Returns

SoundInstance?

The playback, or null where the game did not start the sound.

Type Parameters

TReference

Remarks

A missing file is silent. Mono wave and xWMA files play. Call on the game's thread.

Exceptions

ArgumentNullException

path is null.

InvalidOperationException

The reference has no 3D, or the game declares no sound output model that fades with distance.

RemoveAllItems<TReference>(TReference, IObjectReference?, bool)

Removes every item from the reference's inventory, as Papyrus's RemoveAllItems does.

public static void RemoveAllItems<TReference>(this TReference reference, IObjectReference? transferTo = null, bool keepOwnership = false) where TReference : notnull, IObjectReference

Parameters

reference TReference
transferTo IObjectReference

The container the items move to, or null for none.

keepOwnership bool

Whether moved items retain the reference as their owner.

Type Parameters

TReference

Remarks

Papyrus's abRemoveQuestItems has no counterpart, since the game function it reaches has no such parameter. Call on the game's thread.

Exceptions

InvalidOperationException

The reference is the player, for whom Papyrus also runs a game function no binding reaches.

SendAnimationEvent<TReference>(TReference, string)

Sends the animation event eventName to the reference's animation graph, as Papyrus's Debug.SendAnimationEvent does.

public static void SendAnimationEvent<TReference>(this TReference reference, string eventName) where TReference : notnull, IObjectReference

Parameters

reference TReference
eventName string

Type Parameters

TReference

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

eventName is null.

SetAnimationVariableBool<TReference>(TReference, string, bool)

Sets the bool animation graph variable variableName to value, as Papyrus's SetAnimationVariableBool does.

public static bool SetAnimationVariableBool<TReference>(this TReference reference, string variableName, bool value) where TReference : notnull, IObjectReference

Parameters

reference TReference
variableName string
value bool

Returns

bool

The game's result, which is true even for a name the graph does not declare.

Type Parameters

TReference

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

variableName is null.

SetAnimationVariableFloat<TReference>(TReference, string, float)

Sets the float animation graph variable variableName to value, as Papyrus's SetAnimationVariableFloat does.

public static bool SetAnimationVariableFloat<TReference>(this TReference reference, string variableName, float value) where TReference : notnull, IObjectReference

Parameters

reference TReference
variableName string
value float

Returns

bool

The game's result, which is true even for a name the graph does not declare.

Type Parameters

TReference

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

variableName is null.

SetAnimationVariableInt<TReference>(TReference, string, int)

Sets the int animation graph variable variableName to value, as Papyrus's SetAnimationVariableInt does.

public static bool SetAnimationVariableInt<TReference>(this TReference reference, string variableName, int value) where TReference : notnull, IObjectReference

Parameters

reference TReference
variableName string
value int

Returns

bool

The game's result, which is true even for a name the graph does not declare.

Type Parameters

TReference

Remarks

Call on the game's thread.

Exceptions

ArgumentNullException

variableName is null.

WaitFor3DLoadAsync<TReference>(TReference, IUtility, TimeSpan, CancellationToken)

Waits until the reference's 3D loads, testing SkyrimForge.Game.ObjectReferenceBindings.Is3DLoaded<T>(T) once a frame.

public static Task WaitFor3DLoadAsync<TReference>(this TReference reference, IUtility utility, TimeSpan timeout, CancellationToken cancellationToken = default) where TReference : notnull, IObjectReference

Parameters

reference TReference
utility IUtility

The service that waits one frame between tests of the 3D.

timeout TimeSpan

The span of UnpausedTime after which the task faults if no 3D has loaded.

cancellationToken CancellationToken

Cancels the wait on the next frame. A new game or a save load also cancels the wait.

Returns

Task

Type Parameters

TReference

Remarks

The game loads a model on another thread, so the wait depends on the disk and on the models queued before it rather than on the frame rate. Measured on an NVMe disk, one model new to the session loaded in 4 to 50 milliseconds, and one queued behind 150 others in 1.1 seconds. Call on the game's thread.

Exceptions

ArgumentNullException

utility is null.

TimeoutException

The 3D did not load within timeout.

get_IsInInterior<TReference>(TReference)

Whether the reference is in an interior cell, as Papyrus's IsInInterior returns it.

public static bool get_IsInInterior<TReference>(TReference reference) where TReference : notnull, IObjectReference

Parameters

reference TReference

Returns

bool

Type Parameters

TReference

Remarks

False for a reference in no cell. Call on the game's thread.

get_Key<TReference>(TReference)

The key that opens the reference's lock, as Papyrus's GetKey returns it.

public static Key? get_Key<TReference>(TReference reference) where TReference : notnull, IObjectReference

Parameters

reference TReference

Returns

Key?

Type Parameters

TReference

Remarks

Null where the reference has no lock or its lock takes no key. Call on the game's thread.