Effects

Any number of effects can be attached to an object. Effects can perform various tasks, thus eliminating the need for helper objects. This is especially of interest for magic spells that act with a given duration. Effects are available from CE on.

Introduction

Effects are, roughly put, dynamic timers that can be attached to objects. Effects themselves have no visible or acoustic representation - for this you would use objects or particles instead - effects are pure scripting helpers. They also offer a general interface that can be used to resolve conflicts of temporary status changes made to objects by other objects at the same time.
Here an example of implementing an invisibility spell without effects:
/* Unsichtbarkeitszauber ohne Effektsystem */

#strict

local iRestTime; // Zeit, die der Zauber noch aktiv ist
local pTarget;   // Unsichtbar gemachter Clonk
local iOldVisibility; // Vorheriger Sichtbarkeitsstatus
local iOldModulation; // Vorherige Farbmodulation

public func Activate(pCaster, pCaster2)
{
  // Zauberer ermitteln
  if (pCaster2) pCaster = pCaster2; pTarget = pCaster;
  // Magie kann man hören, ganz klar ;)
  Sound("Magic*");
  // Vorherige Sichtbarkeit des Zauberers speichern
  iOldVisibility = GetVisibility(pCaster);
  iOldModulation = GetClrModulation(pCaster);
  // Zauberer unsichtbar machen
  SetVisibility(VIS_Owner() | VIS_Allies() | VIS_God(), pCaster);
  // Halbdurchsichtig bläulich für den Besitzer und Verbündete
  SetClrModulation(ModulateColor(iOldModulation, RGBa(127,127,255,127)), pCaster);
  // Timer starten: 30 Sekunden unsichtbar
  iRestTime = 30;
}

protected func TimerCall()
{
  // Zeit zählen
  if (iRestTime--) return(1);
  // Fertig; Objekt entfernen
  return(RemoveObject());
}

