GetEffectCreator(effect)

Gets the object that created eEffect.

object GetEffectCreator(
    effect eEffect
);

Parameters

eEffect

An existing effect already applied in game.

Description

Returns the object that created eEffect.

Returns OBJECT_INVALID if eEffect is not a valid effect, or the creator doesn't exsist within the module.

Must be used on eEffect which has been got by GetFirst/NextEffect().

The creator is always the object the script which created (not always applied) the effect runs from. Spell scripts are always executed upon the spell caster (and so effects applied from them spells get the caster as the effect creator). Area-of-effects that create the effect return the caster of it, so basically the caster created it, never the AOE.

Traps cannot be returned, unless they are not one-shot, because they are removed from the game (thus made OBJECT_INVALID) if they are one shot only.

Doors, placeables and the like can create effects and the creator is the placeable or door, until destroyed (thus making it OBJECT_INVALID).

Areas and Modules seem to also be valid creators of effects, and of course are never destroyed.

Remarks

You must first create and place the effect you wish to examine into a variable before calling this function. This is useful when you want to specify only effects that were applied by specific creatures or objects. An example may be a trap that causes a strength decrease each round if the player is in its area of effect. If the player leaves that area of effect, the trap will loop through the effects on the player looking for only the effects it created, and remove them.

In many cases, this will work as expected - but note, the Effect Creator is the object a function or script is running on, which actually declared the effect in question.

See the code sample for examples of when objects may be one thing, or another, in case you have problems with AssignCommand().

Known Bugs

The previous bug stating "returns OBJECT_INVALID if the effect creator was the module." seems now not to be true.

1.64 will fix any exsisting problems with cirtain effects not returning a valid creator, no matter how they are applied (EffectSpellFailure(), EffectTurnResistanceIncrease() and EffectTurnResistanceDecrease())

Version

1.64

Example

// Lever: 2 things happen. If used once, it applies a strength decrease.
// Secondly, if used again, it will remove all effects from the target
// which were created by this lever.

void main()
{
    // Get ourselves and the user
    object oSelf = OBJECT_SELF;
    object oUser = GetLastUsedBy();

    // If used once, we apply an effect
    if(GetLocalInt(oSelf, "DO_ONCE") == FALSE)
    {
        // Done something once
        SetLocalInt(oSelf, "DO_ONCE", TRUE);

        // Apply a strength effect, and a visual
        effect eStr = EffectAbilityDecrease(ABILITY_STRENGTH, 2);
        effect eVis = EffectVisualEffect(VFX_IMP_REDUCE_ABILITY_SCORE);
        ApplyEffectToObject(DURATION_TYPE_INSTANT, eVis, oUser);
        ApplyEffectToObject(DURATION_TYPE_PERMANENT, eStr, oUser);
    }
    else
    {
        // Remove all effects created by us - IE, the permament strength decrease.
        effect eCheck = GetFirstEffect(oUser);
        while(GetIsEffectValid(eCheck))
        {
            // Check creator
            if(GetEffectCreator(eCheck) == oSelf)
            {
                // Remove the effect as it was created by us.
                RemoveEffect(oUser, eCheck);
            }
            eCheck = GetNextEffect(oUser);
        }
    }
}

// When does an effect become created by another creature, other
// then the script caller?
// The creator of an effect is always who declared an effect!

// Example 1: Normal application of effects.
// In this case, the armor class increase will return the object this
// script is run from, for example, a lever's On Used event.
void main()
{
    // Get user
    object oUser = GetLastUsedBy();

    // Create the effect (Thusly, this means this object, the lever,
    // is the creator of this effect)
    effect eAbility = EffectACIncrease(1);

    // Apply the effect
    ApplyEffectToObject(DURATION_TYPE_PERMANENT, eAbility, oUser);
}

// Example 2. Using AssignCommand() function, we will make
// the user apply the effect - however, because the lever has
// created it, the lever will be returned as the effect creator.
void main()
{
    // Get user
    object oUser = GetLastUsedBy();

    // Create the effect (Thusly, this means this object, the lever,
    // is the creator of this effect, not the user!)
    effect eAbility = EffectACIncrease(1);

    // Assign the user to apply the effect
    AssignCommand(oUser, ApplyEffectToObject(DURATION_TYPE_PERMANENT, eAbility, oUser));
}

// Example 3: To get the user to be the effect creator, we must
// have a wrapper function called to do the effect creation, and
// thusly use AssignCommand() to run it.
void DoTheEffect()
{
    // Create the effect - because we assigned this function to
    // the user of the lever, now it is the creator of the effect.
    effect eAbility = EffectACIncrease(1);

    // We do not need assign command here, the user will apply it
    ApplyEffectToObject(DURATION_TYPE_PERMANENT, eAbility, OBJECT_SELF);
}
void main()
{
    // Get user
    object oUser = GetLastUsedBy();

    // Assign the user to apply the effect via. the function created
    // above.
    AssignCommand(oUser, DoTheEffect());
}

functions:	GetAreaOfEffectCreator \| GetEffectDurationType \| GetEffectSpellId \| GetEffectSubType \| GetEffectType
categories:	Effects Functions