Table of Contents

Class QuestReferenceAlias

Namespace
SkyrimForge
Assembly
SkyrimForge.dll

A named placeholder for a reference, equivalent to a Creation Kit reference alias.

public sealed class QuestReferenceAlias : QuestAlias
Inheritance
QuestReferenceAlias
Inherited Members

Constructors

QuestReferenceAlias(string)

A named placeholder for a reference, equivalent to a Creation Kit reference alias.

public QuestReferenceAlias(string name)

Parameters

name string

The alias's name, unique among the quest's aliases of both kinds and the same in every version of the plugin. The saved state stores the reference under it.

Exceptions

ArgumentNullException

name is null.

Properties

ActorValues

The base value an actor filling the alias is given for each actor value, such as Aggression 0.

public IReadOnlyDictionary<ActorValue, float> ActorValues { get; init; }

Property Value

IReadOnlyDictionary<ActorValue, float>

Remarks

The value is set on the actor, not on its base. The actor's own base value is restored once it leaves the alias.

Exceptions

ArgumentNullException

The value is null.

DisplayName

The name a reference shows once it fills the alias. Null shows the reference's own name.

public string? DisplayName { get; init; }

Property Value

string

Remarks

The game saves the name with the reference, which retains it after the alias is cleared.

Exceptions

ArgumentNullException

name is null.

Events

The game's events about the reference that fills the alias.

public IQuestReferenceAliasEvents Events { get; }

Property Value

IQuestReferenceAliasEvents

Exceptions

InvalidOperationException

The alias belongs to no quest.

Factions

The rank an actor filling the alias is given in each faction. A null rank removes the actor from the faction.

public IReadOnlyDictionary<FormId<Faction>, sbyte?> Factions { get; init; }

Property Value

IReadOnlyDictionary<FormId<Faction>, sbyte?>

Remarks

The rank is set on the actor, not on its base. The actor's own rank is restored once it leaves the alias.

Exceptions

ArgumentNullException

The value is null.

IsEssential

Whether an actor filling the alias is essential, entering bleedout rather than dying.

public bool IsEssential { get; init; }

Property Value

bool

Remarks

The flag is set on the actor, not on its base, and reverts to the base's setting once the actor leaves the alias.

Exceptions

ArgumentNullException

name is null.

IsProtected

Whether an actor filling the alias is protected, dying only to the player.

public bool IsProtected { get; init; }

Property Value

bool

Remarks

The flag is set on the actor, not on its base, and reverts to the base's setting once the actor leaves the alias.

Exceptions

ArgumentNullException

name is null.

IsQuestObject

Whether an item filling the alias is a quest item, which the player cannot drop or sell.

public bool IsQuestObject { get; init; }

Property Value

bool

Remarks

The item is a quest item, on the ground and in an inventory alike, from the time the quest displays its first objective until the item leaves the alias, as every item does when RemoveFromJournalAndReset() runs. A save records it.

Exceptions

ArgumentNullException

name is null.

Player

The alias every quest fills with the player.

public static QuestReferenceAlias Player { get; }

Property Value

QuestReferenceAlias

Remarks

It belongs to no quest. Each member that acts on a quest throws, apart from ReferenceId.

Exceptions

ArgumentNullException

name is null.

ReferenceId

Gets the form ID of the reference that fills the alias. An empty alias returns null, and Player returns the form ID of the player's reference.

public FormId<ObjectReference>? ReferenceId { get; }

Property Value

FormId<ObjectReference>?

Exceptions

InvalidOperationException

The alias is not Player and belongs to no quest.

Methods

AddPackage(FormId<Package>, Func<Actor, bool>?)

Gives the actor filling the alias the AI package packageId while condition returns true.

public ISubscription AddPackage(FormId<Package> packageId, Func<Actor, bool>? condition = null)

Parameters

packageId FormId<Package>

The package, whose record names its targets.

condition Func<Actor, bool>

