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

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 eventUse instead
OnClientProcessUsercmdsCore.GameHooks.Controller.ProcessUsercmds
OnEntityTakeDamageCore.GameHooks.Entities.TakeDamage
OnItemServicesCanAcquireHookCore.GameHooks.Items.CanAcquire
OnWeaponServicesCanUseHookCore.GameHooks.Weapons.CanUse
OnWeaponServicesDropWeaponHookCore.GameHooks.Weapons.Drop
OnEntityStartTouch / OnEntityTouch / OnEntityEndTouchCore.GameHooks.Entities.{StartTouch,Touch,EndTouch}
OnMovementServicesRunCommandHookCore.GameHooks.Movement.RunCommand
OnPlayerPawnPostThinkCore.GameHooks.Pawn.PostThink
OnEntityIdentityAcceptInputHookCore.GameHooks.Entities.AcceptInput
OnEntityFireOutputHookCore.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 eventEvent objectMembers
OnClientProcessUsercmdsAPIIOnClientProcessUsercmdsEventPlayerId (int), Usercmds (List<CSGOUserCmdPB>), Paused (bool), Margin (float)
OnEntityTakeDamageAPIIOnEntityTakeDamageEventEntity (CEntityInstance), Info (ref CTakeDamageInfo), DamageResult (ref CTakeDamageResult), settable Result (HookResult)
OnEntityStartTouch / OnEntityTouch / OnEntityEndTouchAPIIOnEntityStartTouchEvent / APIIOnEntityTouchEvent / APIIOnEntityEndTouchEventEntity (CBaseEntity), OtherEntity (CBaseEntity)
OnItemServicesCanAcquireHookAPIIOnItemServicesCanAcquireHookEventItemServices (CCSPlayer_ItemServices), EconItemView (CEconItemView), WeaponVData (CCSWeaponBaseVData?), AcquireMethod (AcquireMethod), OriginalResult (AcquireResult), SetAcquireResult(AcquireResult)
OnWeaponServicesCanUseHookAPIIOnWeaponServicesCanUseHookEventWeaponServices (CCSPlayer_WeaponServices), Weapon (CCSWeaponBase), OriginalResult (bool), SetResult(bool)
OnWeaponServicesDropWeaponHookAPIIOnWeaponServicesDropWeaponHookWeaponServices (CCSPlayer_WeaponServices), Weapon (CBasePlayerWeapon?), SwappingWeapon (bool), settable Result (HookResult)
OnMovementServicesRunCommandHookAPIIOnMovementServicesRunCommandHookEventMovementServices (CCSPlayer_MovementServices), ButtonState (CInButtonState), UserCmdPB (CSGOUserCmdPB)
OnPlayerPawnPostThinkAPIIOnPlayerPawnPostThinkHookEventPlayerPawn (CCSPlayerPawn)
OnEntityIdentityAcceptInputHookAPIIOnEntityIdentityAcceptInputHookEventIdentity (CEntityIdentity), EntityInstance (CEntityInstance), DesignerName (string), InputName (string), Activator (CEntityInstance?), Caller (CEntityInstance?), VariantValue (ref CVariant<CVariantDefaultAllocator>), OutputId (int), settable Result (HookResult)
OnEntityFireOutputHookAPIIOnEntityFireOutputHookEventEntityIO (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

Entity Lifecycle

ConVar and Commands

  • OnConVarCreated - APIIOnConVarCreated: ConVarName (string).
  • OnConVarValueChanged - APIIOnConVarValueChanged: ConVarName (string), PlayerId (int, the client that made the change), NewValue and OldValue (both string).
  • OnConCommandCreated - APIIOnConCommandCreated: CommandName (string).
  • OnCommandExecuteHook - APIIOnCommandExecuteHookEvent: Command (ref CCommand), HookMode (APIHookMode), settable Result (HookResult). HookMode tells you whether this is the Pre or the Post pass, and Result can only be changed in Pre.
  • 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

ClientKind and KeyKind

Two enums are carried by event objects rather than configured:

APIClientKind is reported by IOnClientPutInServerEvent.Kind:

ValueNumber
Player0
Bot1
Unknown2

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