NVSE Event Handling

Jump to: navigation, search

Event handling is added by NVSE 4.6, and was ported from OBSE.

Events include block types found in object scripts, such as OnHit, OnDeath, and so on, as well as other events involving loading, saving, and exiting the game.

An event handler allows response to game events, without having to attach scripts directly to objects. Instead, the scripter uses SetEventHandler / SetEventHandlerAlt to register a User Defined Function as a handler for a specific event. When an event occurs during gameplay, NVSE will invoke any handlers that correspond to it, passing information about the event to their function through its arguments.

Each event expects its handlers to accept a specific set of arguments. The in built events, including any required arguments (listed in the order in which they should appear in the function definition) are listed in the table below. In addition, User Defined Events are possible.

If an event runs slightly before a change could be spotted, consider using SetGameMainLoopCallback to effectively delay the script by a few frames, then un-set the callback once it is called.

Event First Second Notes
OnActivate Activator/Activated (reference) ActionRef (reference) Unlike attaching an OnActivate block to an object's script, this event will NOT prevent normal activation.

Runs BEFORE the OnActivate block occurs. Runs even if activation will be prevented, such as if trying to activate an inaccessible door.

OnActorEquip (alias: OnEquip) Equipper (actor reference) Equipped (item Base Form) Runs before the item is considered as equipped, right after the item occupying the same equipment slot(s) is unequipped.
OnActorUnequip (alias: OnUnequip) Unequipper (actor reference) Unequipped (item Base Form) Does not run if equipped ammo is dropped.
OnAdd AddedItem (a world reference) AddedTo (a container reference) Only works while picking items up in the game world.
OnClose Closed Closer (reference)
OnCombatEnd Target (actor reference) Ender (actor reference)
OnDeath Killed (actor reference) Killer (actor reference)
OnDrop Dropper (reference) Dropped (game-world reference).

Unlike the OnDrop blocktype, does not run when transferring an item in the inventory menu from one container to another.

OnHit Target (any reference) Attacker (either an actor, or a projectile reference if the Target is a non-Actor AND the source weapon isn't melee/unarmed). Runs BEFORE damage is dealt, unlike the OnHit block.

When Attacker is a projectile, use GetProjectileRefSource/GetProjectileRefWeapon for additional info.

OnHitWith Target (any reference) Weapon (Base Form) Runs BEFORE damage is dealt, unlike the OnHitWith block.
OnLoad Loaded Loaded
OnMagicEffectHit Target BaseEffect
OnMurder Murdered (actor reference) Murderer (actor reference)
OnOpen Opened Opener
OnPackageStart Actor Package
OnPackageChange Actor Package
OnPackageDone Actor Package
OnReset WhatsReset WhatsReset (duplicate of first parameter)
OnSell SoldInvItem (Base Form) Seller (can be Player, or Vendor reference) GetSoldItemInvRef will give more information about the sold item.

BUG: this event never ran prior to xNVSE v6.2.8.

OnStartCombat Target Starter If loading from a save where combat was already active, this event will NOT re-trigger.
OnTrigger Trigger ActionRef
OnTriggerEnter Trigger ActionRef
OnTriggerLeave Trigger ActionRef
SayToDone Speaker Info
- - -
Corresponding to Plugin API
LoadGame sSaveFileName No Argument
  • Doesn't run for entering the game using CenterOnCell from the main menu.
  • Runs an extra time for the pop-up warning if a save has missing plugins.
  • Runs after the save has been mostly loaded in already, as GetParentCell returns the cell the player would be in after loading that save.
SaveGame sSaveFileName iSaveFileNameLength
PostLoadGame bSuccessfullyLoaded Does not run upon loading a new game. Also doesn't run for entering the game using CenterOnCell from the main menu.
RuntimeScriptError sErrorMessage iSomeInt
DeleteGame sSaveFileName iSaveFileNameLength
RenameGame sSaveFileOriginalFullName iSaveFileNameLength
RenameNewGame sSaveFileNewFullName iSaveFileNameLength
NewGame Doesn't run for entering the game using CenterOnCell from the main menu.
DeleteGameName sSaveFileRelativeName iSaveFileNameLength
RenameGameName sSaveFileRelativeOriginalName iSaveFileNameLength
RenameNewGameName sSaveFileRelativeNewName iSaveFileNameLength

Event Functions

See Also

External Links