Returns whether the actor it receives runs the package. Null runs it whenever the alias is filled.

Returns

ISubscription

The registration, which Unsubscribe() removes.

Remarks

The packages added to one alias form a stack, evaluated on the game's thread each quarter second of unpaused time while the actor is loaded and alive. The actor runs the first added whose condition passes, ahead of its own packages, and returns to its own once none passes. A completed package remains the actor's package. The stack is not evaluated while the actor speaks in an open conversation, runs zzzDEFAULTzzzWaitForDialogue, or is an actor of a scene one of this plugin's quests plays. A condition that throws is logged and counts as failing, as does a package the game has no form for.

Exceptions

InvalidOperationException

The alias belongs to no quest.

AddPackage(LinkedRefPackage, Func<FormId<ObjectReference>?>, Func<Actor, bool>?)

Gives the actor filling the alias a package whose location or target is the actor's linked reference, and points that link at the reference getLinkedRefId returns.

public ISubscription AddPackage(LinkedRefPackage package, Func<FormId<ObjectReference>?> getLinkedRefId, Func<Actor, bool>? condition = null)

Parameters

package LinkedRefPackage

The package record and the keyword of its link, such as Sandbox or Sit.

getLinkedRefId Func<FormId<ObjectReference>?>

Returns the reference the link is set to. Null counts as the condition failing.

condition Func<Actor, bool>

Returns whether the actor it receives runs the package. Null runs it whenever the alias is filled.

Returns

ISubscription

The registration, which Unsubscribe() removes.

Remarks

The package joins the stack AddPackage(FormId<Package>, Func<Actor, bool>?) describes, and restarts whenever the reference getLinkedRefId returns changes. The actor's original link is restored once the package stops running, including across a save and load.

Exceptions

ArgumentNullException

package or getLinkedRefId is null.

InvalidOperationException

The alias belongs to no quest.

AddTravelPackage(Func<FormId<ObjectReference>?>, uint, Func<Actor, bool>?, PreferredSpeed?)

Gives the actor filling the alias a travel package whose location is near the reference getDestinationId returns.

public ISubscription AddTravelPackage(Func<FormId<ObjectReference>?> getDestinationId, uint radius, Func<Actor, bool>? condition = null, PACKAGE_DATA.PreferredSpeed? speed = null)

Parameters

getDestinationId Func<FormId<ObjectReference>?>

Returns the reference the package's location is near. Null counts as the condition failing.

radius uint

The distance from the reference, in units, that counts as at the location.

condition Func<Actor, bool>

Returns whether the actor it receives runs the package. Null runs it whenever the alias is filled.

speed PACKAGE_DATA.PreferredSpeed?

The speed the actor moves at. Null selects the package's default.

Returns

ISubscription

The registration, which Unsubscribe() removes.

Remarks

The package joins the stack AddPackage(FormId<Package>, Func<Actor, bool>?) describes. It restarts whenever the reference getDestinationId returns changes, and once its actor has stood still for a second more than 60 units past radius from the reference, so the actor follows a moving reference.

Exceptions

ArgumentNullException

getDestinationId is null.

InvalidOperationException

The alias belongs to no quest.

Clear()

Empties the alias.

public void Clear()

Exceptions

InvalidOperationException

The alias belongs to no quest.

CreateActor(FormId<ActorBase>, NiPoint3, bool)

Creates an actor of the base actorBaseId at position and fills the alias with it.

public Actor CreateActor(FormId<ActorBase> actorBaseId, NiPoint3 position, bool persistent = false)

Parameters

actorBaseId FormId<ActorBase>

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

position NiPoint3

The position, in the player's worldspace or, in an interior, the player's cell.

persistent bool

Whether the actor is persistent. While the actor's cell is unloaded, the game returns no form for ReferenceId unless the actor is persistent. The quest never deletes an actor it creates, so a persistent actor remains in the save.

Returns

Actor

Remarks

