Home For Builders Scripting Tutorials Using Module Events

Using Module Events

Intended Audience:
By David Gaider

[Printer Friendly / Syntax Highlight]

When events are triggered (whether on a module, a placeable object, or wherever), the most important part to using the event via script is being able to identify who or what triggered the event. Keep in mind that this is seperate from the UserDefinedEvent... these are the events that are hard-coded into each individual object. You assign a script to that event and, when it is triggered, that script will run.

Module Event List

Event: OnAcquireItem, trigger: whenever an item is added to someone's inventory, what triggered it? Use GetModuleItemAcquired(). Also used here: GetModuleItemAcquiredFrom() to return the object the item was taken from, GetItemPossessor(object oItem) to return who gained the item.

Event: OnActivateItem, trigger: whenever an item using the item property spell 'Unique Power' (which is targeted) or 'Unique Power - Self Only' casts that spell, what triggered it? Use GetItemActivated(). Also used here: GetItemActivatedTarget() to determine the target of a 'Unique Power' spell if the target was an object, GetItemActivatedTargetLocation() to determine the location target of a 'Unique Power' spell if the target was a point, GetItemActivator() to determine who owns the item that was activated.

Event: OnClientEnter, trigger: whenever a player logs into the module, what triggered it? Use GetEnteringObject() to return the player object.

Event: OnClientLeave, trigger: whenever a player logs out of the module, what triggered it? Use GetExitingObject() to return the player object.

Event: OnModuleLoad, trigger: when the module is first started, what triggered it? The module itself... there is no specific object to 'get' in this case. In effect, this is the module version of the OnSpawn script, run only once when the module is loaded.

Event: OnPlayerDeath, trigger: a player character death, what triggered it? Use object GetLastPlayerDied() to return the player object who has died. Default use: the "nw_o0_death" script is generally used here, which clears the relationship of the standard factions to the player and determines when the 'death GUI panel' pops up that allows the player to exit or respawn.

Event: OnPlayerDying, trigger: a player has been reduced below 0 hit points, what triggered it? Use GetLastPlayerDying(). The difference between this and OnPlayerDeath is that here the PC is out of HP but hasn't officially 'died' yet. Default use: The standard script placed here is "nw_o0_dying" which applies EffectDeath to the player and kills him officially to trigger the OnPlayerDeath event. If this script was removed, a player would bleed to death before officially dying at -10 hit points.

Event: OnPlayerLevelUp, trigger: a player has levelled up, what triggered it? Use object GetPCLevellingUp(). This returns a player who has levelled up... but there is no way to prevent the player from finishing the process, as doing so is instantaneous and not an action like resting is.

Event: OnPlayerRespawn, trigger: a player has pressed the 'respawn' option on their Death GUI panel, what triggered it? Use GetLastRespawnButtonPresser(). Default use: the script "nw_o0_respawn", which resurrects the player, removes all adverse effects on him and applies the XP and gold penality. It also determines if there is someplace (like a waypoint) with the tag "NW_DEATH_TEMPLE" and sends them there... if not, it resurrects him where he died.

Event: OnPlayerRest, trigger: a player has pressed the rest button, what triggered it? Use object GetLastPCRested(). Also used here: int GetLastRestEventType() --- note that this event fires both before and after a PC rest. You can detect which through the use of GetLastRestEventType(), with the constants REST_EVENTTYPE_REST_CANCELLED, REST_EVENTTYPE_REST_FINISHED, REST_EVENTTYPE_REST_INVALID, REST_EVENTTYPE_REST_STARTED. If you are looking to control when a player can rest, you want to detect if the rest event has started... and if it is not the time to do so, use the AssignCommand on the PC to tell him to ClearAllActions. This will stop him from completing his rest.

Event: OnUnAcquireItem, trigger: an item has been dropped or removed, what triggered it? Use GetModuleItemLost() to return the item. Also used here: GetModuleItemLostBy() to return the object that used to have that item.

Event: OnHeartbeat, trigger: every six seconds after module load, the module's heartbeat will fire. There is nothing that triggers this event... whatever script is in this area will run on every heartbeat. For that reason, be careful that you do not add large scripts into this area that will be running constantly, as the overhead on processing power that they can take up can be large.

Event: OnUserDefined, trigger: a script has used the SignalEvent command and targeted the module (probably via GetModule). The event sent must have been set to be a UserDefined event. (example of use: SignalEvent (GetModule(), EventUserDefined(100)) ). In a script placed here, you would use GetUserDefinedEventNumber() to watch for the number being sent... and on that occurring, initiate the rest of your script.