IServerPluginCallbacks
IServerPluginCallbacks is the interface used by server plugins to hook game events. It is typically used in conjunction with IGameEventListener2.
See Server Plugins#Coding for implementation details.
Functions
Plugin state
bool Load(CreateInterfaceFn interfaceFactory, CreateInterfaceFn gameServerFactory)- Called when the plugin is loaded by the engine. This can happen either on initialization or when being re-loaded after being unloaded. The two parameters provide the interface factories that the plugin needs to operate. Returns false on error.
void UnLoad()- Called when a plugin is unloaded, use this to disable any asynchronous tasks and remove any callbacks you have registered with the engine (for example a game events listener). Additionally, this function will be called if false is returned by Load().
void Pause()- Called when the operation of the plugin is paused (i.e it will stop receiving callbacks but should not be unloaded).
void UnPause()- Called when a plugin is brought out of the paused state. You should re-enable any asynchronous events your plugin uses in this call
const char *GetPluginDescription()- This function should return a friendly string describing your plugin. Typically this would be its name and the author.
Server events
void LevelInit(char const *pMapName)- Called on level (map) startup, it is the first function called as a server enters a new level.
void ServerActivate(edict_t *pEdictList, int edictCount, int clientMax)- This is called when the server successfully enters a new level, this will happen after the LevelInit call. This call provides pointers to the list of edicts created on the server and the maxplayer count of the server.
void GameFrame(bool simulating)- Called once per server frame. Server performance is very sensitive to the execution time of this function so keep anything you do in this function to a minimum.
void LevelShutdown()- Called when a server is changing to a new level or is being shutdown. Remove any map specific allocations in this call. This can be called multiple times during a map change.
void OnQueryCvarValueFinished( QueryCvarCookie_t iCookie, edict_t *pPlayerEntity, EQueryCvarValueStatus eStatus, char *pCvarName, char *pCvarValue )- Called when a query from
IServerPluginHelpers::StartQueryCvarValue()finishes.iCookieis the value requested. void OnEdictAllocated(edict_t *edict)void OnEdictAllocated(const edict_t *edict)
Clients
PLUGIN_RESULT ClientConnect(bool *bAllowConnect, edict_t *pEntity, const char *pszName, const char *pszAddress, char *reject, int maxrejectlen)- Called when a client initially connects to a server. Set bAllowConnect to false to stop this user from connecting.
void ClientPutInServer(edict_t *pEntity, char const *playername)- Called when a client spawns into a server. This is called before the server spawn function.
void ClientActive(edict_t *pEntity)- Called after a client is fully spawned and configured by the Mod. Use this call to change any player specific settings.
void ClientDisconnect(edict_t *pEntity)- Called when a client disconnects from the server.
Bug:If a client disconnects very quickly after connecting, this function will not be called. [todo tested in?] void SetCommandClient(int index)- Called by the ConVar code to let you keep track of which client is entering a ConCommand. Use this index in ConCommands if you want to see who is running the command. As ConVar commands don't have an edict associated with them when they run you can use this index to look up the entity that is running the command. The index is one less than the entity index.
void ClientSettingsChanged(edict_t *pEdict)- Called when player specific cvars about a player change (for example the users name). Use this function to control what operations a user is allowed to perform to their settings (for example limiting usernames).
PLUGIN_RESULT ClientCommand(edict_t *pEntity, const CCommand &args)- Called when a remote client enters a command into the console. This should be used to provide commands to clients (and ConCommand used to implement server side only commands).
PLUGIN_RESULT NetworkIDValidated(const char *pszUserName, const char *pszNetworkID)- Called when the server retrieves a clients network ID (i.e Steam ID). Note that a clients network ID is not set on connect, you must wait for this callback before a users network ID is valid. The client name is passed into this function, you need to search the currently connected players to find the associated edict pointer. Note that the clients name can change between connect and id validation, you should use the entity index to track specific players. Note also that this function is NOT called for the local user when running a listen/non-dedicated server.
Related constructs
PLUGIN_RESULT- One of:
PLUGIN_CONTINUE- Keep going; no change
PLUGIN_OVERRIDE- Run the game's function, but use our return value instead (Note: This is in reference to arguments passed by reference, such as ClientConnect's bool *bAllowConnect)
PLUGIN_STOP- Don't run the game's function at all
QueryCvarCookie_tCreateInterfaceFnEQueryCvarValueStatus
IServerPluginHelpers
CreateMessage()
void CreateMessage( edict_t *pEntity, DIALOG_TYPE type, KeyValues *data, IServerPluginCallbacks *plugin )
This function displays the in-game messages you are probably used to seeing on servers. It can create either simple announcements, or menus from which a choice must be made with one of the number keys.
Bug:Weapon selection commands count as numbers even if the player has re-assigned them to totally different keys. Be aware that popping up a menu can cause great frustration both through confusion and the blocking of input. [todo tested in?]The function's arguments are:
edict_t *pEntity- Player to send message to
DIALOG_TYPE type- One of:
- DIALOG_MSG
- A plain and simple message
- DIALOG_MENU
- An options menu. If you use this, add sub keys (Todo: Called what?) to
datacontaining:string command- Client command to run if this item is selected
string msg- Option text
- DIALOG_TEXT
- A rich text message (Todo: What format? HTML?)
- DIALOG_ENTRY
- An entry box (Todo: What does this look like?)
- DIALOG_ASKCONNECT
- Ask the client to connect to a specified IP address. Only the "time" and "title" keys are used.
KeyValues *data- Raw data to send to the client. Can contain the following keys:
string title- The title text to display at the top of the message
string msg- The body of the message
color color- The color to display the message in; white by default
int level- The priority of the message, where 0 is highest (only one message can be displayed at any one time)
int time- Number of seconds the message should stay active. Min 10, max 200.
IServerPluginCallbacks *plugin
Confirm:The plugin you are calling from
StartQueryCvarValue()
QueryCvarCookie_t StartQueryCvarValue( edict_t *pEntity, const char *pName )
Call this to find out the value of a cvar on the client.
It is an asynchronous query, and it will call IServerPluginCallbacks::OnQueryCvarValueFinished when the value comes in from the client.
Store the return value if you want to match this specific query to the OnQueryCvarValueFinished call.
Returns InvalidQueryCvarCookie if the entity if invalid.
The function's arguments are:
edict_t *pEntity- Player to send message to
const char *pName- Cvar name
Other functions
void ClientCommand( edict_t *pEntity, const char *cmd )- Attempt to run a command on the client. In some games, only Commands marked FCVAR_SERVER_CAN_EXECUTE can be executed this way.
