Creating new effects in SourcePawn

The SourcePawn API allows developers to access effect data such as name, duration, or a custom-defined data section. It is the most flexible API for effects, but requires a bit more setup.

The ChaosEffect struct is always passed into callbacks as the first parameter. This struct should not be modified, as changes to it may affect subsequent effect activations.

To get started, create a config entry in the effect config, with the section name being the unique ID of the effect. In addition, each effect requires at least a name and an effect_class. The effect class will be used to find your effect's callbacks and should be uniquely named. All other keys are optional and will be initialized to a default value.

Not specifying the effect duration (or setting it to 0) will create a one-shot effect.

"my_effect"
{
    "name"          "#Chaos_Effect_MyEffect"
    "duration"      "60"
    "effect_class"  "MyEffect"
    "data"
    {
        "key"    "value"
    }
}

Then, create a new file for your effect in scripting/chaos/effects. Each function name has to be in the format of <effect>_<callback>, e.g. ExampleEffect_OnStart. None of the callbacks are required, so you can choose the ones you need.

#pragma semicolon 1
#pragma newdecls required

// Called once on plugin start and config reload
public bool MyEffect_Initialize(ChaosEffect effect, GameData gameconf)
{
    // Returning `false` will make the effect unavailable
    if (!gameconf)
        return false;

    // Returning `true` will add the effect to the effects list
    return true;
}

// Called once when the effect starts
public bool MyEffect_OnStart(ChaosEffect effect)
{
    // Returning `false` will prevent the effect from starting
    if (!GameRules_GetProp("m_nForceUpgrades") && !GameRules_GetProp("m_bPlayingMannVsMachine"))
        return false;
    
    // Returning `true` will allow the effect to start
    return true;
}

// Called repeatedly every frame
public void MyEffect_Update(ChaosEffect effect)
{
    // Your code here
}

// Called once when the effect ends (except for one-shot effects)
public void MyEffect_OnEnd(ChaosEffect effect)
{
    // Your code here
}

Finally, include your effect at the top of chaos.sp. Please make sure you order it alphabetically.

#include "chaos/effects/myeffect.sp"