EffectAreaOfEffect(int, string, string, string)

From NWN Lexicon
Revision as of 17:49, 2 March 2021 by Jasperre (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Returns a new Area of Effect effect.

effect EffectAreaOfEffect(
    int nAreaEffectId,
    string sOnEnterScript = "",
    string sHeartbeatScript = "",
    string sOnExitScript = ""
);

Parameters

nAreaEffectId
The ID of the Area of Effect; a reference to vfx_persistent.2da - usually a AOE_MOB_* when applied to creatures or AOE_PER_* when applied at a location.
sOnEnterScript
The script to use when a creature enters the area of the Area of Effect. If not set it uses the value from vfx_persistent.2da (Default: "")
sHeartbeatScript
The script to run on each of the Area of Effect's Heartbeats. If not set it will use the value from vfx_persistent.2da (Default: "")
sOnExitScript
The script to run when a creature leaves the area of an Area of Effect. If not set it uses the value from vfx_persistent.2da (Default: "")

Description

Create an Area Of Effect effect either on a creature which moves with it (AOE_MOB_* "mobile" values) or at a location where it will stay still (AOE_PER_* "persistent" values).

If the scripts are not specified, default ones will be used.

The target you can apply this to can be any valid (non static) object that ApplyEffectToObject works on, or a location.

This effect should not be applied instantly, only temporarily or permanently.


Remarks

Usually you edit in your own scripts into vfx_persistent.2da. However if you want to blank a script using the parameters use a invalid script name such as "default".

In the OnEnter, OnExit and OnHeartbeat scripts you use GetAreaOfEffectCreator returns the caller of the script that the effect is applied from.

This effect becomes an object after applied to creature or location and can be retrieved by a GetObjectByTag or GetFirstObjectInShape functions. The tag of the AOE object is the value of the column "LABEL" for a given AOE, defined in the vfx_persistent.2da file. These objects have no name and have no resref.

Effect functions are Constructors, which are special methods that help construct effect "objects". You can declare and link effects, and apply them using an ApplyEffectToObject() Command. Once applied, each effect can be got separately via. looping valid effects on the target (GetFirst/NextEffect()). See the Effect tutorial for more details.


Effect Breakdown

There is further information on Area of Effects on the nwn.wiki.

If an Area of Effect is created by an Area (using an Area's script or AssignCommand) the GetAreaOfEffectCreator will be OBJECT_INVALID which means most spellcasting related functions won't function correctly. Effects applied from it also have no GetEffectCreator set.

Applied to Creatures

If applied to a creature then the effect will apply to the creature as something you can find, and as an object that follows the creature around. This means it can be correctly dispelled. The effect if removed will remove the corresponding Area of Effect object.

Note that only circle-type area of effects should be applied to creatures - square ones seem to be a Bad Idea(TM) to use.

Since the OnEnter and OnExit of area of effects only apply to creatures (likely for optimisation purposes) checking for non-creatures in a mobiles AOE effect area is probably counterproductive.

Note you can "escape" the AOE applied to yourself if you move fast enough and also have some hiccup in the game (pausing or losing game focus) while moving fast. This is a lot less likely in NWN:EE but is still weirdly possible.

Applied to Locations

If applied to a location then the AOE object is created but no corresponding effect is applied to the caster to dispel it. Instead area dispel magic can check for the object type in the given target area.

This object is static and basically just stays put doing it's thing. It can be either rectangular or circular.

Area of Effect Object

This object has all the normal parameters of an object; it can be destroyed by DestroyObject to "dispel" it or remove it from the game.

You also get a User Defined Event according to SetEventScript usable constants - although you need to use that function to make use of it.

Due to the lack of GetEffect* functions being able to work on the object, you cannot retrieve information such as the remaining duration or the type (such as supernatural, or magical). This means at-location AOE's have less information available to scripters unless manually set.

To get this object in the script that creates it, you should use GetNearestObjectByTag or similar to find it, using the LABEL column to identify it.

Area of Effect Effect

If applied to creatures you can gather some more information from the effect that is applied.

nIndex Parameter Value Description and Notes
GetEffectInteger
0 nAreaEffectId The vfx_persistent.2da line this effect is related to
GetEffectString
0 sOnEnterScript sOnEnterScript parameter. If blank it will use the value from vfx_persistent.2da.
1 sHeartbeatScript sOnEnterScript parameter. If blank it will use the value from vfx_persistent.2da.
2 sOnExitScript sOnExitScript parameter. If blank it will use the value from vfx_persistent.2da.
GetEffectObject
0 AOE created This is the AOE object created when the effect was applied to this creature.

Known Bugs

While NWN:EE improved mobile (attached to creature) AOE's which now should move correctly with the creature they are attached to, you can still escape them if the AOE lags for any reason - it seems to occur when the game loses focus and for smaller AOE's. To work around this in the OnExit of an AOE make sure to never strip EFFECT_TYPE_AREA_OF_EFFECT from an exiting object. It'll fire OnExit then OnEnter events in quick succession since it'll rapidly "catch up".

There are still glitches with the some spell functions when used inside the AOE's script - such as GetSpellId(), GetSpellSaveDC(), GetCasterLevel(), and so on, because of the fact the values can change after the AOE has been in place. These will be documented in the various function pages if applicable.


Version

1.62

Example

int AOE_BOG_STINK = 1500;
 
void main()
{
    //Declare the Area Of Effect, assign it an ID, and tell it what scripts to run when someone interacts with it.
    effect eAOE = EffectAreaOfEffect(AOE_BOG_STINK, "bog_on_enter", "bog_on_hb", "bog_on_exit");
    location lTarget = GetLocation(GetEnteringObject());
    int nDuration = 2;
    //Create an instance of the AOE Object using the Apply Effect function
    ApplyEffectAtLocation(DURATION_TYPE_TEMPORARY, eAOE, lTarget, RoundsToSeconds(nDuration));
}

See Also

functions:  ApplyEffectAtLocation


 author: John Shuell, editor: Jasperre, additional contributor(s): Peter Poe, Jasperre