NVSE Event Handling
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 | |||
| ExitGame | |||
| ExitToMainMenu | |||
| LoadGame | sSaveFileName | No Argument |
|
| SaveGame | sSaveFileName | iSaveFileNameLength | |
| QQQ | |||
| 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
- SetEventHandler / SetEventHandlerAlt has examples on how to use these.
- RemoveEventHandler
- GetCurrentEventName
- DispatchEvent / DispatchEventAlt
