Core Events
Core events are SwiftlyS2's own engine/framework callbacks - client lifecycle, entity lifecycle, convar and command changes, console output, server startup, tick/world update - separate from the CS2 game events system. They're exposed through Core.Event (APIIEventSubscriber), a set of plain C# events.
Subscribing
Subscribe with a plain +=, or with [EventListener<T>] where T is the matching delegate from EventDelegates.
public override void Load(bool hotReload)
{
Core.Event.OnClientConnected += OnClientConnected;
}
private void OnClientConnected(IOnClientConnectedEvent @event)
{
Console.WriteLine($"Client connected: {@event.PlayerId}");
}Match the delegate signature exactly - EventDelegates.OnClientConnected is void(IOnClientConnectedEvent @event); OnTick, OnWorldUpdate, OnSteamAPIActivated and OnStartupServer take no parameters at all, so their handlers are void ().
APIEventListener`1 takes no arguments and its type parameter is constrained to delegates (where T : Delegate); a method can carry only one of them (AllowMultiple = false) - use += when a single method or instance has to listen to several events.
Attribute handlers are discovered on registered instances: your plugin class is registered automatically, any other class must be passed to Core.Registrator.Register(instance) - see Using Attributes.
Blocking a Client from Joining
Some events expose a settable Result to reject the action. APIIOnClientConnectedEvent is the client-lifecycle one - set it to HookResult.Stop or HookResult.CancelOriginal:
[EventListener<EventDelegates.OnClientConnected>]
public void OnClientConnected(IOnClientConnectedEvent @event)
{
if (IsBanned(@event.PlayerId))
{
@event.Result = HookResult.Stop;
}
}The other events with a settable Result are OnCommandExecuteHook (only in the Pre pass) and the obsolete OnEntityTakeDamage, OnWeaponServicesDropWeaponHook, OnEntityIdentityAcceptInputHook and OnEntityFireOutputHook. What each APIHookResult value does to the remaining hooks and the original call is described in Native Functions and Hooks.
Unsubscribing
-= only removes a subscription added with += - keep a reference to the exact delegate instance:
private EventDelegates.OnClientConnected? _onClientConnected;
public override void Load(bool hotReload)
{
_onClientConnected = OnClientConnected;
Core.Event.OnClientConnected += _onClientConnected;
}
public override void Unload()
{
if (_onClientConnected != null)
Core.Event.OnClientConnected -= _onClientConnected;
}The framework tears down every listener a plugin registered on hot reload or unload automatically - unsubscribe manually only to stop listening earlier.
Hot Path Events
OnTick, OnWorldUpdate, and the obsolete OnClientProcessUsercmds are the hot-path callbacks - the first two fire every tick/frame, OnClientProcessUsercmds once per user-command batch of a client. Keep handlers allocation-free and cheap; push anything heavier to a scheduled task or a flag.
OnTick doesn't run while the server is in hibernation, OnWorldUpdate does.
Deprecated Hook-Style Events
Several Core.Event members that used to be the only way to intercept a native call are [Obsolete] in favor of the more structured Core.GameHooks categories - separate pre/post delegates and a richer context object instead of one generic event:
| Obsolete event | Use instead |
|---|---|
OnClientProcessUsercmds | Core.GameHooks.Controller.ProcessUsercmds |
OnEntityTakeDamage | Core.GameHooks.Entities.TakeDamage |
OnItemServicesCanAcquireHook | Core.GameHooks.Items.CanAcquire |
OnWeaponServicesCanUseHook | Core.GameHooks.Weapons.CanUse |
OnWeaponServicesDropWeaponHook | Core.GameHooks.Weapons.Drop |
OnEntityStartTouch / OnEntityTouch / OnEntityEndTouch | Core.GameHooks.Entities.{StartTouch,Touch,EndTouch} |
OnMovementServicesRunCommandHook | Core.GameHooks.Movement.RunCommand |
OnPlayerPawnPostThink | Core.GameHooks.Pawn.PostThink |
OnEntityIdentityAcceptInputHook | Core.GameHooks.Entities.AcceptInput |
OnEntityFireOutputHook | Core.GameHooks.Entities.FireOutput |
The parameter interfaces of these events are [Obsolete] as well, so a handler that takes one of these event objects produces a compiler warning too.
Their event objects still carry the parameters they always did:
| Obsolete event | Event object | Members |
|---|---|---|
OnClientProcessUsercmds | APIIOnClientProcessUsercmdsEvent | PlayerId (int), Usercmds (List<CSGOUserCmdPB>), Paused (bool), Margin (float) |
OnEntityTakeDamage | APIIOnEntityTakeDamageEvent | Entity (CEntityInstance), Info (ref CTakeDamageInfo), DamageResult (ref CTakeDamageResult), settable Result (HookResult) |
OnEntityStartTouch / OnEntityTouch / OnEntityEndTouch | APIIOnEntityStartTouchEvent / APIIOnEntityTouchEvent / APIIOnEntityEndTouchEvent | Entity (CBaseEntity), OtherEntity (CBaseEntity) |
OnItemServicesCanAcquireHook | APIIOnItemServicesCanAcquireHookEvent | ItemServices (CCSPlayer_ItemServices), EconItemView (CEconItemView), WeaponVData (CCSWeaponBaseVData?), AcquireMethod (AcquireMethod), OriginalResult (AcquireResult), SetAcquireResult(AcquireResult) |
OnWeaponServicesCanUseHook | APIIOnWeaponServicesCanUseHookEvent | WeaponServices (CCSPlayer_WeaponServices), Weapon (CCSWeaponBase), OriginalResult (bool), SetResult(bool) |
OnWeaponServicesDropWeaponHook | APIIOnWeaponServicesDropWeaponHook | WeaponServices (CCSPlayer_WeaponServices), Weapon (CBasePlayerWeapon?), SwappingWeapon (bool), settable Result (HookResult) |
OnMovementServicesRunCommandHook | APIIOnMovementServicesRunCommandHookEvent | MovementServices (CCSPlayer_MovementServices), ButtonState (CInButtonState), UserCmdPB (CSGOUserCmdPB) |
OnPlayerPawnPostThink | APIIOnPlayerPawnPostThinkHookEvent | PlayerPawn (CCSPlayerPawn) |
OnEntityIdentityAcceptInputHook | APIIOnEntityIdentityAcceptInputHookEvent | Identity (CEntityIdentity), EntityInstance (CEntityInstance), DesignerName (string), InputName (string), Activator (CEntityInstance?), Caller (CEntityInstance?), VariantValue (ref CVariant<CVariantDefaultAllocator>), OutputId (int), settable Result (HookResult) |
OnEntityFireOutputHook | APIIOnEntityFireOutputHookEvent | EntityIO (ref CEntityIOOutput), DesignerName (string), OutputName (string), Activator (CEntityInstance?), Caller (CEntityInstance?), VariantValue (ref CVariant<CVariantDefaultAllocator>), Delay (float), settable Result (HookResult) |
IOnEntityTakeDamageEvent.DamageResult throws InvalidOperationException when the native call did not provide a result - the Core.GameHooks.Entities.TakeDamage context exposes the nullable native result instead.
Event Reference
Each parameter interface lives under SwiftlyS2.Shared.Events and exposes only the fields relevant to that callback. The delegate on APIEventDelegates has the same name as the Core.Event member - OnEntityFireOutputHook is the exception, its delegate is EventDelegates.OnEntityFireOutputHookEvent.
Client Lifecycle
OnClientConnected- APIIOnClientConnectedEvent:PlayerId(int), settableResult(HookResult).OnClientDisconnected- APIIOnClientDisconnectedEvent:PlayerId(int),Reason(ENetworkDisconnectionReason).OnClientPutInServer- APIIOnClientPutInServerEvent:PlayerId(int),Kind(APIClientKind).OnClientSteamAuthorize- APIIOnClientSteamAuthorizeEvent:PlayerId(int).OnClientSteamAuthorizeFail- APIIOnClientSteamAuthorizeFailEvent:PlayerId(int).OnClientKeyStateChanged- APIIOnClientKeyStateChangedEvent:PlayerId(int),Key(APIKeyKind),Pressed(bool).OnClientVoice- APIIOnClientVoiceEvent:PlayerId(int).
Entity Lifecycle
OnEntityCreated- APIIOnEntityCreatedEvent:Entity(CEntityInstance). The entity isn't fully initialized yet - do your work on the next tick and check its validity there.OnEntitySpawned- APIIOnEntitySpawnedEvent:Entity(CEntityInstance).OnEntityDeleted- APIIOnEntityDeletedEvent:Entity(CEntityInstance).OnEntityParentChanged- APIIOnEntityParentChangedEvent:Entity(CEntityInstance),NewParent(CEntityInstance?).
ConVar and Commands
OnConVarCreated- APIIOnConVarCreated:ConVarName(string).OnConVarValueChanged- APIIOnConVarValueChanged:ConVarName(string),PlayerId(int, the client that made the change),NewValueandOldValue(bothstring).OnConCommandCreated- APIIOnConCommandCreated:CommandName(string).OnCommandExecuteHook- APIIOnCommandExecuteHookEvent:Command(ref CCommand),HookMode(APIHookMode), settableResult(HookResult).HookModetells you whether this is thePreor thePostpass, andResultcan only be changed inPre.OnConsoleOutput- APIIOnConsoleOutputEvent:Message(string). Callbacks run on the dedicated console dispatch thread - schedule the work onto the game thread before touching game-thread-only APIs (see Thread Safety).
The convar events are covered in more detail in Convars.
Server and World
OnMapLoad- APIIOnMapLoadEvent:MapName(string).OnMapUnload- APIIOnMapUnloadEvent:MapName(string).OnPrecacheResource- APIIOnPrecacheResourceEvent:AddItem(string path)adds a resource to the precache list.OnStartupServer,OnTick,OnWorldUpdate,OnSteamAPIActivated- no event object, the handler takes no parameters.
UI
OnCustomHudClicked- APIIOnCustomHudClickedEvent:PlayerId(int),CustomHudLayout(CCSCustomHudLayout),ButtonId(string). See Custom HUD.
ClientKind and KeyKind
Two enums are carried by event objects rather than configured:
APIClientKind is reported by IOnClientPutInServerEvent.Kind:
| Value | Number |
|---|---|
Player | 0 |
Bot | 1 |
Unknown | 2 |
APIKeyKind is reported by IOnClientKeyStateChangedEvent.Key:
Mouse1, Mouse2, Space, Ctrl, W, A, S, D, E, Esc, R, Alt, Shift, Weapon1, Weapon2, Grenade1, Grenade2, Tab, F