swiftlys2/docs/api/releases/features/ai/

Game Events

Game events are a legacy Source 2 mechanism and Valve has been retiring them over time - some events no longer fire in current CS2 builds. Prefer Game Hooks or Core Events when an equivalent exists.

SwiftlyS2 generates a strongly-typed interface for every CS2 game event, exposed through the plugin-scoped Core.GameEvent service (APIISwiftlyCore.GameEvent, type APIIGameEventService). Every generated event implements APIIGameEvent`1.

Firing Events

Three targets, each with the same four members:

  • Fire<T>() / Fire<T>(Action<T>) and FireAsync<T>() / FireAsync<T>(Action<T>) - broadcast to every player.
  • FireToPlayer<T>(int slot) / FireToPlayer<T>(int slot, Action<T>) and their FireToPlayerAsync counterparts - a single player slot.
  • FireToServer<T>() / FireToServer<T>(Action<T>) and their FireToServerAsync counterparts - server-side only.

The Action<T> overloads configure the event before it is sent, and every Async member returns Task for off-main-thread use - the sync members are marked [ThreadUnsafe], see Thread Safety.

// To everyone, with an optional configure callback
Core.GameEvent.Fire<EventShowSurvivalRespawnStatus>(@event =>
{
    @event.LocToken = "survival_respawn_status";
    @event.Duration = 5;
});
 
// To one player slot
Core.GameEvent.FireToPlayer<EventShowSurvivalRespawnStatus>(0, @event =>
{
    @event.LocToken = "private_status";
});
 
// Server-side only
Core.GameEvent.FireToServer<EventShowSurvivalRespawnStatus>();
 
// Off the main thread
await Core.GameEvent.FireAsync<EventShowSurvivalRespawnStatus>();

The event instance passed to a configure callback is only valid for that callback's duration - don't stash and read it later.

Every event has a settable DontBroadcast flag - set it inside the configure callback to build the event without broadcasting it to clients.

Hooking Events

Register hooks by attribute or manually through the service. The handler is the APIIGameEventService.GameEventHandler delegate - HookResult (T eventObj), with T constrained to IGameEvent<T> - and returns APIHookResult. Hooks run in Pre (0) or Post (1) mode (APIHookMode): Pre runs before the game processes the event, Post after.

[GameEventHandler(HookMode.Pre)]
public HookResult OnPlayerDeathPre(EventPlayerDeath @event)
{
    Console.WriteLine($"victim={@event.UserId}, attacker={@event.Attacker}");
    return HookResult.Continue;
}
 
[GameEventHandler(HookMode.Post)]
public HookResult OnPlayerDeathPost(EventPlayerDeath @event)
{
    Console.WriteLine($"headshot={@event.Headshot}, weapon={@event.Weapon}");
    return HookResult.Continue;
}

APIGameEventHandler takes the mode in its constructor, exposes it as the settable HookMode property, and takes the event type from the method's single parameter - a method can carry only one (AllowMultiple = false). The attribute-based equivalents of HookPre/HookPost are discovered on the registered instances of your plugin - see Using Attributes.

In a pre hook, HookResult.Stop cancels the event and skips the remaining hooks; HookResult.CancelOriginal cancels it but still runs them, and HookResult.Handled skips them while letting the event through. Stop and Handled have no effect in post hooks.

Drop every hook registered for an event type at once:

Core.GameEvent.UnhookPre<EventPlayerDeath>();
Core.GameEvent.UnhookPost<EventPlayerDeath>();

Checking Event Listeners

APIIGameEventService.IsListeningToEvent checks whether a player slot is listening for an event - by event name ("player_death"), or through the typed overload that takes the event type as a generic argument:

bool byName = Core.GameEvent.IsListeningToEvent(0, "player_death");
bool typed = Core.GameEvent.IsListeningToEvent<EventPlayerDeath>(0);

Reading and Setting Event Data

Every generated event implements APIIGameEvent`1, giving you Accessor (APIIGameEventAccessor) and a settable DontBroadcast flag. Recognized fields get typed properties directly on the event - for EventPlayerDeath: int UserId/Attacker/Assister, string Weapon, bool Headshot, float Distance, int ActualDmgHealth, plus IPlayer? convenience wrappers (UserIdPlayer, AttackerPlayer, AssisterPlayer) resolved through the player manager:

[GameEventHandler(HookMode.Post)]
private HookResult OnPlayerDeath(EventPlayerDeath @event)
{
    if (@event.AttackerPlayer is { } attacker && @event.UserIdPlayer is { } victim)
    {
        Console.WriteLine($"{attacker.Name} killed {victim.Name} with {@event.Weapon}");
    }
 
    return HookResult.Continue;
}

Fall back to Accessor for fields without a generated property - it reads and writes the raw payload fields by name (the same DontBroadcast flag sits on it too):

string weapon = @event.Accessor.GetString("weapon");
int attackerSlot = @event.Accessor.GetPlayerSlot("attacker");
 
// e.g. in a pre hook, before the game processes the event
@event.Accessor.SetBool("headshot", true);

Every getter takes the field name, every setter the field name and the value:

Getter / setterPayload type
GetBool / SetBoolbool
GetInt32 / SetInt32int
GetUInt64 / SetUInt64ulong
GetFloat / SetFloatfloat
GetString / SetStringstring
GetEntity<K> / SetEntity<K>entity, K : CEntityInstance
GetEntityIndex / SetEntityIndexint
GetPlayerSlot / SetPlayerSlotint
GetPtr / SetPtrnint

APIIGameEventAccessor also exposes read-only helpers, resolved through the player manager: GetPlayer(key) (IPlayer?), GetPlayerController(key) (CCSPlayerController), GetPlayerPawn(key) (CCSPlayerPawn), GetPawnEntityIndex(key) (int), IsReliable() and IsLocal() (bool). Player references are stored as slots in the payload, which is why userid/playerid are read with GetPlayerSlot/GetPlayer (see Terminologies).

As a native wrapper, the accessor is also an APIINativeHandle - IsValid and Address are available on it.