Home For Builders Scripting Tutorials Adding & Removing Effects

Adding & Removing Effects

Intended Audience:
By David Gaider

[Printer Friendly / Syntax Highlight]

If you scroll down the list of commands in your script editor, you will see a long list of commands that begin with the word 'Effect'. These are the basis for building all spells, special abilities and visual effects in the game. There are two commands that allow you to use them: ApplyEffectToObject and ApplyEffectAtLocation. Both of them are very similar in their structure, except the former targets a specific object (creature, item, placeable object, etc) and the other targets a specific location (a point in space).

void ApplyEffectToObject (int nDurationType, effect eEffect, object oTarget, float fDuration=0.0f)

Duration Type: the 'nDurationType' is asking for a constant that begins with DURATION_TYPE_*, of which there are only three. DURATION_TYPE_INSTANT would apply to any effect that is both immediate and permanent and cannot be removed. EffectDamage would be one example, as well as any of the 'fire-and-forget' visual effects. If not instant, the constant must be either DURATION_TYPE_PERMANENT or DURATION_TYPE_TEMPORARY. Permanent is as it sounds... the effect lasts until removed or dispelled. A temporary duration means that the effect must have a duration specified in the command (and is the only time this is so).

Effect: This is the specific effect that you are going to use. It is common to define an effect variable first which contains all the pertinent information of the effect command, and then use that variable when applying... but it is not required.
Each effect will vary in its requirements. Some have only a set application and are simply called, such as EffectSleep or EffectCharmed. Some require additional parameters, such as EffectDamage or EffectPolymorph. I won't go through every effect here, but it is important that you provide all the parameters required by an effect or it will be invalid.

Target: this will either be the object (in ApplyEffectToObject) or the location (in ApplyEffectAtLocation). It can be declared seperately in a variable or defined in the command.

Duration: a duration (in seconds) is only required for effects of DURATION_TYPE_TEMPORARY. When specified, it must be as a float... meaning the number must have a decimal place. So put '3.0' for 3 seconds, or '10.5' for 10 and a half seconds.

Some Examples of Effects

- on the use of an object, polymorph the user into a pixie

NWScript:
void main() { effect ePixie = EffectPolymorph(POLYMORPH_TYPE_PIXIE); ApplyEffectToObject(DURATION_TYPE_PERMANENT, ePixie, GetLastUsedBy()); }

