Effect Configuration

Every effect is a section in addons/sourcemod/configs/chaos/effects.cfg, inside the top-level "effects" block. SourcePawn and VScript effects use the same file and the same keys. Adding effects without code shows a complete entry.

The plugin only reads this file when it loads, so run sm plugins reload chaos after editing it.

Keys

Key	Meaning	Default
Section name	The effect's unique ID, used by the admin commands and in logs. Use lowercase letters, digits and underscores like the existing entries.	required
name	Display name, as a phrase key or plain text. See Names and translations.	none
enabled	0 keeps the effect out of the random pick. Admins can still force it.	1
duration	How long the effect lasts, in seconds. Other active effects can change it when it starts.	0, a one-shot
cooldown	How many activations must pass before the random pick can choose the effect again. See Cooldown.	-1, which uses sm_chaos_effect_cooldown
meta	1 makes the effect a meta effect.	0
effect_class	The SourcePawn class that implements the effect. See Creating new effects in SourcePawn.	none
script_file	The script that implements the effect, as a file name in scripts/vscripts/chaos/effects without .nut. See Creating new effects in VScript.	none
start_sound	Sound that plays when the effect starts. See Sounds.	none
end_sound	Sound that plays when a timed effect ends.	none
claims	Comma-separated list of claims. See Claims and conflicts.	none
data	Settings for the class or script. See Data.	none

Every effect needs an effect_class, a script_file, or both. With both, the class runs before the script and only one of them can get data. See Combining with an effect class.

Unknown keys are ignored, so a misspelled key silently falls back to its default.

One-shots

An effect without a duration, or with "duration" "0", is a one-shot. It runs its start code once and is then done. Nothing undoes its changes, and its end_sound never plays. It checks its claims before it starts but doesn't hold them afterwards.

Cooldown

Cooldowns count activations, not seconds. After an effect ends, or after it runs if it's a one-shot, that many other effects must activate before the random pick can choose it again. Regular and meta effects count separately, so a meta effect's cooldown only goes down when other meta effects activate. "cooldown" "0" means no cooldown. Forced effects ignore cooldowns.

Data

data holds the settings for the class or script. Each class or script reads its own keys, and its source file shows which ones.

For SourcePawn, data is a KeyValues section, like in the example below. The class reads it with effect.OpenData().

For VScript, data is a string holding a Squirrel table literal. It is evaluated each time the effect starts, so it can call functions like Vector or RandomFloat. Write \" for a quote inside it, as this entry does:

		"data"			"{ model = \"models/bots/skeleton_sniper/skeleton_sniper.mdl\" }"

See Creating new effects in VScript for how a script reads it.

Sounds

start_sound plays for everyone right after the effect starts. When a timed effect ends, its start_sound is stopped and its end_sound plays.

Both take a game sound name or a file path relative to sound/. They are not added to the downloads table, so use sounds that ship with TF2 or get custom sounds to your players some other way.

Validation

Entries the plugin can't use are skipped when it loads, and the reason is logged. Test a new entry by forcing it with sm_chaos_forceeffect <id>, and see Debugging for where errors show up.

Names and translations

name is either a phrase key from chaos.phrases.txt or plain text. If a phrase with that key exists, every player sees it in their own language. Otherwise the text is shown as written. An effect without a name still runs, but players aren't shown what it is.

To add a phrase, add a section named after the key to the "Phrases" block, with one entry per language:

	"#Chaos_Effect_MarkedForDeath"
	{
		"en"		"Marked for Death"
	}

Name new keys like the existing ones. To translate, add more language codes to each section, or add an addons/sourcemod/translations/<language code>/chaos.phrases.txt file, as with any SourceMod translation. Reloading the plugin doesn't reread translations, so run sm_reload_translations or change the map after editing them.

A SourcePawn class can also change the displayed name at runtime with ModifyEffectName. See Creating new effects in SourcePawn.

Meta effects

"meta" "1" marks an effect that changes how Chaos itself runs. Meta effects are only picked by their own timer, which sm_chaos_meta_effect_interval and sm_chaos_meta_effect_chance control, as described in Server Setup.

Claims and conflicts

Many effects change something and put it back when they end, such as the camera or a ConVar. If two of them overlap, the first one to end restores its saved value and breaks the one that is still running. Claims prevent that.

A claim is a string that names such a resource. A timed effect holds its claims while it runs, and an effect will not start while another active effect holds one of the same claims. The random pick then chooses another effect. Forcing an effect ends the effects that hold its claims instead.

		"claims"		"player:jumping,player:step_size"

A SourcePawn class can also derive claims from the effect's data with GetClaims. These are merged with the claims key, which then only needs whatever else the effect touches.

Claims only conflict when they are the same string. Before you make up a new one, look at the existing claims keys in effects.cfg and the GetClaims functions in the class files, and reuse the claim that covers the same thing so the two effects can't overlap.

Adding effects without code

Many classes and scripts are generic and read their behavior from data, so you can often add a new effect by reusing one with different settings.

For example, the AddCond class adds the TF2 conditions listed in its data to every player while the effect runs. This entry uses it to mark everyone for death:

	"marked_for_death"
	{
		"name"			"#Chaos_Effect_MarkedForDeath"
		"duration"		"30"
		"effect_class"	"AddCond"
		"data"
		{
			"conditions"
			{
				"TF_COND_MARKEDFORDEATH"	"30"
			}
		}
	}

Under conditions, the key is only a label and the value is the condition's number. AddCond derives a claim for every condition it adds, so this entry needs no claims key. Add the phrase from Names and translations, reload the plugin and translations, then force marked_for_death to try it.

To find out which data keys a class or script reads, look at the existing entries that use it in effects.cfg and at its source file in scripting/chaos/effects or scripts/vscripts/chaos/effects. Derived claims only cover what the class itself changes. If your settings also affect something like the camera or movement, add those claims the way the existing entries for that class do.

When nothing fits, write your own effect in SourcePawn or VScript.