Difference between revisions of "OnUserDefined"

From NWN Lexicon
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
=OnUserDefined=
+
__NOTOC__The script attached to this event fires depending on settings made during the [[OnSpawn]] event for creatures and some general level blanket signals for all objects (including creatures). Typically this script is a switch/case statement that does something different depending on the signal (numerical value) sent to it by an event that calls the script. This event makes it very easy to retain the default behavior of an object while adding custom mannerisms of your own.
  
The script attached to this event fires depending on settings made during the OnSpawn event for creatures and some general level blanket signals for all objects (including creatures). Typically this script is a switch/case statement that does something different depending on the signal (numerical value) sent to it by an event that calls the script. This event makes it very easy to retain the default behavior of an object while adding custom mannerisms of your own.
 
  
<br />
+
====Trigger====
  
====Trigger====
+
A script has used the [[SignalEvent]]() function with [[EventUserDefined]] as the parameter.
  
A script has used the SignalEvent() function.
+
For associates, such as henchmen or summons, the game also triggers event ID 20000 + [[Action_mode|ACTION_MODE_*]] constant, so for instance ACTION_MODE_SEARCH will toggle UDE of 20000, while ACTION_MODE_POWER_ATTACK is 20003. This seems to be undocumented in nwscript.nss but you can see examples of it in the Bioware AI files. This allows the AI to mimic the players actions.
  
<br />
 
  
 
====Function(s)====
 
====Function(s)====
Line 15: Line 13:
 
[[GetUserDefinedEventNumber | GetUserDefinedEventNumber() ]] to return the user defined event number being sent.
 
[[GetUserDefinedEventNumber | GetUserDefinedEventNumber() ]] to return the user defined event number being sent.
  
<br />
 
  
 
====Remarks====
 
====Remarks====
  
In a script that generates a user-defined event, use the [[EventUserDefined]](int) function to generate the appropriate internal event identification number which can be consumed in the OnUserDefined script. Also note that the UserDefined Death event is considered unreliable by Bioware. This is because the UserDefined event runs after the calling event has finished, in this case OnDeath. And as such, a call to [[DestroyObject]](OBJECT_SELF) in the OnDeath event will remove the object, closing its action queue and thus prevent the UserDefined Death event from executing.
+
In a script that generates a user-defined event, use the [[EventUserDefined]](int) function to generate the appropriate internal event identification number which can be consumed in the OnUserDefined script. Also note that the UserDefined Death event is considered unreliable by Bioware. This is because the UserDefined event runs after the calling event has finished, in this case [[OnDeath]]. And as such, a call to [[DestroyObject]](OBJECT_SELF) in the [[OnDeath]] event will remove the object, closing its action queue and thus prevent the UserDefined Death event from executing.
  
<br />
 
  
 
====Example====
 
====Example====
Line 55: Line 51:
 
| width="1px" align="right" valign="top" | <font color="gray">constants: </font>
 
| width="1px" align="right" valign="top" | <font color="gray">constants: </font>
 
|
 
|
[[ event | Event Constants  ]]
+
[[ event | Event Constants  ]] [[action_mode|ACTION_MODE_*]] constants
 
|}
 
|}
  

Latest revision as of 13:53, 12 May 2021

The script attached to this event fires depending on settings made during the OnSpawn event for creatures and some general level blanket signals for all objects (including creatures). Typically this script is a switch/case statement that does something different depending on the signal (numerical value) sent to it by an event that calls the script. This event makes it very easy to retain the default behavior of an object while adding custom mannerisms of your own.


Trigger

A script has used the SignalEvent() function with EventUserDefined as the parameter.

For associates, such as henchmen or summons, the game also triggers event ID 20000 + ACTION_MODE_* constant, so for instance ACTION_MODE_SEARCH will toggle UDE of 20000, while ACTION_MODE_POWER_ATTACK is 20003. This seems to be undocumented in nwscript.nss but you can see examples of it in the Bioware AI files. This allows the AI to mimic the players actions.


Function(s)

GetUserDefinedEventNumber() to return the user defined event number being sent.


Remarks

In a script that generates a user-defined event, use the EventUserDefined(int) function to generate the appropriate internal event identification number which can be consumed in the OnUserDefined script. Also note that the UserDefined Death event is considered unreliable by Bioware. This is because the UserDefined event runs after the calling event has finished, in this case OnDeath. And as such, a call to DestroyObject(OBJECT_SELF) in the OnDeath event will remove the object, closing its action queue and thus prevent the UserDefined Death event from executing.


Example

// OnUserDefined exists as an event for many objects
// to invoke it for a module, try something like...
// SignalEvent(GetModule(), EventUserDefined(112));
// then say we want to capture user-defined event number 112
// in our module's OnUserDefined event...
void main()
{
     switch (GetUserDefinedEventNumber())
     {
          case 112:
               PrintString("Event #112 occurred!");
               break;
          // ... additional case statements for other user-defined
          // events can be added as necessary
     }
}

See Also

functions:

GetUserDefinedEventNumber() SignalEvent EventUserDefined

constants:

Event Constants ACTION_MODE_* constants