- an item with the Unique Spell property (with the tag "WONDERFUL_WAND" that heals and hastes the target for 30 seconds:

NWScript:
void main() { object oWand = GetItemActivated(); if (oWand == GetObjectByTag("WONDERFUL_WAND")) { object oTarget = GetItemActivatedTarget(); int nMaxHP = GetMaxHitPoints(oTarget); int nCurHP = GetCurrentHitPoints(oTarget); effect eHeal = EffectHeal(nMaxHP - nCurHP); ApplyEffectToObject(DURATION_TYPE_INSTANT, eHeal, oTarget); ApplyEffectToObject(DURATION_TYPE_TEMPORARY, EffectHaste(), oTarget, 30.0); } }

- in a creature's OnUserDefined, when an event #100 is sent, a generic bugbear is summoned without effects at a waypoint tagged "SUMMON_POINT":

NWScript:
void main() { int nUser = GetUserDefinedEventNumber(); if(nUser == 100) { effect eSummon = EffectSummonCreature("bugbeara001"); location lWP = GetLocation(GetObjectByTag("SUMMON_POINT")); ApplyEffectAtLocation(DURATION_TYPE_PERMANENT, eSummon, lWP); } }

Visual Effects
Visual effects are very similar to regular effects in that you apply them in the same way. You use EffectVisualEffect and provide it the parameter of one of the visual effect constants... all of which start with VFX_*. There are a fair number of these, however, and they deserve some special mention.

VFX_BEAM_* = these are the different types of beam visuals, and while grouped with the other visual effects, these constants are used with EffectBeam and not with EffectVisualEffect.
VFX_COM_* = these are combat visual effects, almost all of which should be applied with an instant duration.
VFX_DUR_* = most of these are the visual effects used for spells. They all must be applied with either a permanent or temporary duration.
VFX_FNF_* = these are called 'fire-and-forget' effects in that they play only once. They must have an instant duration.
VFX_IMP_* = these are 'impact' effects, usually used for the short-duration effect when a spell strikes a target. They have an instant duration.

This is an example of a magic well which, when used, creates an effect on itself and then applies a strength increase with an effect to the target (but can only be used once by them... if they use it again it strikes them with lightning for 8d6 damage):

NWScript:
void main() { effect eFirst; effect eSecond; effect eStrength = EffectAbilityIncrease(ABILITY_STRENGTH, (d4() + 1)); object oTarget = GetLastUsedBy(); int nOnce = GetLocalInt(oTarget, "Use_Pool_Once"); // if the PC has not used the pool before if (nOnce == FALSE) { eFirst = EffectVisualEffect(VFX_IMP_GOOD_HELP); eSecond = EffectVisualEffect(VFX_IMP_IMPROVE_ABILITY_SCORE); // create the effect on the pool ApplyEffectToObject(DURATION_TYPE_INSTANT, eFirst, OBJECT_SELF); // apply the strength effect with visual 3 seconds later DelayCommand(3.0, ApplyEffectToObject(DURATION_TYPE_INSTANT, eSecond, oTarget)); DelayCommand(3.0, ApplyEffectToObject(DURATION_TYPE_TEMPORARY, eStrength, oTarget, 300.0)); // and set the variable on the PC so they can't use the pool again SetLocalInt(oTarget, "Use_Pool_Once", TRUE); } // if they have used the pool else { eFirst = EffectVisualEffect(VFX_IMP_LIGHTNING_M); // allow them a reflex save against the lightning bolt int nDamage = GetReflexAdjustedDamage(d6(8), oTarget, 25, SAVING_THROW_TYPE_ELECTRICITY); eSecond = EffectDamage(nDamage, DAMAGE_TYPE_ELECTRICAL); // and then cause the visual effect of the bolt strike and apply the damage ApplyEffectToObject(DURATION_TYPE_INSTANT, eFirst, oTarget); ApplyEffectToObject(DURATION_TYPE_INSTANT, eSecond, oTarget); } }

Removing Effects

The thing to know about removing effects is that an effect has a unique 'pointer' established when it is applied. If you define a new effect variable later and define it as a similar type of effect, RemoveEffect will not target it.

The easiest way to remove an effect is to scroll through the current effects that are applied to a target through the use of GetFirstEffect and GetNextEffect... and then filter out the specific effect you are looking for. Once you have found it (or them if you are removing more than one effect at a time) the pointer is set to the correct effect and you can remove it.

The following commands are useful for filtering:

GetEffectCreator = if you want to specify only effects that were applied by specific creatures or objects
GetEffectDurationType = this will return the constant of an effect's duration type (either instant, permanent or temporary). Very general, but useful in specific circumstances.
GetEffectSpellId = this will return the constant of the spell that applied the effect (SPELL_*). Very useful if you are looking for all the effects of a particular spell or leaving out effects of certain spells.
GetEffectSubType = this will return the constants SUBTYPE_MAGICAL, SUBTYPE_SUPERNATURAL or SUBTPE_EXTRAORDINARY. All effects default to a magical sub-type unless specifically set otherwise.
GetEffectType = this is the most commonly-used filter when looking for a specific effect. It returns the constant EFFECT_TYPE_*, which almost duplicates the list of effect commands. Only visual effects don't have an effect type.

the basic script for removing an effect looks like this:

effect eEffect = GetFirstEffect(oTarget);
while (GetIsValidEffect(eEffect))
{
if (eEffect == filter used)
{
RemoveEffect(oTarget, eEffect);
}
eEffect = GetNextEffect(oTarget);
}

an example of removing a curse effect applied by a witch (with the tag "EVIL_WITCH") off of dialogue:

NWScript:
void main() { effect eEffect = GetFirstEffect(GetPCSpeaker()); while (GetIsEffectValid(eEffect)) { if ((GetEffectType(eEffect) == EFFECT_TYPE_CURSE) && (GetEffectCreator(eEffect) == GetObjectByTag("EVIL_WITCH"))) { RemoveEffect(GetPCSpeaker(), eEffect); } eEffect = GetNextEffect(GetPCSpeaker()); } }

Some Things To Be Aware Of

- EffectKnockdown causes a crash when applied by anything other than a creature (will be fixed in next patch)

- EffectHitPointChangeWhenDying doesn't work (will be fixed in next patch)

- All effects are not permanent... they do not save with the character back to the vault, but will persist within the current module. The longest effect type currently is the extraordinary effect, which will resist dispel magic effects and resting. ExtraordinaryEffect and SupernaturalEffect are applied when declaring the effect command:

effect eEffect = ExtraordinaryEffect (EffectSilence());