Events (SourceMod Scripting)

To view all the events, click here.

Events are short, named messages sent by the server. Although they are used for internal message passing, they are also networked to clients.

All event natives are found in plugins/include/events.inc.

Introduction

Events are documented in .res files under a mod's resource folder. The "default" events are located in hl2/resource/gameevents.res and hl2/resource/serverevents.res. Mods can extend these events with their own.

For example, let's look at player_death from hl2/resource/gameevents.res:

"player_death"
{
	"userid"	"short"   	// user ID who died				
	"attacker"	"short"	 	// user ID who killed
}

Counter-Strike:Source extends this definition in cstrike/resource/modevents.res:

"player_death"
{
	"userid"	"short"   	// user ID who died				
	"attacker"	"short"	 	// user ID who killed
	"weapon"	"string" 	// weapon name killer used 
	"headshot"	"bool"		// signals a headshot
}

Note that the event is structured in the following format:

"name"
{
	"key1"	"valueType1"
	"key2"	"valueType2"
	...
}

Sending Events

Events are very easy to send. For example, let's say we want to send a death message using the player_death event from above. For Counter-Strike:Source, this would look like:

SendDeathMessage(attacker, victim, const String:weapon[], bool:headshot)
{
	new Handle:event = CreateEvent("player_death")
	if (event == INVALID_HANDLE)
	{
		return
	}
 
	SetEventInt(event, "userid", GetClientUserId(victim))
	SetEventInt(event, "attacker", GetClientUserId(attacker))
	SetEventString(event, "weapon", weapon)
	SetEventBool(event, "headshot", headshot)
	FireEvent(event)
}

Notes:

• You don't need to call CloseHandle(), FireEvent() does this for us.
• Even though "userid" and "attacker" are shorts, we set them as ints. The term "short" is only used to tell the engine how many bytes of the integer are needed to be networked.
• It is possible for event creation to fail; this can happen if the event does not exist, or nothing is hooking the event. Thus, you should always make sure CreateEvent calls return a valid Handle.
• Most events use client userids instead of client indexes.
• By default, FireEvent() broadcasts messages to clients. This can be prevented by passing dontBroadcast as true.

Hooking Events

When hooking an event, there are three modes to choose from:

• Pre - Hook the event before it is fired.
• Post - Hook the event after it is fired.
• Post_NoCopy - Hook the event, but do not save any of its information (special optimization).

Hooking an event is usually done for one of the following goals. To get an idea of which mode to use, see the list below each goal:

• Blocking the event (preventing it from being fired)
  • Always Pre
• Rewriting the event (changing its parameters)
  • Always Pre
• Acting upon the event (doing something once the event is completed)
  • Pre if your action must come before the mod's action.
  • Post if your action must come after the mod's action.
  • PostNoCopy if your action is Post and only requires the event name.

As always, you do not need to unhook events when your plugin unloads. They are automatically removed.

Blocking Events

Blocking events is the easiest thing to do. Let's say we want to block death events that are headshots:

public OnPluginStart()
{
	HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre)
}
 
public Action:Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
	if (GetEventBool(event, "headshot"))
	{
		return Plugin_Handled
	}
	return Plugin_Continue
}

Rewriting Events

Rewriting events is just as easy -- events can be modified in pre hooks. For example, say we want to remove headshots from all events:

public OnPluginStart()
{
	HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre)
}
 
public Action:Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
	SetEventBool(event, "headshot", false)
	return Plugin_Continue
}

Post Hooks

Post hooks are default, and will usually be the most common usage. For example, say we want to print a message to every client that dies:

public OnPluginStart()
{
	HookEvent("player_death", Event_PlayerDeath)
}
 
public Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
	decl String:weapon[64]
	new victimId = GetEventInt(event, "userid")
	new attackerId = GetEventInt(event, "attacker")
	new bool:headshot = GetEventBool(event, "headshot")
	GetEventString(event, "weapon", weapon, sizeof(weapon))
 
	decl String:name[64]
	new victim = GetClientOfUserId(victimId)
	new attacker = GetClientOfUserId(attackerId)
	GetClientName(attacker, name, sizeof(name))
 
	PrintToConsole(victim,
		"You were killed by \"%s\" (weapon \"%s\") (headshot \"%d\")",
		name,
		weapon,
		headshot)
}

This will print a message to a player's console telling them who killed them, with what weapon, and whether it was a headshot or not.

Note that the return value for post hooks is ignored, so the Action tag is not needed.

PostNoCopy Hooks

Lastly, there are some hooks where the only piece of information needed is the name of the event. PostNoCopy is a special optimization for this case. When transitioning from Pre to Post, SourceMod must duplicate the event and all of its key/value pairs. PostNoCopy prevents that sequence from happening.

For example, let's say we want to find when a certain sequence of events is called.

public OnPluginStart()
{
	HookEvent("game_newmap", GameEvents, EventHookMode_PostNoCopy)
	HookEvent("game_start", GameEvents, EventHookMode_PostNoCopy)
	HookEvent("game_end", GameEvents, EventHookMode_PostNoCopy)
	HookEvent("game_message", GameEvents, EventHookMode_PostNoCopy)
}
 
public GameEvents(Handle:event, const String:name[], bool:dontBroadcast)
{
	PrintToServer("Event has been fired (event \"%s\") (nobcast \"%d\")", name, dontBroadcast)
}

Note that like normal Post hooks, there is no return value needed. However, the event parameter for PostNoCopy will always be equal to INVALID_HANDLE. Thus, the name parameter must be used instead of GetEventName.