SetEventScript(object, int, string)

From NWN Lexicon
Jump to: navigation, search
Nwnee logo.jpg Note: This article documents Neverwinter Nights: Enhanced Edition new content or changes/updates/fixes to 1.69 functions. These are all listed under the category and patches pages.
Sets the given event script for the given object and handler.
int SetEventScript(
    object oObject,
    int nHandler,
    string sScript
);

Parameters

oObject
The object to set the event script on.
nHandler
An EVENT_SCRIPT_* constant matching the event to set the script on.
sScript
The script to attach to the event.

Description

Sets the given event script for the given object and handler.

Returns 1 on success, 0 on failure.

Will fail if oObject is invalid or does not have the requested handler.

Remarks

This also works on PCs with the OnConversation, OnDeath, OnHeartbeat, and OnUserDefined, OnCombatRoundEnd, OnPerception, and OnSpellCastAt. The main missing ones appear to be OnRested (covered by the module) and possibly OnBlocked, OnPhysicalAttacked and OnDamaged but these may exist just needs testing!

If a script is cleared (by using a blank parameter) you can unset that script and it will just not ever fire (as if it was never set). This is particularly useful for either toggling, or single firing, a heartbeat script. See the code example.

A blank event script is more efficient than a void main() { } script - it simply is not called at all (although in some cases this means a default script does run - eg; OnClick for the default transition script).

From testing PCs have scripts actually set to the word "default" by default - any changes made are not saved to a .bic file. Therefore be careful you do not create a script called "default" since it might run many times in creature events you don't expect!

It also means the GetEventScript will never return a blank entry for a PC unless specifically set using SetEventScript.

Version

1.74.8164 with further bugfixes after this.

Example

// Thanks to Clippy for this great example!
// This script is a perfect example of a fire-and-forget placeable OnHeartbeat script.
// It will apply the visual effect ID stored in local variable "vfx" (set in the toolset)
// Then it will remove the event script from the heartbeat so it never fires again.
// This is efficient - it will fire the first heartbeat "when ready" (lazily, especially if it's in an area the player isn't) and then never fire it ever again.
void main() {
    int vfx = GetLocalInt(OBJECT_SELF, "vfx");
    if (vfx)
        ApplyEffectToObject(DURATION_TYPE_PERMANENT, EffectVisualEffect(vfx), OBJECT_SELF);
 
    SetEventScript(OBJECT_SELF, EVENT_SCRIPT_PLACEABLE_ON_HEARTBEAT, "");
}

See Also

functions: GetEventScript()
constants: EVENT_SCRIPT_* Constant Group