protected func Destruction()
{
  // Zauber wird entfernt: Unsichtbarkeit aufheben
  SetClrModulation(iOldModulation, pTarget);
  SetVisibility(iOldVisibility, pTarget);
  return(1);
}
The magic spell object exists until the spell has ended and then makes the clonk visible again. Also, if the spell object is deleted for other reasons (e.g. a scenario section change), the clonk is made visible in the Destruction callback (if this wasn't so, the clonk would remain invisible for ever). Also there is a Timer (defined in the DefCore) called every second. Notice you couldn't just have a single timer call to mark the end of the spell because timer intervals are marked in the engine beginning with the start of the round and you wouldn't know at what point within an engine timer interval the spell would start.
However, there are some problems with this implementation: for example, the magician can not cast a second invisibility spell while he's already invisible - the second spell would have practically no effect, because the end of the first spell would make the clonk visible again. The spell script would have to do some special handling for this case - but not only for multiple invisibility spells, but also for any other spell or script that might affect visibility or coloration of the clonk. Even if this spell would remember the previous value e.g. for coloration it could not handle a situation in which other scripts change the color of their own in the middle of the spell. The same problems occur when multiple scripts modify temporary clonk physcials such as jumping, walking speed, fight strength or visibility range, energy, magic energy etc. Using effects, these conflicts can be avoided.

Application

Effects are created using AddEffect and removed with RemoveEffect. If an effect was successfully created, the callback Fx*Start is made (* is replaced with the effect name). Depending on the parameters, there can also be an Fx*Timer call for continuous activity such as casting sparks, adjusting energy etc. Finally, when the effect is deleted, the callback Fx*Stop is made. Now, the invisibility spell implemented using effects:
/* Unsichtbarkeitszauber mit Effektsystem */
	
#strict

// EffectVars:
//   0 - Vorheriger Sichtbarkeitsstatus
//   1 - Vorherige Farbmodulation

public func Activate(pCaster, pCaster2)
{
  // Zauberer ermitteln
  if (pCaster2) pCaster = pCaster2;
  // Magie kann man hören, ganz klar ;)
  Sound("Magic*");
  // Effekt starten
  AddEffect("InvisPSpell", pCaster, 200, 1111, 0, GetID());
  // Fertig - das Zauberobjekt wird nun nicht mehr gebraucht
  return(RemoveObject());
}

protected func FxInvisPSpellStart(pTarget, iEffectNumber)
{
  // Vorherige Sichtbarkeit des Zauberers speichern
  EffectVar(0, pTarget, iEffectNumber) = GetVisibility(pTarget);
  var iOldMod = EffectVar(1, pTarget, iEffectNumber) = GetClrModulation(pTarget);
  // Zauberer unsichtbar machen
  SetVisibility(VIS_Owner() | VIS_Allies() | VIS_God(), pTarget);
  // Halbdurchsichtig bläulich für den Besitzer und Verbündete
  SetClrModulation(ModulateColor(iOldMod, RGBa(127,127,255,127)), pTarget);
  // Fertig
  return(1);
}

protected func FxInvisPSpellStop(pTarget, iEffectNumber)
{
  // Status wiederherstellen
  SetClrModulation(EffectVar(1, pTarget, iEffectNumber), pTarget);
  SetVisibility(EffectVar(0, pTarget, iEffectNumber), pTarget);
  // Fertig
  return(1);
}
In this case, the magic spell object only starts the effect, then deletes itself immediately. The engine ensures that there are no conflicts with multiple effects modifying the visibility: effects are stored in a stack which ensures that effects are always removed in the opposite order of their addition. For this, there are a couple of extra Start and Stop calls to be made which are explained in detail later.
This effects does not have a timer function. It does, however, define a timer interval of 1111 which will invoke the standard timer function after 1111 frames which will delete the effect. Alternatively, you could define a timer function as such:
protected func FxInvisPSpellTimer(pTarget, iEffectNumber)
{
  // Rückgabewert -1 bedeutet, dass der Effekt gelöscht wird
  return(-1);
}
To store the previous status of the target object, special storage space in EffectVar() is used. This is necessary because in this case the effect callbacks to not have any object script context. So you cannot access any object local variables in the effect callbacks - remember that the magic spell object which has created the effect is already deleted. If you require an object context in the effect callbacks you can specify one in AddEffect(). In that case, effect callbacks would be in object local context and the effect would automatically be deleted if the target object is destroyed.

Priorities

When creating an effect you always specify a priority value which determines the effect order. The engine ensures that effects with lower priority are added before effects with a higher priority - even if this means deleting an existing effect of higher priority. So if one effect colors the clonk green and another colors the clonk red, the result will be that of the effect with higher priority. If two effects have the same priority, the order is undefined. However, it is guaranteed that effects added later always notify the Fx*Effect callback of the same priority.
In the case of the red and green color, one effect could also determine the previous coloring and then mix a result using ModulateColor. But priorities also have another function: an effect of higher priority can prevent the addition of other effects of lower priority. This is done through the Fx*Effect callback. If any existing effect reacts to this callback with the return value -1, the new effect is not added (the same applies to the Start callback of the effect itself). Here an example:
/* Feuerimmunitätszauber */

#strict

public func Activate(pCaster, pCaster2)
{
  // Zauberer ermitteln
  if (pCaster2) pCaster = pCaster2;
  // Magie kann man hören, ganz klar ;)
  Sound("Magic*");
  // Effekt starten
  AddEffect("BanBurnPSpell", pCaster, 180, 1111, 0, GetID());
  // Fertig - das Zauberobjekt wird nun nicht mehr gebraucht
  return(RemoveObject());
}

protected func FxBanBurnPSpellStart(pTarget, iEffectNumber, iTemp)
{
  // Beim Start des Effektes: Clonk löschen, wenn er brennt
  if (!iTemp) Extinguish(pTarget);
  return(1);
}

protected func FxBanBurnPSpellEffect(szNewEffect, iEffectTarget, iEffectNumber, iNewEffectNumber, var1, var2, var3)
{
  // Feuer abblocken
  if (WildcardMatch(szNewEffect, "*Fire*")) return(-1);
  // Alles andere ist OK
  return();
}
This effect makes the clonk fire-proof for 30 seconds. The effect is implemented without any Timer or Stop callbacks as the complete functionality is achieved by simply blocking other effects which might have "Fire" as part of their name. This especially applies to the engine internal fire which has exactly the name "Fire". Of course, you could still add a Timer callback for graphic effects so the player can see that his clonk is immune. Also, you could create special visual effects when preventing incineration in FxBanBurnPSpellEffect. For the like:
[...]

protected func FxBanBurnPSpellEffect(szNewEffect, iEffectTarget, iEffectNumber, iNewEffectNumber, var1, var2, var3)
{
  // Nur Feuer behandeln
  if (!WildcardMatch(szNewEffect, "*Fire*")) return();
  // Beim Feuer haben die drei Extraparameter normalerweise folgende Bedeutung:
  // var1: iCausedBy           - Spieler, der für das Feuer verantwortlich ist
  // var2: fBlasted            - bool: Ob das Feuer durch eine Explosion zustande kam
  // var3: pIncineratingObject - Objekt: Anzündendes Objekt
  // Anzündendes Objekt löschen
  if (var3 && GetType(var3) == C4V_C4Object()) Extinguish(var3);
  // Feuer abblocken
  return(-1);
}
This would even delete all burning objects which would otherwise incinerate the target object. The type check for var3 avoids possible conflicts with other "Fire" effects that might have differing parameters. Obviously, conflict situations like this should be avoided at all cost.
The following table contains general guidelines for priorities in effects of the original pack:
Effect Priority
Short special effects 300-350
Effects which cannot be banned 250-300
Magic ban spell 200-250
Permanent magic ban spell 180-200
Short term, benevolent magic effects 150-180
Short term, malevolent magic effects 120-150
Normal Effects 100-120
Fire as used by the engine 100
Permanent magic effects 50-100
Permanent other effects 20-50
Internal effects, data storage etc. 1
Generally, effect priorities should be chosen by dependency: if one effect should prevent another it needs a higher priority to do this (even if it is a permanent effect). Short term effects should have a higher priority than long term effects so that short term changes in the object are visible on top of long term effects.
The engine internal fire is of priority 100. So a magic fire which also uses the properties of the engine fire should have a slightly higher priority and should call the respective FxFire* functions within its callbacks. For proper functioning all effect callback (i.e. Start, Timer, and Stop) should be forwarded as each might depend on the action of the others. If this is not possible in your case, you should reimplement the complete fire functionality by script.
Effects with priority 1 are a special case: Other effects are never temporarily removed for them and they are never temporarily removed themselves.

Special Add/Remove Calls

For the engine to ensure that effects are always removed in opposite order, it might in some cases be necessary to temporarily remove and later re-add existing effects. In these situations, the scripter should obviously take care to remove any object changes and reapply them after re-adding so that other effects will behave accordingly.
Effects are also removed when the target object is deleted or dies - the cause for the removal is passed in the iReason parameter to the Remove function of the effect. This can be used e.g. to reanimate a clonk immediately upon his death:
/* Wiederbelebungszauber */

#strict

// EffectVars: 0 - Anzahl der zusätzlichen Wiederbelebungen

public func Activate(pCaster, pCaster2)
{
  // Zauberer ermitteln
  if (pCaster2) pCaster = pCaster2;
  // Magie kann man hören, ganz klar ;)
  Sound("Magic*");
  // Effekt starten
  AddEffect("ReincarnationPSpell", pCaster, 180, 0, 0, GetID());
  // Fertig - das Zauberobjekt wird nun nicht mehr gebraucht
  return(RemoveObject());
}

protected func FxReincarnationPSpellStart(pTarget, iEffectNumber, iTemp)
{
  // Nur beim ersten Start: Meldung
  if (!iTemp) Message("%s bekommt|ein Extraleben", pTarget, GetName(pTarget));
  return(1);
}

protected func FxReincarnationPSpellStop(pTarget, iEffectNumber, iReason, fTemp)
{
  // Nur beim Tod des Clonks
  if (iReason != 4) return(1);
  // Effekt erhalten, wenn der Clonk lebt: Wurde wohl durch einen anderen Effekt wiederbelebt :)
  if (GetAlive(pTarget)) return(-1);
  // Clonk wiederbeleben
  SetAlive(1, pTarget);
  // Energie geben
  DoEnergy(100, pTarget);
  // Nachricht
  Sound("Magic*", 0, pTarget);
  Message("%s|wurde wiederbelebt.", pTarget, GetName(pTarget));
  // Effekt wirkt nur einmal: Entfernen
  return(1);
}
This effect reanimates the clonk as many times as he has cast the reanimation spell.

Global Effects

Global effects are effects that are not bound to any target object. With global effects, too, priorities are observed and temporary Add/Remove calls might be necessary to ensure order. Simply imagine all global effects are attached to an imaginary object. Global effects are accessed whenever you specify 0 for the target object.
This can be used to make changes to gravity, sky color, etc. Here's an example for a spell that temporarily reduces gravity and then resets the original value:
/* Gravitationszauber */

#strict

// EffectVars: 0 - Vorherige Gravitation
//             1 - Änderung durch den Zauber

public func Activate(pCaster, pCaster2)
{
  // Magie kann man hören, ganz klar ;)
  Sound("Magic*");
  // Effekt global starten
  AddEffect("GravChangeUSpell", 0, 150, 37, 0, GetID(), -10);
  // Fertig - das Zauberobjekt wird nun nicht mehr gebraucht
  return(RemoveObject());
}

protected func FxGravChangeUSpellStart(pTarget, iEffectNumber, iTemp, iChange)
{
  // Anderen Gravitationseffekt suchen
  if (!iTemp)
  {
    var iOtherEffect = GetEffect("GravChangeUSpell", pTarget);
    if (iOtherEffect == iEffectNumber) iOtherEffect = GetEffect("GravChangeUSpell", pTarget, 1);
    if (iOtherEffect)
    {
      // Gravitationsänderung auf diesen Effekt aufrechnen
      EffectVar(1, pTarget, iOtherEffect) += iChange;
      SetGravity(GetGravity() + iChange);
      // Selbst entfernen
      return(-1);
    }
  }
  // Vorherige Gravitation sichern
  var iOldGrav = EffectVar(0, pTarget, iEffectNumber) = GetGravity();
  // Für nichttemporäre Aufrufe wird iChange übergeben, und auf den Änderungswert aufgerechnet
  if (iChange) EffectVar(1, pTarget, iEffectNumber) += iChange;
  // Gravitationsänderung setzen
  // Die Änderung kann in temporären Aufrufen auch ungleich iChange sein
  SetGravity(iOldGrav + EffectVar(1, pTarget, iEffectNumber));
  // Fertig
  return(1);
}

protected func FxGravChangeUSpellTimer(pTarget, iEffectNumber)
{
  // Gravitation in Richtung Normalwert schrauben
  var iGravChange = EffectVar(1, pTarget, iEffectNumber);
  // Fertig?
  if (Inside(iGravChange, -1, 1)) return(-1);
  // Anpassen
  var iDir = -iGravChange/Abs(iGravChange);
  EffectVar(1, pTarget, iEffectNumber) += iDir;
  SetGravity(GetGravity() + iDir);
  return(1);
}

protected func FxGravChangeUSpellStop(pTarget, iEffectNumber)
{
  // Gravitation Wiederherstellen
  SetGravity(EffectVar(0, pTarget, iEffectNumber));
  // Effekt entfernen
  return(1);
}
pTarget will be 0 in all these effect calls. You should still pass this parameter to calls such as EffectVar() for then it is also possible to attach effects to the magician or perhaps a magic tower. In this case, gravity would automatically be reset as soon as the magician dies or the magic tower is destroyed.

Adding Effects

In the previous example, several gravitational effects were combined so that the gravity change lasts longer if the spell is casted multiple times. Adding these effects cannot be done in the Effect callback because the gravitation effect might always be prevented by another effect with higher priority (e.g. a no-spells-whatsoever-effect). Through the special Fx*Add callback you can achieve the desired result more easily, or at least in a more structured fashion:
[...]

protected func FxGravChangeUSpellEffect(szNewEffect, pTarget, iEffectNumber)
{
  // Falls der neu hinzugefügte Effekt auch eine Gravitationsänderung ist, Interesse am Übernehmen anmelden
  if (szNewEffect eq "GravChangeUSpell") return (-3);
  // Ansonsten ignorieren
  return();
}

protected func FxGravChangeUSpellAdd(pTarget, iEffectNumber, szNewEffect, pTarget, iNewTimer, iChange)
{
  // Aufruf erfolgt, wenn der Effekt übernommen werden konnte
  // Gravitationsänderung auf diesen Effekt aufrechnen
  EffectVar(1, pTarget, iEffectNumber) += iChange;
  SetGravity(GetGravity() + iChange);  
  // Fertig
  return(1);
}
Returning -3 in the Fx*Effect callback will cause the Fx*Add callback to be invoked for the new effect. In this case the new effect is not actually created and the function AddEffect will return the effect number of the effect which has taken on the consequences of the new effect instead. As opposed to the method above this has the advantage that the return value can now be used to determine whether the effect has been created at all.

User Defined Properties

Effects can be easily classified by name. In this way, e.g. all magic spell effects can easily be found through the respective wildcard string. If, however, you want to create user-defined properties which also apply to existing effects you can do this by defining additional effect functions:
global func FxFireIsHot() { return(1); } // Feuer is heiß

// Funktion, die alle heißen Effekte vom Zielobjekt entfernt
global func RemoveAllHotEffects(pTarget)
{
  // Lokaler Aufruf
  if (!pTarget) pTarget=this();
  // Alle Effekte durchsuchen und die heißen entfernen
  var iEffect, i;
  while (iEffect = GetEffect("*", pTarget, i++))
    if (EffectCall(pTarget, iEffect, "IsHot"))
      RemoveEffect(0, pTarget, iEffect);
}
Using EffectCall() you can of course also call functions in the effect, e.g. to extend certain effects.

Blind Effects

Sometimes effects only need to be created in order to produce the respective callbacks in other effects - for example with magic spells which don't have any animation or long term effects but which nonetheless might be blocked by other effects. Example for the earthquake spell:
/* Erdbebenzauber */

#strict

public func Activate(object pCaster, object pCaster2)
{
  Sound("Magic1");
  // Effekt prüfen
  var iResult;
  if (iResult = CheckEffect("EarthquakeNSpell", 0, 150)) return(iResult!=-1 && RemoveObject());
  // Effekt ausführen
  if (GetDir(pCaster)==DIR_Left()) CastLeft(); else CastRight();
  // Zauberobjekt entfernen
  return(RemoveObject());
}
The return value of CheckEffect() is -1 if the effect was rejected and a positive value or -2 if the effect was accepted. In both cases the effect itself should not be executed, but in the latter case the Activate function may signal success by returning 1.

Extended Possibilities

As every effect has its own data storage, effects are also a way of attaching external data to objects without having to change the object definition for that. Also, simple calls can be delayed, e.g. for one frame after destruction of the object as is done at one place in the Knights pack:
// Der Aufruf von CastleChange muss verzögert erfolgen, damit das Teil zum Aufruf auch wirklich weg ist
// Ansonsten würden FindObject()-Aufrufe dieses Objekt noch finden
public func CastlePartDestruction()
{
  // Fundament?
  if (basement) 
  	RemoveObject(basement);
  // Globaler Temporäreffekt, wenn nicht schon vorhanden
  if (!GetEffect("IntCPW2CastleChange"))
  	AddEffect("IntCPW2CastleChange", 0, 1, 2, 0, CPW2);
  return(1);
}

protected func FxIntCPW2CastleChangeStop()
{
  // Alle BurgTeile benachrichtigen
  var pObj;
  while(pObj = FindObject(0, 0, 0, 0, 0, OCF_Fullcon(), 0,0, NoContainer(), pObj))
    pObj->~CastleChange();
  // Fertig
  return(1);
}
For this application, the effect name should start with "Int" (especially if working with global callbacks) followed by the id of the object to avoid any kind of name conflict with other effects.
Also, certain action can be taken at the death of an object without having to modify that object's definition. A scenario script might contain:
/* Szenarioscript */

#strict

protected func Initialize()
{
  // Alle Wipfe manipulieren
  var obj;
  while (obj = FindObject(WIPF, 0,0,0,0, OCF_Alive(), 0,0, 0, obj))
    AddEffect("ExplodeOnDeathCurse", obj, 20);
}

global func FxExplodeOnDeathCurseStop(pTarget, iEffectNumber, iReason)
{
  // Bumm!
  if (iReason == 4) Explode(20, pTarget);
  return(1);
}
All wipfs present at the beginning of the scenario will explode on death.

Naming

So that effects might properly recognize and manipulate each other you should stick to the following naming scheme ("*abc" means endings, "abc*" means prefixes, and "*abc*" means string parts which might occur anywhere in the name).
Name section Meaning
*Spell Magic effect
*PSpell Benevolent magic effect
*NSpell Malevolent magic effect
*USpell Neutral magic effect
*Fire* Fire effect - the function Extinguish() removes all effects of this name.
*Curse* Curse
*Ban* Effect preventing other effects (e.g. fire proofness or immunity)
Int* Internal effect (data storage etc.)
*Potion Magic potion
Warning: as function names may not be more than 100 characters in length (and you will lose oversight eventually), you should not stuff too much information into the effect name. Effect names are case sensitive. Also, you should avoid using any of these identifiers in your effect names if your effect doesn't have anything to do with them.

Callback Reference

The following callbacks are made by the engine and should be implemented in your script according to necessity. * is to be replaced by your effect name.

Fx*Start

int Fx*Start (object pTarget, int iEffectNumber, int iTemp, C4Value var1, C4Value var2, C4Value var3, C4Value var4);
Called at the start of the effect. pTarget is the target object of the effect. iEffectNumber is the effect index. These two parameters can be used to identify the effect, e.g. to manipulate corresponding variables in EffectVar().
In normal operation the parameter iTemp is 0. It is 1 if the effect is re-added after having been temporarily removed and 2 if the effect was temporarily removed and is now to be deleted (in this case a Remove call will follow).
Values var1 to var4 are the additional parameters passed to /() and can be custom used.
If iTemp is 0 and this callback returns -1 the effect is not created and the corrsponding AddEffect() call returns 0.

Fx*Stop

int Fx*Stop (object pTarget, int iEffectNumber, int iReason, bool fTemp);
When the effect is temporarily or permanently removed. pTarget again is the target object and iEffectNumber the index into the effects list of that object.
iReason contains the cause of the removal and can be one of the following values:
iReason Meaning
0 Normal removal
1 Temporary removal (fTemp is 1).
2 Not used
3 The target object has been deleted
4 The target object has died
The effect can prevent removal by returning -1. This will not help, however, in temporary removals or if the target object has been deleted.

Fx*Timer

int Fx*Timer (object pTarget, int iEffectNumber, int iEffectTime);
Periodic timer call, if a timer interval has been specified at effect creation. pTarget and iEffectNumber as usual.
iEffectTime specifies how long the effect has now been active. This might alternatively be determined using GetEffect().
If this function is not implemented or returns -1, the effect will be deleted after this call.

Fx*Effect

int Fx*Effect (string szNewEffectName, object pTarget, int iEffectNumber, int iNewEffectNumber, C4Value var1, C4Value var2, C4Value var3, C4Value var4);
A call to all effects of higher priority if a new effect is to be added to the same target object. szNewEffectName is the name of the new effect; iEffectNumber is the index of the effect being called; and iNewEffectNumber is the index of the new effect.
Warning: the new effect is not yet properly initialized and should not be manipulated in any way. Especially the priority field might not yet have been set. The iNewEffectNumber can however be used to request information via EffectCall(). In calls made by CheckEffect() iNewEffectNumber is always 0.
This function can return -1 to reject the new effect. As the new effect might also be rejected by other effects, this callback should not try to add effects or similar (see gravitation spell). Generally you should not try to manipulate any effects during this callback.
Return -2 or -3 to accept the new effect. As long as the new effect is not rejected by any other effect, the Fx*Add call is then made to the accepting effect, the new effect is not actually created, and the calling AddEffect function returns the effect index of the accepting effect. The return value -3 will also temporarily remove all higher prioriy effects just before the Fx*Add callback and re-add them later.
var1 bis var4 are the parameters passed to AddEffect()

Fx*Add

int Fx*Add (object pTarget, int iEffectNumber, string szNewEffectName, int iNewEffectTimer, C4Value var1, C4Value var2, C4Value var3, C4Value var4);
Callback to the accepting effect if that has returned -2 or -3 to a prior Fx*Effect call. iEffectNumber identifies the accepting effect to which the consequences of the new effect will be added; pTarget is the target object (0 for global effects).
iNewEffectTimer is the timer interval of the new effect; var1 to var4 are the parameters from AddEffect. Notice: in temporary calls, these parameters are not available - here they will be 0.
If -1 is returned, the accepting effect is deleted also. Logically, the calling AddEffect function will then return -2.

Fx*Damage

int Fx*Damage (object pTarget, int iEffectNumber, int iDmgEngy, int iCause, int iCausePlr);
Every effect receives this callback whenever the energy or damage value of the target object is to change. If the function is defined, it should then return whether to allow the change.
iDmgEngy is the change amount. Negative values are used for damage, positive values for healing (in case of living beings).
Energy values are exact, meaning 100,000 is the full energy value of a normal clonk of rank 10 (C4MaxPhysical). The conversion factor from GetEnergy to this value is 1,000.
This callback is made upon life energy changes in living beings and damage value changes in non-livings - but not vice versa. iCause contains the value change and reason:
Script constant iCause Meaning
FX_Call_DmgScript 0 Damage by script call DoDamage()
FX_Call_DmgBlast 1 Damage by explosion
FX_Call_DmgFire 2 Damage by fire
FX_Call_DmgChop 3 Damage by chopping (only trees)
FX_Call_EngScript 32 Energy value change by script call DoEnergy()
FX_Call_EngBlast 33 Energy loss by explosion
FX_Call_EngObjHit 34 Energy loss by object hit
FX_Call_EngFire 35 Energy loss by fire
FX_Call_EngBaseRefresh 36 Energy recharge at the home base
FX_Call_EngAsphyxiation 37 Energy loss by suffocation
FX_Call_EngCorrosion 38 Energy loss through acid
FX_Call_EngStruct 39 Energy loss of buildings (only "living" buildings)
FX_Call_EngGetPunched 40 Energy loss through clonk-to-clonk battle
Generally, the expression "iCause & 32" can be used to determine whether the energy or damage values were changed.
iCausePlr is the player number of the player who caused the change.
Using this callback, damage to an object can be prevented, lessened, or increased. You could deduct magic energy instead, transfer damage to other objects, or something similar.

Fx*Info

string Fx*Info(object pTarget, int iEffectNumber)
Is being called when the info of an object is shown via the context menu of the object target. The returned string is appended to the description as a separate line. This is used for example by the fire effect to show that an object is on fire.

Function Reference

There are the following functions for manipulation of effects:
Sven2, März 2004