Writing Multi-Game SourceMod Plugins

Different Source games tend to have different quirks. This page discusses the more common quirks you'll run into.

Detecting the current game

In order to use what you learn from this document, you will need to detect which game the plugin is running on.

To detect the current game, use the GetEngineVersion() function, like this:

EngineVersion g_EngineVersion;
 
public void OnPluginStart()
{
    g_EngineVersion = GetEngineVersion();
}

This isn't always necessary for games that use different events, but it's still a good idea.

Round Start

Most plugin writers assume that hooking round_start will make things work on all games. Those plugin writers would be wrong.

Several games use other events instead or have behavior that needs to be taken into account.

Game	Fires round_start?	Alternate Event	Extra Quirks
Half-Life 2: DeathMatch	Yes	teamplay_round_start	teamplay_round_start is only fired for Team Deathmatch
Day of Defeat: Source	No	dod_round_start
Team Fortress 2	No	teamplay_round_start	full_reset will be false if this is not the first round of a multi-round map. In Arena mode, the arena_round_start event fires when players can start moving.
Counter-Strike: Global Offensive	Yes		round_start is fired during warmup round

Round End

round_end, like round_start, isn't the same across all games.

Most of the time, winner is the team ID of the winning team: 0 for stalemate, 2 for team 1 (Combine, Allies, Terrorists, RED, or Survivors), or 3 for team 2 (Rebels, Axis, Counter-Terrorists, BLU, or Infected).

Game	Fires round_end?	Alternate Event	Extra Quirks
Half-Life 2: DeathMatch	Yes		winner is a userid for Deathmatch or a team ID for Team Deathmatch
Day of Defeat: Source	No	dod_round_win	team is the winning team.
Team Fortress 2	No	See next section	See next section
Nuclear Dawn	No	round_win	team is the winning team. type is the win reason.

Team Fortress 2

Round End is so complicated in Team Fortress 2 that I'm giving it its own section. TF2 has not just one, but four different events for round end.

Game Mode	Event	Quirks
All	teamplay_round_win	team is the winning team. winreason was only recently fixed and its meaning depends on the game mode.
All but Arena or MvM	teamplay_win_panel	Win Panel screen, includes each team's score and the scores of the top 3 players. winning_team is the winning team. winreason includes captured all points, time ran out, captured flags, etc...
Arena	arena_win_panel	Arena Win Panel screen, includes each team's score and the scores of the top 3 players for each team. winning_team is the winning team. winreason can only be killed all players on the other team and captured point.
MvM	pve_win_panel	MvM Win Panel screen. winning_team is the winning team. Most data is not present in this event and is instead interpolated from the CTFPlayerResource netprops.

player_death

All games appear to use the player_death event, but the fields available to each game vary radically.

The quirks you need to know about are:

Detecting Fake Deaths

Team Fortress 2 introduced the concept of fake deaths. In order to detect if a death was fake, you need to do something like this:

#include <tf2_stocks>
 
// Hook the "player_death" event during OnPluginStart and pass in the following callback:
public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
    bool bFake = g_EngineVersion == Engine_TF2 && (event.GetInt("death_flags") & TF_DEATHFLAG_DEADRINGER);
    if (bFake)
    {
        // Do stuff on faked death
    }
    // do other stuff
}

Detecting Headshots

Not all games support headshots, but those that do have them done differently.

player_death

Headshots can be detected in player_death similarly to this:

#include <tf2_stocks>
 
// Hook the "player_death" event during OnPluginStart and pass in the following callback:
public Action Event_PlayerDeath(Event event, const char[] name, bool dontBroadcast)
{
    bool bHeadshot;
 
    switch (g_EngineVersion)
    {
        case Engine_CSS, Engine_CSGO, Engine_Left4Dead, Engine_Left4Dead2:
        {
            bHeadshot = event.GetBool("headshot");
        }
 
        case Engine_TF2:
        {
            bHeadshot = event.GetInt("customkill") == TF_CUSTOM_HEADSHOT;
        }
    }
 
    if (bHeadshot)
    {
        // This was a headshot, do something
    }
}

Unfortunately, some games don't appear to track headshots for death (Half-Life 2: DeathMatch for example).

player_hurt

player_hurt is a bit trickier.

#include <tf2_stocks>
 
#define HITGROUP_HEAD 1
 
// Hook "player_hurt", etc.
public Action Event_PlayerHurt(Event event, const char[] name, bool dontBroadcast)
{
    bool bHeadshot;
 
    switch (g_EngineVersion)
    {
        case Engine_CSS, Engine_CSGO, Engine_DODS, Engine_Left4Dead, Engine_Left4Dead2:
        {
            bHeadshot = event.GetInt("hitgroup") == HITGROUP_HEAD;
        }
 
        case Engine_TF2:
        {
            bHeadshot = event.GetInt("custom") == TF_CUSTOM_HEADSHOT;
        }
    }
 
    if (bHeadshot)
    {
        // This was a headshot, do something
    }
}

As you can see, more games support detecting if a shot was a headshot in player_hurt than player_death.

SDKHooks TraceAttack and OnTakeDamage

Headshots can be detected by TraceAttack or OnTakeDamage depending on the game.

Note: Changing damage and returning Plugin_Changed for either event will change the damage the player takes.

#include <sdkhooks>
 
#define HITGROUP_HEAD 1
 
public void OnClientPutInServer(int client)
{
    switch (g_EngineVersion)
    {
        case Engine_CSS, Engine_CSGO, Engine_DODS, Engine_Left4Dead, Engine_Left4Dead2:
        {
            SDKHook(client, SDKHook_TraceAttack, TraceAttack);
        }
        case Engine_TF2:
        {
            SDKHook(client, SDKHook_OnTakeDamage, OnTakeDamage);
        }
    }
 
}
 
public Action TraceAttack(int victim, int &attacker, int &inflictor, float &damage, 
        int &damagetype, int &ammotype, int hitbox, int hitgroup)
{
    bool bHeadshot = hitgroup == HITGROUP_HEAD;
 
    if (bHeadshot)
    {
        // This was a headshot, do something.
    }
 
    return Plugin_Continue;
}
 
public Action OnTakeDamage(int victim, int &attacker, int &inflictor, float &damage, 
        int &damagetype, int &weapon, float damageForce[3], float damagePosition[3], int damagecustom)
{
    bool bHeadshot = damagecustom == TF_CUSTOM_HEADSHOT;
 
    if (bHeadshot)
    {
        // This was a headshot, do something
    }
 
    return Plugin_Continue;
}