OnHeartbeat

From NWN Lexicon
Revision as of 17:48, 11 September 2020 by Jasperre (talk | contribs)
Jump to: navigation, search

The script associated with this event usually fires every six seconds (the span of a combat round in NWN). This is good for a script that needs to check for something repeatedly or perform an action regularly. Be aware that too many OnHeartbeat scripts can be processor costly. Use other types of event scripts when possible. Area of effects can have a Heartbeat script defined when created.

Unlike OnCombatRoundEnd this is not garanteed to start at the same time. It appears to be based off the spawn in time of an object. For instance if it starts the first heartbeat at when GetTimeSecond() is 2, the next one will be at 8, 14, etc. (if not on low AI mode).

Trigger

Every six seconds that pass (one round). If many OnHeartbeat events have to run at the same time, some will get low priority. It appears, at least, that objects in areas where there are no PCs get low priority. See SetAILevel for more detail. In testing modules with many heartbeats, some of these heartbeats would fire irregularly, and with up to 15 second intervals.

It should be that a heartbeat will always, eventually, be scheduled in to fire.

To make this efficient rather than using a minimal or blank script, have no script in the field or use SetEventScript to clear it.


Objects With Heartbeat Events

Object Script Fire Frequency Affected by AI Level Additional Notes
Module 6 seconds No This should be the script used to do module-wide events and checks in one, consolidated place. It is usually one of the larger heartbeat scripts in a module.
Area 6 seconds No Since this is unaffected by a PC being present, be aware a large number of areas heartbeat scripts may slow down a module significantly.
Creature NPC 6-15 seconds Yes Standard creature heartbeat scripts usually perform repetitive tasks that can get interrupted (since the action queue can be cleared by external factors), such as waypoint walking.
Player 6 seconds No Defaults to a script name "default" which doesn't exist in the game files. Instead of overriding "default" use SetEventScript to set this to a proper script. This can be actually useful as a very efficient (only runs when the PC is present, so scales with number of PCs) local heartbeat.
Placeable and Door 6-15 seconds Yes Placeables and doors frequently are the slowest heartbeats in the game even with PCs present in the area. It is highly recommended to not use them for anything that is required for module progression, instead using the area one or an alternative (eg; an area of effect/trigger area to detect a PC being nearby).
Area of Effects 6 seconds No (we think) Area of Effect scripts are set to some default value in vfx_persistent.2da, or overriden by the parameters in EffectAreaOfEffect. Can also set it later using SetEventScript. They will fire consistently to do per-round damage and are used as such by the default Bioware spells (eg; Acid Fog will do acid damage to those standing in it).
Trigger and Encounter 6 seconds No (we think) Note "Traps" are a type of trigger. It is not recommended to use their heartbeat scripts unless, for instance, checking to do AOE damage on each round. A good way in general to toggle this on or off is to use SetEventScript.
Encounter 6 seconds No (we think) Triggers and Encounters are very similar in function. It is not recommended to use their heartbeat scripts unless, for instance, checking to do AOE damage on each round. A good way to "toggle" this on Encounters would be making the trigger active or not, which suppresses the event so it doesn't run if the encounter is inactive. A good way in general to toggle this on or off is to use SetEventScript.

Remarks

When used for a creature, conditions set within the OnSpawn script are checked and executed if they are applicable; these include "fast buff" for enemies (used when a PC draws within a certain range to simulate preparation), day/night postings for the WalkWayPoints() function, and the standard ambient animations used by creatures when standing around.

Setting the AI level to AI_LEVEL_HIGH on a creature will force the heartbeat to fire as if a PC was in the area. This is useful for monsters you want to travel across multiple area's with waypoints, but is costly on the CPU.

Area of effects can have a Heartbeat script defined, and can apply damage (such as Acid Fog does) to everyone in the area, each combat round.


There are a set of special heartbeat script used when creatures are under the effect of certain statuses. See the statescripts.2da file for what these are. Generally most just try and signal to a henchman to cure the status (eg: cast Remove Fear on someone under the effect of EffectFrightened) but can be modified by module writers to do additional things.