The game loads the actor's 3D afterwards. Start(int) waits for its actors to load. Before the 3D loads, SetOutfit takes effect but EquipItem does not, so call EquipItem after WaitFor3DLoadAsync. CreateActorAsync(FormId<ActorBase>, NiPoint3, FormId<Outfit>?, IEnumerable<FormId<Weapon>>?, bool, CancellationToken) also replaces the actor's outfit and weapons.

Exceptions

InvalidOperationException

The alias belongs to no quest.

InvalidOperationException

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

CreateActorAsync(FormId<ActorBase>, NiPoint3, FormId<Outfit>?, IEnumerable<FormId<Weapon>>?, bool, CancellationToken)

Creates an actor and fills the alias with it, as CreateActor(FormId<ActorBase>, NiPoint3, bool) does, then sets its outfit and weapons once its 3D loads.

public Task<Actor> CreateActorAsync(FormId<ActorBase> actorBaseId, NiPoint3 position, FormId<Outfit>? outfitId, IEnumerable<FormId<Weapon>>? weaponIds, bool persistent = false, CancellationToken cancellationToken = default)

Parameters

actorBaseId FormId<ActorBase>

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

position NiPoint3

The position, in the player's worldspace or, in an interior, the player's cell.

outfitId FormId<Outfit>?

The outfit the actor wears in place of its own, or null to leave its own.

weaponIds IEnumerable<FormId<Weapon>>

The weapons that replace every weapon the actor has, the first of them equipped. An empty list leaves the actor unarmed, and null leaves its weapons.

persistent bool

Whether the actor is persistent, as for CreateActor(FormId<ActorBase>, NiPoint3, bool).

cancellationToken CancellationToken

Cancels the outfit and weapon changes. A new game or a save load also cancels them.

Returns

Task<Actor>

A task that completes with the actor once its outfit and weapons are set.

Remarks

The weapons are replaced two seconds after the 3D loads and the outfit is set, once the game has equipped the actor's template weapons. The template weapons are removed, so a cell that loads again cannot equip one.

Exceptions

InvalidOperationException

The alias belongs to no quest.

InvalidOperationException

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

TimeoutException

The actor's 3D did not load within ten seconds, which happens where its cell is not loaded. The actor remains in the alias.

CreateMarker(NiPoint3)

Creates an XMarker at position and fills the alias with it.

public ObjectReference CreateMarker(NiPoint3 position)

Parameters

position NiPoint3

Returns

ObjectReference

Remarks

The quest deletes the marker once the alias is filled again or cleared, or once RemoveFromJournalAndReset() runs.

Exceptions

InvalidOperationException

The alias belongs to no quest.

InvalidOperationException

The game created no marker.

DisableAndClearAsync(float, TimeSpan, CancellationToken)

Disables the reference filling the alias once it is distance or more from the player, or once timeout of unpaused time has passed, and then empties the alias.

public Task DisableAndClearAsync(float distance, TimeSpan timeout, CancellationToken cancellationToken = default)

Parameters

distance float

The distance from the player, in units, at which the reference is disabled.

timeout TimeSpan

The span of unpaused time after which the reference is disabled wherever it is.

cancellationToken CancellationToken

Cancels the wait.

Returns

Task

A task that completes once the alias is emptied, immediately for an empty alias. A new game, a load, or cancellationToken cancels the task and leaves the alias filled.

Remarks

The reference is disabled rather than deleted, since deleting an actor the dialogue system still references ends the process. The packages added to the alias run until then.

Exceptions

InvalidOperationException

The alias belongs to no quest.

Fill<TReference>(FormId<TReference>)

Fills the alias with the reference referenceId names.

public void Fill<TReference>(FormId<TReference> referenceId) where TReference : struct, IObjectReference

Parameters

referenceId FormId<TReference>

Type Parameters

TReference

Remarks

The reference is stored by form ID. A reference the game does not have shows no marker, and is logged while an open objective targets the alias.

Exceptions

InvalidOperationException

The alias belongs to no quest.