Building Triggers
Creating triggers under the ACR is nearly the same as creating them under standard NWN2; The ACR just provides a few more options for builders.
Contents
Naming Conventions
The following conventions will need to be used in naming trigger blueprints to avoid any conflicts with other blueprints and to ensure that all content works properly with scripts:
Localized Name
Choose a one or two word descriptive name. You can add text visible only to builders in {} to help distinguish multiple blueprints of the same type at a glance.
- Example: Transition Trigger {party}
Template, ResRef, and Tag
All trigger blueprints in the basemod will begin with the abr_tr prefix to designate them as global blueprints. Server specific blueprints should begin with a 3 digit server number in place of the "abr", so 001_tr for example. For every subcategory, add a two letter acronym delimited with underscores followed lastly by a descriptive name for the trigger itself. This helps to quickly locate blueprints when all we have is its resref. To illustrate, here are a few examples:
- Example: A global generic trigger:
abr_tr_gn_mytrigger - Example: A server generic trigger on server 01:
001_tr_gn_mytrigger
Comments
To identify and track blueprint versions, it's best to write your name and the date you modified the blueprint in the comments area. In addition, you may wish to note any scripts the blueprint is specifically used by (primarily for dedicated blueprints).
- Example: Created By: John Doe, Date Modified: 2014-01-23, Used By: acr_trigger_i.nss
For global blueprints, you should also include a link to this wiki page so builders that are unfamiliar with conventions or configuration options can easily find them.
Event Handlers
The default basemod triggers should already have these handlers in place, so if you are copying an existing blueprint, you probably don't need to do anything here. To start off with, make sure the trigger's event scripts are all set correctly. The default scripts are:
-
acf_trg_onclick -
acf_trg_ondisarm -
acf_trg_onheartbeat -
acf_trg_ontraptriggered -
acf_trg_onenter -
acf_trg_onexit -
acf_trg_onuserdefined
Custom Scripting
If you need to add your own custom scripts, you can of course do so. First, include this line at the top of your script somewhere:
#include "acr_trigger_i"
Then make sure the following functions are called in each of your custom event handlers, just as they are done in the acf_trg_* scripts. Failure to call one of these scripts in a trigger's event handler WILL break the ACR's trigger system, and probably a few other things as well.
-
ACR_TriggerOnClick() -
ACR_TriggerOnDisarm() -
ACR_TriggerOnHeartbeat() -
ACR_TriggerOnTrapTriggered() -
ACR_TriggerOnEnter() -
ACR_TriggerOnExit() -
ACR_TriggerOnUserDefined()
Configuration Options
- See also: Using Local Variables
These options allow the builder to configure a trigger to better suit their needs. These options are changed by altering the local variables on the trigger itself, and not by altering any of the scripts used by the trigger. The default basemod triggers should already have these variables in place, so if you are copying an existing blueprint, you probably only need to alter the values of the variables here.
Detect Magic
These are advanced options for triggers to register as magical to Detect Magic.
-
ACR_SPELLSCHOOL(integer) If the trigger should register to Detect Magic, use integer 1 - 9 for the school of magic of the aura. Detect Magic: SpellSchool Variables for which integer calls which school of magic. -
ACR_SPELLPOWER(integer) If the trigger should register to Detect Magic, use integer 1 - 9 for the spell level of the aura. See the Detect Magic page for more information. -
ACR_SPELLSCHOOL2(integer) If the trigger should register a second aura to Detect Magic, use integer 1 - 9 for the school of magic of the aura. See the Detect Magic page for which integer calls which school of magic. -
ACR_SPELLPOWER2(integer) If the trigger should register a second aura to Detect Magic, use integer 1 - 9 for the spell level of the aura. See the Detect Magic page for more information.
- Detecting Portals
- Detecting Glyphs and Symbol Traps
See Detect Magic: Glyphs and Symbol Traps
Effects
These are advanced options for placing effects (visual and otherwise) on triggers. For the following effect options, {EVENT} is one of:
-
ON_CLICK -
ON_DISARM -
ON_HEARTBEAT -
ON_ENTER -
ON_EXIT
Visual Effects
-
ACR_VFX_{EVENT}_EFFECT_VISUAL(string)
These strings are used to define the visual effects that trigger for each event on the activating creature (this includes light shaft placeables). These are not mutually exclusive options (ie they can all be defined on a single object). Each string must be defined in the following format: VFX CONSTANT/VFX DURATION, where VFX CONSTANT is one of the GetEffectInteger constants defined in visualeffects.2da (listed in NWScript.nss) and VFX DURATION is a float representing the total number of seconds the effect should last (use 0.0 if it's either n/a or a permanent effect; some exceptions apply noted in the individual effect sections of the documentation).
Visual effects are those which only provide a visual indicator that something has occurred. These effects are totally harmless but are used in conjunction with Physical and Damage Effects to illustrate something has occurred to the target upon interacting with an object (the source of the effects).
Visual effect constants are string values used in constructing the *_EFFECT_VISUAL local variable. The list of supported effects can be expanded as necessary, but any changes or additions should be reflected in the _getVFXConstant() function in the acr_vfx_i.nss file in order for the effect to function.
Not all visual effects will support variable durations. Some simply have fixed animation cycles which cannot be affected through scripting.
To setup the visual effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.
For example, to construct a fire beam that triggers when an object is used (touched) and expires after 5 seconds, you would create the following:
- Variable Name :
ACR_VFX_ON_USE_VISUAL_EFFECT - Variable Type : string
- Variable Value :
VFX_BEAM_FIRE/5.0
You can substitute any of the available visual effects constants in place of VFX_BEAM_FIRE, but be sure your spelling is correct. Typo's will not yield correct results.
Physical Effects
These strings are used to define the physical effects that trigger for each event on the activating creature. These are not mutually exclusive options (ie they can all be defined on a single object). Each string must be defined in the following format: VFX TYPE/VFX DURATION, where VFX TYPE is the specific type of effect to be applied and VFX DURATION is a float representing the total number of seconds the effect should last (use 0.0 if it's either n/a or a permanent effect; some exceptions apply noted in the individual effect sections of the documentation).
Physical effects are those that affect the target's health or condition. These include anything from raw damage to altering the target's state of mind. They typically have NO visual indication (exceptions exist like knockdown) and as a result, should be used in tandem with a suitable visual effect for the benefit of the player (both in terms of providing IC feedback that something has affected their character as well as providing a more enjoyable and engaging atmosphere).
Not all physical effects have durations. Some are instant effects and others are permanent. damage effects apply directly to the physical effect, and as such, you should always reference this section when constructing damage effect values to understand how the damage will be applied.
To setup the physical effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.
For example, to construct a knockdown physical effect to be used with the fire beam visual effect described above that expires after 10 seconds, you would create the following:
- Variable Name :
ACR_VFX_ON_USE_PHYSICAL_EFFECT - Variable Type : string
- Variable Value :
KNOCKDOWN/5.0
You can substitute any of the physical effects available in place of KNOCKDOWN, but be sure your spelling is correct. Typo's will not yield correct results.
Damage Effects
These strings are used to define the damage a physical effect will apply to the activating creature for each event as well as the saving throw required to avoid suffering from the physical effect or related damage. These are not mutually exclusive options (ie they can all be defined on a single object) but they must exist for each physical effect defined if some form of damage is to be applied. Each string must be defined in the following format: DAMAGE/ST TYPE/DC, where DAMAGE is the damage value to apply toward the desired physical effect, ST TYPE is the type of Saving Throw possible (FORTITUDE, REFLEX, or WILL), and DC is the Difficulty Class of the save.
Damage effects contain the actual details of the physical effect being applied, including any saving throws and DCs that the target can attempt to save against. Damage effects need not be defined, but they should be defined appropriately according to the physical effect used. Read the article on physical effect types to determine how damage values are applied to a given physical effect. Do not define a damage Effect without a corresponding physical effect to apply it to.
To setup the damage effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.
For example, to give the knockdown physical effect described above some damage and allow the target a reflex saving throw of DC 15, you would create the following:
- Variable Name :
ACR_VFX_ON_USE_DAMAGE_EFFECT - Variable Type : string
- Variable Value : 3.0/
REFLEX/15.0
All values must be represented as floating point numbers.
