EffectLinkEffects

EffectLinkEffects(effect, effect)

Creates one new effect object from two separate effect objects.

effect EffectLinkEffects(
    effect eChildEffect,
    effect eParentEffect
);

Parameters

eChildEffect

One of the two effects to link together.

eParentEffect

One of the two effects to link together.

Description

Returns an Effect that combines the two supplied effects, returning eChildEffect as a child of eParentEffect. The returned effect can then be applied to a target and be affected by all linked effects.

If you remove one of the effects from a target which is linked to others (for example, a Stun effect linked to a nice stunned visual) the other linked effects will be removed too. This lets things like Remove Curse, Freedom, Clarity and so on, look correct - they remove effects by the EFFECT_TYPE_ constant, and let the game work out if there were any extra visuals linked with it.

Always link effects you want to be removed or dispelled at the same time.

It is unknown, although it should never be done as such, if you link a MagicalEffect(eEffect) and a SupernaturalEffect(eEffect) which type the final EffectLinkEffects() will turn out to be.

Remarks

You can also link effects to other effects even if they were created with EffectLinkEffects.

Note: When applying linked effects if the target is immune to all valid effects most other effects will not be applied as well. This means that if you apply a visual effect and a stun effect (EffectStunned()) (in a link) and the target is immune to the stun effect that the visual effect will not be applied as well. Visual Effects are not considered "valid" effects for the purposes of determining if an effect will be removed or not and as such should never be packaged *only* with other visual effects in a link.

So if you wanted to apply both, say, a Deafness effect and a Stunning effect, but apply them so only Immunity: Deafness and Immunity: Stunning stopped each separately, do not link both effects in one Link.

However, there is a little discrepancy as such an EffectAttackDecrease() linked with EffectStunned will not be blocked by the immunity, and in this case any visual effects linked together will also not be removed. There might as well be more effects like attack decrease though.

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.

Known bugs

If a linked effect with only visual effects is created, it will not be able to be applied to a target, and will not display any visual animation. Linking a non-visual effect can remedy the situation, displaying all linked visual animations.

Version

1.62

Example

// Link Stunning and an appropriate Stunned VFX, and apply to
// the user of the lever, for 120 seconds (2 minutes).
 
// If the user is immune to being stunned, they will not see the
// VFX either and just get "So and so is immune to Stun"
// reported.
 
// However, there IS a separate impact (instantly applied) VFX,
// which shows the target was hit by stun, even if they were
// immune.
 
// If we then later cast Clarity (which removes mind effects, like
// stun) it will remove the associated (linked) visual too.
 
void main()
{
    // Get the user
    object oUser = GetLastUsedBy();
 
    // Declare Effects
    effect eVis = EffectVisualEffect(VFX_IMP_STUN);
    effect eStun = EffectStunned();
    effect eDur = EffectVisualEffect(VFX_DUR_MIND_AFFECTING_DISABLED);
    // Link effects
    effect eLink = EffectLinkEffects(eDur, eStun);
 
    // Duration is 120 seconds
    float fDuration = 120.0;
 
    // Apply effects - the link can just be applied, no checking
    // if they are immune or not.
    ApplyEffectToObject(DURATION_TYPE_INSTANT, eVis, oUser);
    ApplyEffectToObject(DURATION_TYPE_TEMPORARY, eLink, oUser, fDuration);
}
 
// Apply two negative effects and one positive. Even though one
// of the negative effects is an EffectCurse, it still can be
// removed via restoration spells (via looping the effects on
// the target) because it is linked to another negative
// non-curse effect (which the looping removes).
 
void main()
{
    // reduce STR by two; it's a Curse!
    effect eNegative1 = EffectCurse(2,0,0,0,0,0);
    // reduce CON by two; no curse
    effect eNegative2 = EffectAbilityDecrease(ABILITY_CONSTITUTION, 2);
    // increase DEX by two
    effect ePositive1 = EffectAbilityIncrease(ABILITY_DEXTERITY, 2);
 
    // link the effects together
    effect eLink = EffectLinkEffects(eNegative2, eNegative1);
    eLink = ExtraordinaryEffect(EffectLinkEffects(ePositive1, eLink));
 
    // apply them
    ApplyEffectToObject(DURATION_TYPE_PERMANENT, eLink, GetFirstPC());
}

See Also

functions:	EffectCharmed
constants:	EFFECT_TYPE_* Constants

---

 author: John Shuell, editors: Jasperre, Mistress, additional contributor: Jasperre